Part I Network Layer Interface (NLI)

Chapter 1 STREAMS Overview

STREAMS defines a standard interface for character I/O within the kernel, and between the kernel and the rest of the system. STREAMS creates, uses and dismantles streams. A stream is a full-duplex processing and data transfer path between a driver in kernel space and a process in user space.

1.1 Overview

A stream is made up of three parts--a stream head, optionally one or more modules, and a driver. The stream structure is summarized in Figure 1-1. The stream head provides the interface between the stream and the user processes. The module processes data travelling between the stream head and the driver. The driver can be a device driver, which has associated hardware, or a software driver.

STREAMS facilities are available using a series of system calls, which interact with the driver.

Figure 1-1 STREAMS Format

For detailed information on STREAMS, refer to the STREAMS Programming Guide.

Chapter 2 About NLI

The Solstice X.25 Network Layer Interface (NLI) provides acces to the X.25 Packet Layer Protocol (PLP). The NLI defines the format that STREAMS messages must take when interfacing to the network layer. This allows for the easy construction of user level library software, and means that applications map conveniently onto the STREAMS format.

2.1 NLI Overview

The Solstice X.25 Network Layer Interface provides access to the X.25 Packet Layer Protocol (PLP). The NLI defines the format that STREAMS messages must take when interfacing to the network layer. This allows for the easy construction of user level library software, and means that applications map conveniently onto the STREAMS format.

Solstice X.25 applications use the putmsg and getmsg system calls to interact with the PLP driver.

Figure 2-1 NLI and STREAMS

Messages passed using NLI have both a control and a data part. Primitives and associated parameters are passed to the X.25 driver using the control part of the message. Data, if there is any, is contained in the data part of the message.

Figure 2-2 NLI Message Format

Solstice X.25 NLI provides the following:

• NLI messages

  These determine the format of the control parts of putmsg and getmsg, and are used to communicate with the network.

• A series of ioctls

  These communicate with the Solstice X.25 code, rather than with the network.

• A series of library functions

  These are not part of the NLI, but can be used along with it.

2.2 NLI Commands

Solstice X.25 NLI provides a series of NLI commands contained within C structures. These determine the format of the control parts of putmsg and getmsg. The NLI commands correspond to X.25 packet types, and are used to communicate with the network. For example, when an application passes down the NLI command N_CI to a stream using putmsg, this is translated into an X.25 Call Connect by the PLP module. When the PLP module receives a Connect Indication, it translates it into an N_CI command which is passed up to the application using a getmsg system call.

Table 2-1 summarizes the structures and their corresponding Packet Types and NLI Commands. Refer to the sections indicated for detailed information.

The following commands and structures are also provided. They do not correspond to X.25 packet types:

2.3 NLI ioctls

Solstice X.25 NLI provides a series of ioctls. These are used to communicate with the Solstice X.25 code itself, rather than with the network. For example, ioctls are used to gather statistics about a link, or to set the parameters to be used on a link. This distinguishes them from the NLI Commands given in Table 2-1. To use them together, you might use an ioctl to set the parameters to be used on a link and then use an NLI command to initiate a call over the link. The NLI ioctls can be used for the following purposes:

• Operating on the Network User Identifiers mapping table

• Reading and resetting statistics

• Getting status information

• Operating on the X.25 Routing Table

• Overriding settings made using x25tool

2.4 Support Functions

Solstice X.25 also includes a library of Sun-specific support functions that you can use when writing applications. These are not part of the NLI, but can be used in NLI applications.

2.5 Support for OSI Connection-Mode Network Service (OSI CONS)

The Solstice X.25 NLI can support applications which use the OSI Connection-Mode Network Service, as defined in X.223 and ISO 8878. To be consistent with these documents, this service is referred to as OSI CONS in this guide. This service provides the mapping between the OSI CONS primitives and the elements of the X.25 Packet Layer Protocol.

2.6 Addressing

When making straightforward X.25 calls, you need to work with DTE and LSAP addresses. When making OSI CONS calls, you use NSAP and LSAP addresses. See "6.3.1 xaddrf--Define Addressing" for more information.

2.7 Facilities and QOS Parameters

The X.25 Recommendations allow service providers to offer a number of optional facilities, that affect the way that calls are made and handled.

• Non-OSI extended addressing

• X.25 fast select request/indication with no restriction on response

• X.25 fast select request/indication with restriction on response

• X.25 reverse charging

• X.25 packet size negotiation

• X.25 window size negotiation

• X.25 network user identification

• X.25 Recognized Private Operating Agency selection

• X.25 Closed User Groups

• X.25 programmable facilities

• X.25 call deflection.

The following Quality of Service (QOS) parameters are available when writing OSI CONS applications:

• Throughput Class

• Minimum Throughput Class

• Target Transit Delay

• Maximum Acceptable Transit Delay

• Use of Expedited Data

• Protection

• Priority

• Receipt Acknowledgment

2.8 Operating System Support

Solstice X.25 9.2 will run on Solaris 7 or Solaris 8. It is not compatible with earlier versions of the Solaris operating system.

Chapter 3 Making and Receiving Calls

This chapter contains examples of how to make and receive calls. All of the examples involve the application opening a stream to the X.25 PLP Driver. Once the stream has been opened, it can be used for initiating, listening for, or accepting a connection. There is a one-to-one mapping between X.25 virtual circuits and PLP driver streams. Once a connection has been established on a stream, the stream cannot be used other than for passing data and protocol messages for that connection.

Sample code for making OSI CONS calls, dealing with Expedited Data and Resets and receiving a remote disconnect is given at the end of this section.

There are copies of the code samples referred to in this chapter in the /opt/SUNWconn/x25/samples.nli directory.

3.1 Making a Single Call

This section shows the process for making a single, straightforward call. The call being made is a standard X.25 call. It does not have to deal with Expedited Data or Resets. The disconnect is initiated locally. The steps for making a standard X.25 call are:

1. Open a stream on the /dev/x25 device:

   if ((x25_fd = open("/dev/x25", O_RDWR)) < 0) {
    	perror("Opening Stream");
    	exit(1);
    	}

2. Open a connection to the open stream.

   1. Allocate a Connect Request structure.

   2. Supply any quality of service and facilities parameters that are required.

   3. Set the called (and optionally calling) addresses.

   4. Pass the Connect Request down to the X.25 Driver.

   5. Wait for the connect confirmation or rejection

      #define FALSE 0
       #define TRUE 1
       #define CUDFLEN 4
       #define DBUFSIZ 128
       #include <memory.h>
       #include <netx25/x25_proto.h>
       struct xaddrf called = { 0, 0, { 14, { 0x23, 0x42, 0x31, 
       0x56, 0x56, 0x56, 0x56 }}, 0 };
        /* no flags
         * DTE = "23423156565656", null NSAP
         */
       struct xcallf conreq;
       struct strbuf ctlblk, datblk;
       struct xdataf data; 
      
       main ()
       {
          .
          /* Convert link to internal format */
          called.link_id = 0;
          conreq.xl_type = XL_CTL;
          conreq.xl_command = N_CI;
          conreq.CONS_call = FALSE;
          /* This is not a CONS call */
          conreq.negotiate_qos = FALSE;
          /* Just use default */
          memset(&conreq.qos, 0, sizeof(struct qosformat));
          memcpy(&conreq.calledaddr, &called, sizeof(struct xaddrf));
          memset(&conreq.callingaddr, 0, sizeof(struct xaddrf));
        }

      In the example, the entire QOS field is zeroed, allowing for future additions to the structure. Setting the calling address to null, as shown, leaves the network to fill in this value. For more information on QOS and Facilities, see "2.7 Facilities and QOS Parameters".

3. Send the message on the stream using the putmsg system call, passing any call user data in the data part of the message:

   char cudf[CUDFLEN] = { 1, 0, 0, 0 };
    ctlblk.len = sizeof(struct xcallf);
    ctlblk.buf = (char *) &conreq;
    datblk.len = CUDFLEN;
    datblk.buf = cudf;
    if (putmsg(x25_fd, &ctlblk, &datblk, 0) < 0 ) {
    	perror("Call putmsg");
    	exit(1);
    	}

4. Transfer the data.

   In the data transfer phase, access is given to:

   • the Q-bit, to support X.29-like services

   • the M-bit, to signal packet fragmentation

   • the D-bit, to request confirmation of data delivery

   • Expedited data, to support X.29 and OSI CONS.

     Normal and Q-bit data is sent and received using the N_Data message and may be acknowledged using the N_DAck message. Expedited data uses the N_EData message, and is acknowledged using an N_EAck message.

     Once a connection has been successfully opened on a stream, sending a data packet is straightforward:

     char datbuf[DBUFSIZ];
      /* Copy data into datbuf[] here*/
      data.xl_type = XL_DAT;
      data.xl_command = N_Data;
      data.More = data.setQbit = data.setDbit = FALSE;
      ctlblk.len = sizeof(struct xdataf);
      ctlblk.buf = (char *) &data;
      datblk.len = DBUFSIZ;
      datblk.buf = datbuf;
      retval = putmsg(x25_fd, &ctlblk, &datblk, 0); 

     Normally, the call to putmsg blocks if there are flow control conditions in the connection which lead to either a full queue at the stream head, or a lack of streams resources. To avoid blocking due to a full queue, open the stream with the option O_NDELAY flagged. In this case, putmsg returns immediately, and the failure is signalled by a return value (retval) of EAGAIN.

     This procedure allows the application to carry out other processing (for example, receiving data) before trying again. The best method to use depends on the nature of the application.

5. Close the connection.

   In this example, closure is initiated locally. The application sends a Disconnect Request (N_DI) message on the stream. Unless this is being used to reject an incoming call the X.25 driver signals that it has observed the message. It does this by sending a Disconnect Confirm upstream when it receives the Clear Confirm. In this way, the upper components can be certain that no messages will follow the Disconnect.

   In the case of rejection, the connection identifier supplied on the Connect Indication must be returned in the disconnect message. The disconnect (reject) is not acknowledged in this case.

   As in the case of a remote disconnection, once the response has been received the stream becomes idle, and remains in this state until the application sends out another control message. This may be to close the stream, or to initiate a new Listen or Connect request on it. The application should, however, not send any of these messages until it receives the Disconnect Response.

   As described in "6.4.7 N_DI--Clear Request/Indication ", a disconnect collision may occur. If this happens, no Clear Confirm is sent.

   /* Coded and sent disconnect request, process response */
    struct xdiscf  *dis_ind;
    struct xdcnff  *dis_cnf;
    struct extraformat *xqos = (struct extraformat *)0;
    if ( hdrptr->xl_type == XL_CTL ) {
    	switch( hdrptr->xl_command ) {
    /* Disconnect Collision */
    		case N_DI:
    			dis_ind = (struct xdiscf*)hdrptr; 
    			xqos = &dis_ind->indicatedqos.xtras;
    			break;
    /* Disconnect Confirmation */
    		case N_DC:
    			dis_cnf = (struct xdcnff*)hdrptr; 
    			xqos = &dis_cnf->indicatedqos.xtras;
    			break;
    		default:
    			return;
    		}
    	if ( xqos ) {
    /*
      * Print any charging information returned
      */
    		if ( xqos->chg_cd_len ) { 
    /* Print out Call Duration from chg_cd_field */
    			}
    		if ( xqos->chg_mu_len ) { 
    /* Print out Monetary Unit from chg_mu_field */
    			}
    		if ( xqos->chg_sc_len ) { 
    /* Print out Segment Count from chg_sc_field */
    			}
    		}  /* end if (xqos) */
    	}  /* end if (hdrptr->xl_type==XL_CTL) */

3.2 Receiving Data

In the same way as sending data, data reception is straightforward. When data is received with the D-bit set, action may be required by the application. When the initial Call Request is sent, it may request that data confirmation be at the application-to-application level. If application-to-application confirmation is agreed upon, then on receiving a packet with the D-bit set, an application must send a Data Acknowledgment (N_DAck) message.

This example prints out incoming data as a string, if the Q-bit is not set:

S_X25_HDR *hdrptr;
 struct xdataf *dat_msg;
 struct xdatacf *dack;
 for(;;) {
 	if (getmsg(x25_fd, &ctlblk, &datblk, &getflags) < 0) {
 		perror("Getmsg fail");
 		exit(1);
 		}
 hdrptr = (S_X25_HDR *) ctlbuf;
 if (hdrptr->xl_type == XL_CTL) {
 /* Deal with protocol message as required - 
  * see below
  */
 	}
 if (hdrptr->xl_type == XL_DAT) {
 	dat_msg = (struct xdataf *) ctlbuf;
 	switch (dat_msg->xl_command) {
 		case N_Data: 
 			if (dat_msg->More)
 				printf("M-bit set \n");
 			if (dat_msg->setQbit)
 				printf("Q-bit set \n");
 			else  {
 				if (dat_msg->setDbit) 
 					printf("D-bit set \n");
 				for (i = 1;i<datblk.len; i++) 
 					printf("%c", datbuf[i]);
 /* 
  * If application to application 
  * Dbit confirmation was negotiated 
  * at call setup time,
  * send an N_DAck 
  */
 				if (app_to_app && dat_msg->setDbit) { 
 					dack = (struct xdatacf *)malloc(sizeof(struct xdatacf));
 					memset((char *)dack 0, sizeof(struct xdatacf)); 
 					dack- >xl_command = N_DAck; 
 					dack->xl_type = XL_DAT; 
 					ctlblk->len = sizeof(struct xdatacf); 
 					ctlblk->buf = (char *)dack;  
 					datblk->len = 0;
 					datblk->buf = (char *)0; 
 					putmsg(x25_fd, &ctlblk, &datblk, &getflags);
 					} 
 				} /* end else */
 			break;
 		case N_EData: 
 			printf("***Expedited data received \n");
 /* Must deal with it */
 			break;
 		case N_DAck: 
 			printf("***Data Acknowledgment received \n");
 			break;
 		default: 
 			break;
 		} /* end switch */
 	} /* end if */
 } /* end for */

3.3 Additional Call Information

The example in "3.1 Making a Single Call", is of a relatively straightforward call. Procedures for making a call using OSI CONS, for receiving expedited data, for dealing with resets and for receiving remotely initiated disconnects are given in the following sections. These can be integrated into the example above, as required.

3.3.1 Opening connections for OSI CONS Calls

The following example opens a connection for an OSI CONS call:

#define FALSE	0
 #define TRUE	1
 #define CUDFLEN 4
 #define EXPLEN 4
 #include <memory.h>
 #include <netx25/x25_proto.h>
 struct xaddrf called = { 0, 0, {14, { 0x23, 0x42, 0x31, 0x56, 
 0x56, 0x56, 0x56 }}, 0};
 /* Subnetwork "A" (filled in later), no flags, 
   * DTE = "23423156565656", null NSAP  */
 struct xcallf conreq;
 struct strbuf, ctlblk, datblk;
 struct xedataf exp; 

 main ()
 {
    .
    .
    .
    called.link_id = 0;
    /*
     * snidtox25 only fails if a 
     * NULL string is passed to it 
     */
    conreq.xl_type = XL_CTL;
    conreq.xl_command = N_CI;
    conreq.CONS_call = TRUE;
    /* This is a CONS call */
    conreq.negotiate_qos = TRUE;
    /* Negotiate requested */
    memset(&conreq.qos, 0, sizeof (struct qosformat));
    conreq.qos.reqexpedited = TRUE;  /* Expedited requested */
    conreq.qos.xtras.locpacket = 8;  /* 256 bytes */
    conreq.qos.xtras.rempacket = 8;  /* 256 bytes */
    memcpy(&conreq.calledaddr, &called, sizeof(struct xaddrf));
    memset(&conreq.callingaddr, 0, sizeof(struct xaddrf));
    .
    .
    .
 }

When negotiate_qos is true (non-zero), setting the QOS fields to zero means that the connection uses defaults for QOS and Facilities. If required, these can be set to different values but it is recommended that the entire QOS structure be zeroed first as shown. This is preferable to setting each field individually, as it allows for any future additions to this structure. Setting the calling address to null leaves the network to fill this value in.

The message is sent on the stream using the putmsg system call, with any call user data being passed in the data part of the message:

char cudf[CUDFLEN] = { 1, 0, 0, 0 };
 ctlblk.len = sizeof(struct xcallf);
 ctlblk.buf = (char *) &conreq;
 datblk.len = CUDFLEN;
 datblk.buf = cudf;
 if (putmsg(x25_fd, &ctlblk, &datblk, 0) < 0 ) {
 	perror("Call putmsg");
 	exit(1);
 	}

At this stage, the application should wait for a response to the Call Request. The response may be either a Connect Confirmation or a Disconnect (rejection) message.

3.3.2 Receiving Expedited Data

The preceding example allows for the possibility of receiving expedited data messages, which are carried in X.25 interrupt packets. These must be dealt with appropriately. Since only one expedited data packet can be outstanding in the connection at any time, its sender is prevented from sending any further such messages until the receiver has acknowledged it. The receiver does this by sending an Expedited Acknowledgment (EAck) message. The EAck is sent in the same way as an ordinary data packet, but with no data part.

If an application does not need to use the expedited data capability, then it responds to receiving an EData by resetting or closing the connection.

When sending expedited data, the application must wait for an acknowledgment before requesting further expedited transmissions.

char expdata[]= {1, 2, 3, 4};
 exp.xl_type= XL_CTL;
 exp.xl_command= N_Edata;
 ctlblk.len= sizeof (struct xedataf);
 ctlblk.buf= (char *) &exp;
 datblk.len= EXPLEN;
 datblk.buf= expdata;
 if (putmsg(x25_fd, &ctlblk, &datblk, 0) < 0) {
 	error("Exp putmsg");
 	exit(1);
 	}
 for (;;) {
 	if (getmsg(x25_fd, &ctlblk, &datblk, &getflags) < 0) {
 	perror("Getmsg fail");
 	exit(1);
 	}
 hdrptr = (S_X25_HDR *) ctlbuf;
 if (hdrptr->xl_type == XL_CTL) {
 /* Deal with protocol message as required */
 	}
 if (hdrptr->xl_type == XL_DAT) {
 	dat_msg = (struct xdataf *) ctlbuf;
 	switch (dat_msg->xl_command) {
 		case N_Data:
 /* process more data */
 			break;
 		case N_EData:
 			printf("***Expedited data received \n");
 /* Must deal with */
 .... send N_EAck ....
 			break;
 		case N_EAck:  /* Expedited data received */
 /* Further N_Edata can now be sent */
 			break;
 		default:
 			break;
 		}
 	}

3.3.3 Dealing with Resets and Interrupts

Resets and Interrupts are dealt with in a similar way, except that there is no data passed with a Reset Request. When a Reset Request or Interrupt is issued, the application must wait for the acknowledgment, as for an expedited request. However, until this is received, the only action that can be taken is to issue a Disconnect Request.

The diagnostic field in a Reset Request or Interrupt contains the reason for issuing the reset. Standard values for this are defined in the include file <netx25/x25_proto.h>, although the application can set any value. See Chapter 9, Error Codes for more details.

When a Reset Indication is received, there are only two valid actions that may be taken:

• send a Reset Confirmation message to acknowledge the reset

• send a Disconnect Request

In either case, pending data is flushed from the queue.

Reset Indications can be dealt with as part of the general processing of incoming messages, as shown in the following disconnect handling example.

#include<netx25/x25_proto.h>
 struct xrstf rst;
 S_X25_HDR *hdrptr;
 rst.xl_type= XL_CTL;
 rst.xl_command= N_RI;
 rst.cause= 0;
 rst.diag= NU_RESYNC;
 ctlblk.len= sizeof (struct rstf);
 ctlblk.buf= (char *) &rst;
 if (putmsg(x25_fd, &ctlblk, 0, 0) < 0) {
 	perror(" putnmsg");
 	exit(1);
 	}
 	for (;;) {
 		if (getmsg(x25_fd, &ctlblk, &datblk, &getflags) < 0) {
 			perror("Getmsg fail");
 			exit(1);
 			}
 		hdrptr = (S_X25_HDR *) ctlbuf;
 		if (hdrptr->xl_type == XL_CTL) {
 			continue;
 			}
 		switch (hdrptr->xl_command) {
 			case N_RC:  /* Reset complete */
 /* Enter data transfer */
 				break;
 			default:
 				break;
 			}  /* end switch */
 		} /* end for */

Control messages, like resets and interrupts, take higher priority than normal data messages, both internally in the PLP driver, and across the network.

3.3.3.1 Receiving a Remote Disconnect

If the remote end initiates a Disconnect, then a Disconnect Indication (N_DI) message (or possibly an N_Abort message, see "6.4.1 N_Abort--Abort Indication") is received at the NLI. The application need not acknowledge this message since, after sending a Disconnect, the X.25 driver silently discards all messages received except for connect and accept messages. These are the only meaningful X.25 messages on the stream after disconnection.

The receiver of a Disconnect Indication should ensure that enough room is available in the getmsg call to receive all parameters and, when present, up to 128 bytes of Clear User Data. Handling such a Disconnect event would normally be part of the general processing of incoming messages.

The following example could be combined with the code from the data transfer example in the previous section.

struct xdiscf *dis_msg;
 if (hdrptr->xl_type == XL_CTL) {
 	switch (hdrptr->xl_command) {
 /* Other events/indications dealt with 
   * here - e.g. Reset Indication (N_RI)
   */
 		case N_DI: 
 			dis_msg = (struct xdiscf *) hdrptr;
 			printf("Remote disconnect, cause = %x, diagnostic = %x \n",
 			dis_msg->cause, dis_msg->diag);
 /* Any other processing needed here - 
   * e.g. change connection state
   */
 			return;
 		case N_Abort:
 			printf("***Connection Aborted \n");  /* etc.  */
 			return;
 		default:
 			break;
 		}
 	} 

It is guaranteed that no X.25 interface messages are sent to the application once a disconnect message has been passed up to it, wherever the message came from.

Although at this stage the stream is idle, it is in an open state and remains so until some user action. This could be to close the stream, or to initiate a new Listen or Connect request on it.

Chapter 4 Listening for Calls

This chapter contains examples of how to listen for single or multiple incoming calls and then accept or reject the call.

There are copies of the code samples referred to in this chapter in the /opt/SUNWconn/x25/samples.nli directory.

4.1 Listening for a Single Call

The steps for listening for a single incoming call are:

1. Send an N_Xlisten message to the X.25 driver.

   This should carry the called address list in which the application is interested.

2. Wait for the response to the Listen Request.

   The l_result flag will indicate success or failure. If the l_result flag indicates failure, the application can decide either to close the stream or to try again later.

3. Wait for Connect Indication messages from the X.25 driver.

4. Decide whether to accept on this or a different stream.

5. Negotiate facilities and QOS, if required.

   A Connect Confirmation message carrying the appropriate connection identifier is then passed down on the stream on which the connection is being accepted.

6. Construct the listen message.

   The listen message has two parts. Construct the control part of the message like this:

   struct xlistenf lisreq;
    lisreq.xl_type = XL_CTL;
    lisreq.xl_command = N_XListen;
    lisreq.lmax = 1;

   In this example, lmax has the value of 1, indicating that only one Connect Indication is to be handled at a time.

   The data part of the message contains the sequence of bytes that specify the Call User Data string and address(es) which are to be listened for. The simplest case for this would be to set "Don't Care" values for both the CUD and address:

   int lislen;
    char lisbuf[MAXLIS];
    lisbuf[0] = X25_DONTCARE; /* l_cumode*/
    lisbuf[1] = X25_DONTCARE; /* l_mode*/
    lislen = 2;

   Alternatively, to set the CUD to match exactly the (X.29) value defined in the array cudf[] (0x01000000), and the NSAP to match any sequence starting 0x80, 0x00, the following would be used:

   lislen = 0;
    lisbuf[lislen++] = X25_IDENTITY; /* l_cumode */
    lisbuf[lislen++] = CUDFLEN; /* l_culength */
    memcpy(&(lisbuf[lislen]), cudf, CUDFLEN); /* l_cubytes */
    lislen += CUDFLEN;
    lisbuf[lislen++] = X25_STARTSWITH; /* l_mode */
    lisbuf[lislen++] = X25_NSAP; /* l_type */
    lisbuf[lislen++] = 4; /* l_length */
    lisbuf[lislen++] = 0x80;  /* l_add */
    lisbuf[lislen++] = 0x00; 

   Or, to accept any CUD Field, with a DTE of 2342315656565:

   #define MY_DTE_LEN 13
    #define MY_DTE_OCTETS 7
    char my_dte[MY_DTE_OCTETS] = {0x23,0x42,0x31,0x56,0x56,0x56,0x50};
    lislen = 0;
    lisbuf[lislen++] = X25_DONTCARE;  /* l_cumode */
    lisbuf[lislen++] = X25_IDENTITY; /* l_mode */
    lisbuf[lislen++] = X25_DTE; /* l_type */
    lisbuf[lislen++] = MY_DTE_LEN; /* l_length */
    memcpy(&(lisbuf[lislen]), my_dte, MY_DTE_OCTETS); /* l_add */
    lislen += MY_DTE_OCTETS;

   ---

   Note -

   The l_add field uses packed hexadecimal digits and the l_length value is actually the number of semi-octets, whereas the l_culength field specifies the length of the l_cubytes field in octets.

   ---

7. Send the Listen Request down the open stream:

   ctlblk.len = sizeof(struct xlistenf);
    ctlblk.buf = (char *) &lisreq;
    datblk.len = lislen;
    datblk.buf = lisbuf;
    if (putmsg(x25_fd, &ctlblk, &datblk, 0) < 0) {
    	perror("Listen putmsg failure");
    	return -1;
    	}

8. Wait for the listen response; the result flag indicates success or failure:

   #define DBUFSIZ 128
    #define CBUFSIZ MAX( sizeof(struct xccnff), sizeof(struct xdiscf) )
    struct xlistenf *lis_msg;
    ctlblk.maxlen = CBUFSIZ; /* See 4.1 above for declarations */
    ctlblk.buf = ctlbuf;
    datblk.maxlen = DBUFSIZ;
    datblk.buf = datbuf;
    for(;;) {
    	if (getmsg (x25_fd, &ctlblk, &datblk, &getflags) < 0) {
    		perror("Listen getmsg failure");
    		return -1;
    		}
    	lis_msg = (struct xlistenf *) ctlbuf;
    	if ((lis_msg->xl_type == XL_CTL) &&  (lis_msg->xl_command == N_XListen))
    		if (lis_msg->l_result != 0) {
    			printf("Listen command failed \n");
    			return -1;
    			}
    		else {
    			printf("Listen command succeeded \n");
    			return 0;
    			}
    	} 

   Cancelling a Listen Request is done in the same way, except that no data is passed with the request. It cancels all successful Listens that have been made on that stream.

9. Once the listening application has received a Listen Response indicating success, it should wait for incoming Connect Indications.

   When an N_CI message arrives, the application should inspect its parameters-- address, call user data, facilities, quality of service, and so on--then decide whether to accept or reject the connection.

   A listening application can accept a call either on the stream the indication arrived on, or on some other stream. This other stream can be one which is already open and free, or the application can open it.

   Whatever method is used for the accept, the identifier conn_id in the Connect Indication message must be copied into the accept message for matching by the X.25 driver. If this identifier in the accept message does not match, a Disconnect is sent to the accepting application. This causes the resource to hang on the stream on which the incoming call was sent, since the connection is never accepted.

   A listening application can reject the call by sending a N_DI message down the stream on which the Connect Indication arrived. A Connect Indication cannot be rejected on a different stream. The connection identifier must be quoted in the message for matching, since there may be several Connect Indications passed to the listening application. If there is no match for the rejection, the message is silently discarded.

   The rejecting listener can request one of two actions in response to the disconnect:

   • Request immediate disconnect. The application sets the reason field to NU_PERMANENT (0xF5).

   • Search for further matching listeners. The application set the reason field to any value except 0xF5.

     The following code example shows how to reject an incoming call:

     struct xcallf  *conind;
      struct xdiscf disc_msg; 
      /* Use getmsg to receive the Connect Indication
       * use conind to point to it
       */
      disc_msg.xl_type = XL_CTL;
      disc_msg.xl_command = N_DI;
      disc_msg.conind = conind->conind;
      disc_msg.cause = cause; /* cause to be returned */
      disc_msg.diag = diag; /* diagnostic to be returned */
      if (disc_immed) /* no more searches */
      	disc_msg.reason = NU_PERMANENT; /* 0xF5 */
      /* Send Rejection down stream with putmsg */

     ---

     Note -

     The application must not accept a connection on a listening stream that is capable of handling more than one Connect Indication at one time if there could subsequently be other Connect Indications to be handled on that stream. For example, the application issues a Listen Request to handle three Connect Indications at one time. A Connect Indication is received and sent to the application on the listen stream. The application must not accept this connection on the listen stream because there could be two more Connect Indications that can be sent subsequently.

     ---

10. Negotiate any facilities or OSI CONS QOS parameters required.

    To do this, set the negotiate_qos flag in the Connect Response message. The values received should then be copied into the response, and those facilities and/or parameters (and any related flags) for which a different value is desired should then be altered (see "2.7 Facilities and QOS Parameters"). Copy the entire QOS structure from the indication to the response. This allows for future additions to this structure.

    An example of negotiation is shown below. Here all the values are copied as indicated, except the packet size, which is negotiated down to 256 if it is flagged as negotiable, and is greater than 256:

    struct xcallf *conind;
     struct xccnff conresp;
     /* Do a getmsg etc to receive the Connect Indication,
      * assign conind to point to it.
      */
     conresp.xl_type = XL_CTL;
     conresp.xl_command = N_CC;
     conresp.conn_id = conind->conn_id;  /* Connection identifier */
     conresp.CONS_call = TRUE /* This is a CONS call */
     memset(&conresp.responder, 0, sizeof(struct xaddrf));
     /* Let network fill in responding addr */
     conresp.negotiate_qos = TRUE;
     memcpy (&conresp.rqos, &conind->qos, sizeof (struct qosformat) );
     if (conind->qos.xtras.pwoptions & NEGOT_PKT) {
     	if (conind->qos.xtras.rempacket > 8)
     		conresp.rqos.xtras.rempacket = 8; 
     	if (conind->qos.xtras.locpacket > 8)
     		conresp.rqos.xtras.locpacket = 8;
     	}
     /* Set any other values to be negotiated here,
      * then send the response down with a putmsg.
      */

    Alternatively, the application may decide to accept (agree with) the indicated values, in which case the negotiate_qos flag is set to zero.

    If a connection is never established on a listening stream (using a matching accept) then that stream remains listening on the address list supplied. On the other hand, once an established connection has been disconnected, the stream does not return to a listening state. Instead, it remains open in an idle state. If the application needs to listen again, then the listen message must be re-sent. Rejection does not alter the listening state of the stream.

4.2 Listening for Multiple Incoming Calls

Sample code for a listener that can handle several incoming PAD calls simultaneously is provided in the file /opt/SUNWconn/x25/samples.nli/listen.c. Listeners to handle other types of incoming calls are similar. The steps are:

1. Define the values you need.

   Specify the maximum number of simultaneous calls you want to allow. Set the maximum number of simultaneous calls depending on the processor power available to you and the number of calls you expect to need to handle.

2. Open the X.25 device.

   The open_stream() function does this. It requests notification from the kernel when there is incoming data on the stream.

3. Listen for incoming data.

   The do_listen() function specifies the information used to decide what to do with an incoming call. The example shows two ways of doing this, one simple, the other more complex. In the simple example, the program listens for any call user data beginning with the four BCD digits 1234.

4. Wait for incoming calls.

   To do this, call the getmsg() function. If an incoming call arrives that matches the criteria that you specified in step 1, the X25 driver will send an N_CI indication. At this point, you could choose to do some more sophisticated checking. The example program includes a function called try_next() that tells the X.25 driver to see if the connect message is destined for another application, and a function called reject_call() that tells the X.25 driver to reject the call.

5. Accept the incoming call.

   Assuming the call is valid, the accept_call() function is used to accept it. Note that when accepting incoming data, the application must copy the call indication identifier into the connect confirm sent to the kernel.

6. Handle the incoming call as appropriate.

   The sample code contains an example of a call that is handled by printing a message and closing the device (which closes the connection).

7. Exit the program when finished.

Chapter 5 Getting Statistics

This chapter contains an example of a program for gathering statistics. By using the ioctls described in Chapter 7, Network Layer ioctls, you can write programs that specify more precisely what kind of statistics you want to gather and whether they should apply to a particular link or virtual circuit.

5.1 Sample Program

There is a copy of this code sample in the /opt/SUNWconn/x25/samples.stats directory.

The steps for writing this kind of program are:

1. Include the streams and X.25 header files.

2. Specify the location of the X.25 devices file descriptor.

3. Define a structure for containing the statistics.

   In the example these are per-link X.25 statistics.

4. Open the X.25 driver.

5. Define the fields required by the ioctl(s) you are using.

   In the example, this is N_getlinkstats, which retrieves per link X.25 statistics.

6. Specify where you want to gather statistics from.

   For example, N_getlinkstats requires you to give a link number.

7. Gather the statistics.

   How you do this depends on which ioctls you are using.

8. Display, or otherwise make use of, the statistics that have been gathered.

    /************************************************************
     * Copyright 20 Apr 1995 Sun Microsystems, Inc. All Rights Reserved
     *
     * This example shows how to open X25 driver,
     * get X25 per_link statistics,
     * and display (as an example) the number of transmit and
     * received CALL packets.
     *
     * Many more information are available for X25 through this ioctl.
     * Many other ioctls permit to get :
     * - Global stats for : IXE, X25 packet layer protocol, LAPB, LLC2, and MLP
     * - Per-link stats for : X25, LAPB, LLC2 and MLP
     * - Per-VC stats
     * Some other ioctls permit to reset those statistics.
     *
     ************************************************************/
   
    /*
     * General includes for streams
     */
    #include <fcntl.h>
    #include <stdio.h>
    #include <sys/types.h>
    #include <sys/stat.h>
    #include <sys/stropts.h>
    #include <sys/stream.h>
   
    /*
     * the following includes are specific to X25
     */
    #include <netx25/uint.h>
    #include <netx25/x25_proto.h>
    #include <netx25/x25_control.h>
   
    /*
     * location of x25 device file descriptor
     */
    #define X25_DEV "/dev/x25"
   
    /* used to open X25 device */
    int x25_fd;
   
    /*
     * io control structure used for all stream ioctl
     * see STREAM programmer's guide for more information about this structure.
     */
    struct strioctl      ioc;
   
    /*
     * this structure to be used to collect X25 per-link stats
     */
    struct perlinkstats  x25_s;
   
    main()
    {
    	/*
    	 * open x25 driver
    	 */
    	x25_fd = open(X25_DEV, O_RDONLY);
    	if (x25_fd == -1)
            {
    			perror("Failed to access X25 driver.\n");
    			exit(1);
    	}
   
    	/*
    	 * set the general info for ioctl
    	 */
    	ioc.ic_cmd = N_getlinkstats;
    	ioc.ic_len = sizeof(x25_s);
    	ioc.ic_dp = (char *) &x25_s;
   
    	/*
    	 * Set the link id.
    	 * Specify the link number where to gather statistics.
    	 * (2 in that particular case)
    	 */
    	x25_s.linkid = 2;
   
    	/*
    	 * perform the STREAMS ioctl
    	 */
    	if (ioctl(x25_fd, I_STR, &ioc) < 0)
    			{
    			perror("Failed to gather X25 per-link statistics");
    			exit(2);
    	}
   
    	/*
    	 * display some statistics
    	 */
    	printf("X25 statistics for link number 2\n");
    	printf("Number of CALL transmitted %10ld\n",
    			x25_s.mon_array[cll_out_s]);
    	printf("Number of CALL received %10ld   \n",
    			x25_s.mon_array[cll_in_s]);
    }

Chapter 6 NLI Commands and Structures

Solstice X.25 NLI provides a set of NLI commands. These are contained within C structures, which determine the format of the control parts of putmsg and getmsg. The NLI commands correspond to X.25 packet types. NLI commands are used to communicate with the network. For example, when an application passes down the NLI command N_CI to a stream using putmsg, this is translated into an X.25 Call Request by the PLP module. When the PLP module receives a Connect Indication, it translates it into an N_CI message which is passed up to the application using a getmsg system call.

The header files used by the NLI commands and structures are contained in the /usr/include/netx25 directory.

6.1 Commands and Structures Tables

Table 6-1 summarizes the NLI commands and their corresponding Packet Types and C structures:

These commands and structures in do not correspond to X.25 packet types:

All of the structures listed in Table 6-1 and Table 6-2 are defined in the x25_primitives C union.

In addition to the structures that have a one-to-one mapping with NLI commands, Solstice X.25 provides a number of structures that are used by several of the commands. These are related to addressing and facilities, and are listed in Table 6-3:

6.2 x25_primitives C Union

The Solstice X.25 software provides a series of data structures that determine the control part of messages passed across the NLI. The format of the control part of messages passed across the NLI is defined by structures in the following C union.

union X25_primitives {
      struct xcallf xcall; /* Connect Request/Indication */
      struct xccnff xccnf; /* Connect Confirm/Response */
      struct xdataf xdata; /* Normal, Q-bit, or D-bit data */
      struct xdatacf xdatac; /* Data ack */
      struct xedataf xedata; /* Expedited data */
      struct xedatacf xedatac; /* Expedited data ack */
      struct xrstf xrst; /* Reset Request/Indication */
      struct xrscf xrscf; /* Reset Confirm/Response */
      struct xdiscf xdisc; /* Disconnect Request/Indication */
      struct xdcnff xdcnf; /* Disconnect Confirm */
      struct xabortf abort; /* Abort Indication */
      struct xlistenf xlisten; /* Listen Command/Response */
      struct xcanlisf xcanlis; /* Cancel Command/Response */
      struct pvcattf pvcatt; /* PVC Attach */
      struct pvcdetf pvcdet; /* PVC Detach */
  }; 

All structures begin with the same members, as shown below:

typedef struct xhdrf {
      unsigned char xl_type; /* XL_CTL/XL_DAT */
      unsigned char xl_command; /* Command */
 } S_X25_HDR; 

Messages to and from applications are classified as control messages or data messages. xl_type indicates whether a message is control or data using the values XL_CTL for control and XL_DAT for data. Within each classification, the message identity is indicated by the xl_command qualifier. The combination of xl_type and xl_command must be consistent.

When sending an NLI command to the x25 driver using putmsg, the size of the data structure is determined by the command, and clearly is known in advance. The .len member of the control buffer is used to hold this value, and the.maxlen member is not used.

When reading a message with the getmsg call, the type of message cannot be known before it is received, so a buffer large enough to hold any message should be supplied. Put the size of this buffer in the.maxlen member of the control buffer structure. The actual size of the message received will be placed in the.len member on return from the getmsg call. To ensure that the buffer will be large enough, declare it as being of type union X25_primitives.

Example 6-1 shows how a getmsg can be constructed.

Example 6-1 Constructing a getmsg

#include <stream.h>
 #include <netx25/dx25_proto.h>


 struct strbuf ctlb;
 struct strbuf datab;

 union X25_primitives buffer;
 char data_buf[DATALEN];

  .
  .
  .

 ctlb.maxlen = sizeof (union X25_primitives);
 ctlb.buf = (char *)buffer;

 flag = MSG_ANY;
 datab.maxlen = DATALEN;
 datab.buf = data_buf;

 getmsg (x25_fd, &ctlb, &datab, flag);

 switch ((S_X25_HDR *)&buffer->xl_type) {
 	case N_Abort:
 			/* treat 'buffer' as an Abort message
 			 * datab.len should be 0
 			 */
 		break;

 	case N_CI:
 			/* Treat 'buffer' as a Connect Indication
 			 * data_buf[] contains Call User Data
 			 * datab.len equals length of Call User Data
 			 */
 			break;

 	.
 	.
 	.

 	};

6.3 Generic Structures

The structures described in this section define addressing, facilities and QOS and are used by a number of the commands described in "6.4 NLI Commands".

6.3.1 xaddrf--Define Addressing

Addressing is defined by the xaddrf structure:

Example 6-2 xaddrf Structure

#define NSAPMAXSIZE 20

 struct xaddrf {
        uint32_t           link_id;
        unsigned char           aflags;
        struct lsapformat       DTE_MAC;
        unsigned char           nsap_len;
        unsigned char           NSAP[NSAPMAXSIZE];
}

The members in the xaddrf structure are:

6.3.2 lsapformat--Define an LSAP

The LSAP is defined by the lsapformat structure:

Example 6-3 lsapformat Structure

#define LSAPMAXSIZE 9

 struct lsapformat {
 			uint8						lsap_len;
 			uint8						lsap_add[LSAPMAXSIZE];
 }; 

The members of the lsapformat structure are:

6.3.3 extraformat--Define Standard X.25 Facilities

Standard X.25 facilities are defined by the extraformat structure:

Example 6-4 extraformat Structure

#define MAX_NUI_LEN   64
 #define MAX_RPOA_LEN  8
 #define MAX_CUG_LEN   2
 #define MAX_FAC_LEN   109
 #define MAX_TARIFFS   4
 #define MAX_CD_LEN    MAX_TARIFFS * 4
 #define MAX_SC_LEN    MAX_TARIFFS * 8
 #define MAX_MU_LEN    16

 struct extraformat {
 /* extraformat structure */
         unsigned char     fastselreq;
         unsigned char     restrictresponse;
         unsigned char     reversecharges
         unsigned char     pwoptions;
         unsigned char     locpacket, rempacket;
         unsigned char     locwsize , remwsize;
         int               nsdulimit;
         unsigned char     nui_len;
         unsigned char     nui_field[MAX_NUI_LEN];
         unsigned char     rpoa_len;
         unsigned char     rpoa_field[MAX_RPOA_LEN];
         unsigned char     cug_type;
         unsigned char     cug_field[MAX_CUG_LEN];
         unsigned char     reqcharging;
         unsigned char     chg_cd_len;
         unsigned char     chg_cd_field[MAX_CD_LEN];
         unsigned char     chg_sc_len;
         unsigned char     chg_sc_field[MAX_SC_LEN];
         unsigned char     chg_mu_len;
         unsigned char     chg_mu_field[MAX_MU_LEN];
         unsigned char     called_add_mod;
         unsigned char     call_redirect;
         struct lsapformat called;
         unsigned char     call_deflect;
         unsigned char     x_fac_len;
         unsigned char     cg_fac_len;
         unsigned char     cd_fac_len;
         unsigned char     fac_field[MAX_FAC_LEN];
 };

The members of this structure are defined as follows:

6.3.4 qosformat--Define OSI CONS QOS Parameters

OSI CONS-related quality-of-service parameters are defined in the quosformat structure:

#define MAX_PROT 32
 struct qosformat {
 	unsigned char reqtclass;
 	unsigned char locthroughput, remthroughput;
 	unsigned char reqminthruput;
 	unsigned char locminthru, remminthru;
 	unsigned char reqtransitdelay;
 	unsigned short transitdelay;
 	unsigned char reqmaxtransitdelay;
 	unsigned short acceptable;
 	unsigned char reqpriority;
 	unsigned char reqprtygain;
 	unsigned char reqprtykeep;
 	unsigned char prtydata;
 	unsigned char prtygain;
 	unsigned char prtykeep;
 	unsigned char reqlowprtydata;
 	unsigned char reqlowprtygain;
 	unsigned char reqlowprtykeep;
 	unsigned char lowprtydata;
 	unsigned char lowprtygain;
 	unsigned char lowprtykeep;
 	unsigned char protection_type;
 	unsigned char prot_len;
 	unsigned char lowprot_len;
 	unsigned char protection[MAX_PROT];
 	unsigned char lowprotection[MAX_PROT];
 	unsigned char reqexpedited;
 	unsigned char reqackservice;
 	struct extraformat xtras;
 };

The members of the qosformat structure are defined as follows:

6.4 NLI Commands

This section describes the available NLI commands in alphabetical order. Refer to Table 6-1 for a summary of the available commands and related structures.

6.4.1 N_Abort--Abort Indication

Description

N_Abort is used when the X.25 driver needs to send a Disconnect to the application, but there is no resource available in the system to construct a full Disconnect Indication message. For this reason, this message should rarely be received. The control part of an Abort Indication message has a format defined in the xabortf structure. There is no data part.

This message only appears in a getmsg, never in a putmsg. Example 6-1 shows how a getmsg can be constructed.

The xabortf structure is shown below:

struct xabortf {
      unsigned char xl_type; /* Always XL_CTL */
      unsigned char xl_command; /* Always N_Abort */
 };

6.4.2 N_CC--Call Response/Confirmation

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;

 struct xccnff confirm;
 .
 .
 .
 ctlb.len = sizeof(struct xccnff);
 ctlb.buf = (char *)confirm;

 putmsg(x25_fd, &ctlb, NULL,0);

Description

N_CC is used when calls are being accepted. When used with putmsg, N_CC is a Call Response, when used with getmsg, it is a Call Confirmation. Example 6-1 shows how a getmsg can be constructed. When used with getmsg, ctlb.len is replaced by cltb.maxlen. The control part of the Call Request or Indication is defined by the xccnff structure. There is no data part.

The xccnff structure is shown below:

struct xccnff {
      unsigned char xl_type; /* Always XL_CTL */
      unsigned char xl_command; /* Always N_CC */
      int conn_id; /* The connection id quoted on the associated
                      indication. */
      unsigned char CONS_call; /* When set, indicates CONS call */
      unsigned char negotiate_qos; /* When set, negotiate
                                      facilities etc. else use
                                      indicated values */
      struct xaddrf responder; /* Responding address */
      struct qosformat rqos; /* Facilities and CONS qos: if
                                negotiate_qos is set */
 };

The members of the xccnff structure are:

6.4.3 N_CI--Call Request/Indication

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;
 struct strbuf datab;

 struct xcallf call;
 char          cud[MAX_LENGTH];
 .
 .
 .
 ctlb.len = sizeof(struct xcallf);
 ctlb.buf = (char *)call;

 datab.len = cudlen;
 datab.buf = cud;

 putmsg(x25_fd, &ctlb, &datab, 0);

Description

N_CI is used when calls are requested or indicated across the X.25 interface. When used with putmsg, N_CI is a Call Request, when used with getmsg, it is a Connect Indication. Example 6-1shows how a getmsg can be constructed. The control part of the Call Request or Indication is defined by the xcallf structure. The data part of the message will contain any call user data.

The xcallf structure is shown below:

struct xcallf {
 	unsigned char xl_type; /* Always XL_CTL */
 	unsigned char xl_command; /* Always N_CI */
 	int conn_id; /*connection id returned in Call Response or
                    Disconnect */
 	unsigned char CONS_call; /*When set, indicates a CONS call*/
 	unsigned char negotiate_qos; /* When set, negotiate
                                     facilities etc. or else use
                                     defaults */
 	struct xaddrf calledaddr; /* The called address  */
 	struct xaddrf callingaddr; /* The calling address */
 	struct qosformat qos; /* Facilities and CONS qos: if
                              negotiate_qos is set */
 }; 

The members of the xcallf structure are:

6.4.4 N_DAck--Data Ack Request/Indication

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;

 struct xdatacf dack;
 .
 .
 .
 ctlb.len = sizeof(struct xdatacf);
 ctlb.buf = (char *)dack;

 putmsg(x25_fd, &ctlb, NULL, 0);

Description

N_DAck acknowledges a previous Data Acknowledgment Request or Indication which had the D-bit set. The D-bit requests end-to-end, as opposed to local, acknowledgment. There is a one-to-one correspondence between D-bit data and acknowledgments, with one Data Acknowledgment being received/sent for each D-bit data packet sent/received. It is always the oldest outstanding D-bit packet that is being acknowledged.

Refer to "6.3.4 qosformat--Define OSI CONS QOS Parameters" for details of requesting acknowledgment using the reqackservice member of the qosformat structure. For OSI CONS calls, Data Acknowledgment must be negotiated on the connection.

When used with putmsg, N_DAck is a Data Acknowledgment Request, when used with getmsg, it is a Data Acknowledgment Indication. Example 6-1 shows how a getmsg can be constructed. The control part of the Data Acknowledgment Request or Indication is defined by the xdatacf structure. There is no data part.

The xdatacf structure is shown below:

struct xdatacf {
 	unsigned char xl_type; /* Always XL_DAT */
 	unsigned char xl_command; /* Always N_DAck */
 }; 

6.4.5 N_Data--Data

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;
 struct strbuf datab;

 struct xdataf control;
 char          data[MAX_LENGTH];
 .
 .
 .
 ctlb.len = sizeof(struct xdataf);
 ctlb.buf = (char *)control;

 datab.len = MAX_LENGTH;
 datab.buf = data;

 putmsg(x25_fd, &ctlb, &datab, 0);

Description

N_Data is used to transfer data across the X.25 interface. The synopsis shows a putmsg. Example 6-1 shows how a getmsg can be constructed. The control part of the Data packet is defined by the xdataf structure. The data part of the message contains the user data.

The xdataf structure is shown below:

struct xdataf {
 	unsigned char xl_type; /* Always XL_DAT */
 	unsigned char xl_command; /* Always N_Data */
 	unsigned char More; /* Set when more data is required
                            to complete the nsdu */
 	unsigned char setDbit, /* Set when data carries X.25 D-bit */
 	unsigned char setQbit; /* Set when data carries X.25 Q-bit */
 }; 

The members used by xdataf are.

No acknowledgement for this data is given to, or expected from, the application unless the D-bit is set and application-to-application Receipt Confirmation is being used.

6.4.6 N_DC--Clear Confirm

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;
 struct strbuf datab;

 struct xdcnff disc;
 char          cud[MAX_LENGTH];
 .
 .
 .
 ctlb.len = sizeof(struct xdcnff);
 ctlb.buf = (char *)disc;

 datab.len = cudlen;
 datab.buf = cud;

 putmsg(x25_fd, &ctlb, NULL, 0);

Description

N_DC is used to confirm a previous clear indication (N_DI). The example shows a putmsg. Example 6-1 shows how a getmsg can be constructed. The control part of the Data packet is defined by the xdcnff structure. If Fast Select is in use, the data part of the message contains any clear user data.

The xdcnff structure is shown below:

struct xdcnff {
 	unsigned char xl_type; /* Always XL_CTL */
 	unsigned char xl_command; /* Always N_DC */
 	unsigned char indicated_qos; /* When set, facilities
 	                                indicated */
 	struct qosformat rqos; /* If indicated_qos is set, holds
                               facilities and CONS qos */
 }; 

The members of the xdcnff structure are:

6.4.7 N_DI--Clear Request/Indication

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;
 struct strbuf datab;

 struct xdiscf disc;
 char          cud[MAX_LENGTH];
 .
 .
 .
 ctlb.len = sizeof(struct xdiscf);
 ctlb.buf = (char *)disc;

 datab.len = cudlen;
 datab.buf = cud;

 putmsg(x25_fd, &ctlb, &datab, 0);

Description

N_DI is used when a Clear Request/Indication crosses the X.25 interface. When used with putmsg, N_DI is a Clear Request, when used with getmsg, it is a Disconnect Indication. Example 6-1shows how a getmsg can be constructed. The control part of the Call Request or Indication is defined by the xdiscf structure. If Fast Select is in use, the data part of the message contains any clear user data.

The X.25 cause and diagnostic bytes, cause and diag, are presented, as well as the CONS originator and reason codes mapped from these. For a Clear Request the user can specify a non-zero cause code. This has no effect for an OSI CONS call; the value is set to zero by the system.

The Clear Request from an application is confirmed unless it is a rejection of a previous Connect Indication. When it is not a rejection, the X.25 driver sends a Clear Confirm to the application when the Clear Confirmation is received. This guarantees that once the Clear Confirm is read by the application no more messages are sent on this stream. For this reason, after requesting disconnection, the application should read and discard all messages from the stream until the Clear Confirm is received.

For call rejection, no acknowledgment is sent. However, the application must supply the connection identifier presented in the Connect Indication so that the appropriate circuit is cleared. In the case of a Disconnect Indication, all messages sent downstream except connect messages are discarded silently.

The xdiscf structure is shown below:

struct xdiscf {
 	unsigned char xl_type; /* Always XL_CTL */
 	unsigned char xl_command; /* Always N_DI */
 	unsigned char originator, /* Originator and Reason mapped
                                  from */
 		reason, /* X.25 cause/diag in indications */
 		cause, /* X.25 cause byte */
 		diag; /* X.25 diagnostic byte */
 	int conn_id; /* The connection id (for reject only) */
 	unsigned char indicated_qos; /* When set, facilities
                                     indicated */
 	struct xaddrf responder; /* CONS responder address */
 	struct xaddrf deflected; /* Deflected address */
 	struct qosformat qos; /* If indicated_qos is set, holds
                              facilities and CONS qos */
 };

The members of the xdiscf structure are.

If a disconnect collision occurs, acknowledgement is taken to be complete.

6.4.8 N_EAck--Expedited Data Acknowledgement

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;

 struct xedatacf eack;
 .
 .
 .
 ctlb.len = sizeof(struct xedatacf);
 ctlb.buf = (char *)eack;

 putmsg(x25_fd, &ctlb, NULL, 0);

Description

N_EAck is used to acknowledge expedited data, carried by an X.25 Interrupt packet. The example shows a putmsg. Example 6-1 shows how a getmsg can be constructed. The control part of the Interrupt packet is defined by the xedatacf structure. There is no data part. An acknowledgment must be sent immediately on receipt of an Interrupt packet.

The xedatacf structure is shown below:

struct xedatacf {
 	unsigned char xl_type; /* Always XL_DAT */
 	unsigned char xl_command; /* Always N_EAck */
 }; 

6.4.9 N_EData--Expedited Data

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;
 struct strbuf datab;

 struct xedataf edata;
 char          data[MAX_LENGTH];
 .
 .
 .
 ctlb.len = sizeof(struct xedataf);
 ctlb.buf = (char *)edata;

 datab.len = cudlen;
 datab.buf = cud;

 putmsg(x25_fd, &ctlb, &datab, 0);

Description

N_EData is used when expedited data, carried by an X.25 Interrupt packet, crosses the X.25 interface. The example shows a putmsg. Example 6-1 shows how a getmsg can be constructed. The control part of the Interrupt packet is defined by the xedataf structure. The data part of the message contains the user data. The expedited data is a confirmed primitive and must be acknowledged (see "6.4.8 N_EAck--Expedited Data Acknowledgement") before another expedited data unit can be requested or indicated.

The xedataf structure is shown below:

struct xedataf {
 	unsigned char xl_type; /* Always XL_DAT */
 	unsigned char xl_command; /* Always N_EData */
 }; 

6.4.10 N_PVC_ATTACH--PVC Attach

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;

 struct pvcattf attach;
 .
 .
 .
 ctlb.len = sizeof(struct pvcattf);
 ctlb.buf = (char *)attach;

 putmsg(x25_fd, &ctlb, NULL, 0);

Description

N_PVC_ATTCH is used when an application wants to attach to a PVC.The control part of the PVC Attach is defined by the pvcattf structure. The example shows a putmsg. Example 6-1 shows how a getmsg can be constructed.

The pvcattf structure is shown below:

struct pvcattf {
        unsigned char     xl_type;      /* Always XL_CTL */
        unsigned char     xl_command;   /* Always N_PVC_ATTACH */
        unsigned short    lci;          /* Logical channel */
        uint32_t     link_id;      /* Link # */
        /* 0 for next 3 parameters implies use of default */
        unsigned char     reqackservice;
        unsigned char     reqnsdulimit;
        int               nsdulimit;
        int               result_code;     /* Non-zero - error */
};

The members used by pvcattf are:

6.4.11 N_PVC_DETACH--PVC Detach

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;
 struct strbuf datab;

 struct pvcdetf detach;
 .
 .
 .
 ctlb.len = sizeof(struct pvcdetf);
 ctlb.buf = (char *)detach;

 datab.len = cudlen;
 datab.buf = cud;

 putmsg(x25_fd, &ctlb, &datab, 0);

Description

N_PVC_DETACH is used when an application wants to detach from a PVC. This allows the use of a stream to be changed. The control part of the PVC Detach is defined by the pvcdetf structure. The data part of the message contains any call user data. The synopsis shows a putmsg. Example 6-1 shows how a getmsg can be constructed.

The pvcdetf structure is shown below:

struct pvcdetf {
 	unsigned char xl_type; /* Always XL_CTL */
 	unsigned char xl_command; /* Always N_PVC_DETACH */
 	int reason_code; /* Reports why */
 };

This structure has the following member:

The PVC Detach message is acknowledged to the user by returning another PVC Detach message.

6.4.12 N_RC--Reset Response/Confirm

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;

 struct xrscf rc;
 .
 .
 .
 ctlb.len = sizeof(struct xrscf);
 ctlb.buf = (char *)rc;

 putmsg(x25_fd, &ctlb, NULL, 0);

Description

N_RC is used to respond to a previous reset. When used in a putmsg it is a Reset Response. In a getmsg it is a Reset Confirm. Example 6-1 shows how a getmsg can be constructed. The control part of the Reset Response or Confirm is defined by the xrscf structure. There is no data part.

The xrscf structure is shown below:

struct xrscf {
 	unsigned char xl_type; /* Always XL_CTL */
 	unsigned char xl_command; /* Always N_RC */
 };

A Reset primitive is an acknowledged service (see the associated structure xrscf). A collision between a Reset Indication and a Reset Request is taken to acknowledge the Reset--no Reset Confirmation is then required before another Reset Request can be sent. Normally, Resets are handled by the application.

6.4.13 N_RI--Reset Request/Indication

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;

 struct xrstf reset;
 .
 .
 .
 ctlb.len = sizeof(struct xrstf);
 ctlb.buf = (char *)reset;

 putmsg(x25_fd, &ctlb, NULL, 0);

Description

N_RI is used for resets. When used in a putmsg it is a Reset Request. In a getmsg it is a Reset Indication. Example 6-1 shows how a getmsg can be constructed. The X.25 cause and diagnostic bytes, cause and diag, are presented as well as the CONS originator and reason codes that are mapped from these. Refer to Chapter 9, Error Codes for further information.

For a Reset Request, the user can specify a non-zero cause code. This has no effect for an OSI CONS call; the value is set to zero by the system.

The control part of the Reset Request or Indication is defined by the xrstf structure. There is no data part.

The xrstf structure is shown below:

struct xrstf {
 	unsigned char xl_type; /* Always XL_CTL */
 	unsigned char xl_command; /* Always N_RI */
 	unsigned char originator, /* Originator and Reason mapped */
 			reason, /* from X.25 cause/diag in indications */
 			cause, /* X.25 cause byte */
 			diag; /* X.25 diagnostic byte */
 }; 

A Reset primitive is an acknowledged service. It must be acknowledged before another Reset can be requested. A collision between a Reset Indication and a Reset Request is taken to acknowledge the Reset--no Reset Confirmation is then required before another Reset Request can be sent. Normally, Resets are handled by the application.

6.4.14 N_Xcanlis--Listen Cancel Command/Response

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;

 struct xcanlisf canlis;
 .
 .
 .
 ctlb.len = sizeof(struct xcanlisf);
 ctlb.buf = (char *)canlis;

 putmsg(x25_fd, &ctlb, NULL, 0);

Description

N_Xcanlis is used to cancel an interest in incoming calls.

When used with putmsg, N_Xcanlis is a Listen Cancel Command, when used with getmsg, it is a Listen Cancel Response. Example 6-1 shows how a getmsg can be constructed. The control part of the Listen Command or Response is defined by the xcanlisf structure. There is no data part.

The Cancel Request removes all listen addresses from the stream. There is no way of cancelling a Listen on a particular address, for example, when the use of the stream is about to be changed by the application.

The control part of a Listen Cancel Command or Response message has a format defined in the xcanlisf structure:

struct xcanlisf {
 	unsigned char xl_type; /* Always XL_CTL  */
 	unsigned char xl_command; /* Always N_Xcanlis */
 	int c_result; /* Result flag */
 };

This structure has the following member:

6.4.15 N_Xlisten--Listen Command/Response

Synopsis

#include <stream.h>
 #include <netx25/x25_proto.h >

 struct strbuf ctlb;
 struct strbuf datab;

 struct xlistenf listen;
 char          lisbuf[MAXLIS];
 .
 .
 .
 ctlb.len = sizeof(struct xlistenf);
 ctlb.buf = (char *)listen;

 datab.len = lislen;
 datab.buf = lisbuf;

 putmsg(x25_fd, &ctlb, &datab, 0);

Description

N_Xlisten is used to listen for incoming calls. When used with putmsg, N_Xlisten is a Listen Command, when used with getmsg, it is a Listen Response. Example 6-1 shows how a getmsg can be constructed. The control part of the Listen Command or Response is defined by the xlistenf structure.

The data part is treated as a byte stream of CUD and addresses conforming to the following definition:

unsigned char l_cumode;
 unsigned char l_culength;
 unsigned char l_cubytes [l_culength];
 unsigned char l_mode;
 unsigned char l_type;
 unsigned char l_length;
 unsigned char l_add[(l_length+1)>>1];

Not all variables need be present. Refer to the individual variable descriptions below for more details.

The fields l_cumode, l_culength and l_cubytes are used to match the CUD field of the incoming call against that specified in the Listen request.

The fields l_mode, l_type, l_length and l_add are used to match the called address field(s) of the incoming call against that specified in the Listen request.

To use wildcards, represent * by 0x0F and ? by 0x0E. * represents 0 or more characters. ? represents a single character.

The xlistenf structure is shown below:

struct xlistenf {
 	unsigned char xl_type; /* Always XL_CTL */
 	unsigned char xl_command; /* Always N_Xlisten */
 	int lmax; /* Maximum number of CI's at a time */
 	int l_result; /* Result flag */
 };

The members of the xlistenf structure are.

For example code using listening, refer to Chapter 4, Listening for Calls.

Chapter 7 Network Layer ioctls

This chapter describes the Network Layer ioctls alphabetically. Refer to the tables below for functional groupings of Network Layer ioctls. Use the ioctls in this chapter to communicate with the Solstice X.25 software. To communicate with the network, for example to initiate calls, use the NLI commands described in Chapter 6, NLI Commands and Structures.

Note that some ioctls allow changes to be made to connections that may currently be in use--potentially disrupting users.

The header files used by the NLI ioctls are contained in the /usr/include/netx25 directory.

7.1 ioctls Functional Grouping

These ioctls are related to NUI mapping. The NUI mapping table maps Network User Identifiers to particular facilities. The ioctls described in this section let you operate on NUI mappings. Note that any changes you make could disrupt other users. For this reason you require root access to use the ioctls that let you change the current settings.

These ioctls operate on a per multiplexor basis:

These ioctls operate on a per virtual circuit basis:

These ioctls start and stop packet level tracing:

These ioctls manage the X.25 routing table. Using them may override values set using x25tool. The ioctls are:

These ioctls operate on a link:

7.2 N_getlinkstats--Retrieve Per-Link Statistics

Retrieve statistics for a particular link.

Associated Structure

The following structure is associated with this ioctl:

struct perlinkstats {
        uint32_t linkid;                   /* link id (ppa)           */
        int      network_state;                 /* Network State           */
        uint32_t mon_array[link_mon_size]; /* L3perlinkmonarray       */
};

The members of the perlinkstats structure are:

Associated Structure

The following structure is associated with this ioctl:

struct nliformat {
     unsigned char  version;    /* NLI version number */
 };

The members of the nliformat structure are:

7.3 N_getoneVCstats --Retrieve Per-Virtual-Circuit Statistics

This ioctl is used to retrieve per-virtual circuit state and statistics for the virtual circuit associated with the stream on which the ioctl is made.

Associated Structure

The vcinfo structure is shown below:

struct vcinfo {
        struct xaddrf     rem_addr;     /* = called for outward calls */
        /* = caller for inward calls  */
        uint32_t     xu_ident;     /* link id                    */
        uint32_t     process_id;   /* effective user id          */
        unsigned short    lci;          /* Logical Channel Identifier */
        unsigned char     xstate;       /* VC state                   */
        unsigned char     xtag;         /* VC check record            */
        unsigned char     ampvc;        /* =1 if a PVC                */
        unsigned char     call_direction;
        /* in=0, out=1                */
        unsigned char     domain;       /* was in 8.0, not in R7. Put it back */
        int                perVC_stats[perVCmon_size];
}; 

The members of the vcinfo structure are:

7.4 N_getpvcmap--Get PVC Default Packet/Window Sizes

This ioctl is used to read the default packet and window sizes of active PVCs.

Associated Structure

The following structure is associated with this ioctl:

struct pvcmapf {
   struct pvcconff entries[MAX_PVC_ENTS]; /* Data buffer           */
   int             first_ent;             /* Where to start search   */
   unsigned char   num_ent;               /* Number entries returned */
 };

The members of the pvcmapf structure are:

7.5 N_getstats--Get X.25 Multiplexor Statistics

This ioctl is used to read the statistics counts for the X.25 multiplexor since network start-up or since they were last reset by an N_zerostats ioctl (see below). Statistics are maintained an a multiplexor basis--separate link statistics are not available.

Associated Structure

The N_getstats structure associated with this ioctl is an integer array of size mon_size, defined in the file x25_control.h. Entries and meanings include the following:

7.6 N_getVCstats--Get Per-Virtual-Circuit Statistics

This ioctl is used to retrieve per-virtual circuit state and statistics, for all virtual circuits currently active over all configured links.

Associated Structure

The vcstatsf structure, defined in x25_control.h, takes this format:

struct vcstatsf {
         int first_ent;          /* Where to start search   */
         unsigned char num_ent   /* Number entries returned */
         struct pervcinfo vc;    /* Data buffer, extendable by*/
                                 /* malloc overlay*/
 };

The members of the vcstatsf structure are:

The contents of the pervcinfo structure are:

struct pervcinfo {
        struct xaddrf     rem_addr;     /* = called for outward calls */
        /* = caller for inward calls  */
        uint32_t     xu_ident;     /* link id                    */
        uint32_t     process_id;   /* effective user id          */
        unsigned short    lci;          /* Logical Channel Identifier */
        unsigned char     xstate;       /* VC state                   */
        unsigned char     xtag;         /* VC check record            */
        unsigned char     ampvc;        /* =1 if a PVC                */
        unsigned char     call_direction;
        /* DIRECTION_xxx (see mib)    */
        unsigned char     domain;       /* was in 8.0, not in R7. Put it back */
        uint32_t     perVC_stats[perVCstat_size];
        /* Per-VC statistics array    */
        /*
         * move these to the end, so that the first bit of the struct is
         * identical to the 8.0 one
        */
        unsigned char     vctype;       /* what _is_ this? */
        struct xaddrf     loc_addr;     /* = caller for outward calls */
        /* = called for inward calls  */
        uint32_t     start_time;   /* time the VC was created */
};
 

xstate contains the state of the VC. Possible states and meanings are:

perVC_stats contains statistics counts, as follows:

7.7 N_getVCstatus--Get Per-Virtual-Circuit Statistics

This ioctl has been superceded by the N_getVCstats ioctl. It is retained for backward compatibility with Solstice X.25 8.x. When writing new applications, use N_getVCstats.

This ioctl is used to retrieve per-virtual circuit state and statistics, for all virtual circuits currently active over all configured links.

Associated Structure

The vcstatusf structure takes this format:

struct vcstatusf {    
   struct vcinfo       vcs[MAX_VC_ENTS];  /* Data buffer      */
   int                 first_ent;         /* Where to start search */
   unsigned char       num_ent;           /* Number entries returned */
 };

The members of the vcstatusf structure are:

The contents of the vcinfo structure are:

struct vcinfo {
        struct xaddrf     rem_addr;     /* = called for outward calls */
        /* = caller for inward calls  */
        uint32_t     xu_ident;     /* link id                    */
        uint32_t     process_id;   /* effective user id          */
        unsigned short    lci;          /* Logical Channel Identifier */
        unsigned char     xstate;       /* VC state                   */
        unsigned char     xtag;         /* VC check record            */
        unsigned char     ampvc;        /* =1 if a PVC                */
        unsigned char     call_direction;
        /* in=0, out=1                */
        unsigned char     domain;       /* was in 8.0, not in R7. Put it back */
        int                perVC_stats[perVCmon_size];
}; 

The xstate member contains the state of the VC. Possible states and meanings are:

The perVC_stats member contains statistics. Entries are statistics counts, as follows:

7.8 N_linkconfig--Configure the wlcfg Database

This ioctl is used to configure the wlcfg database for a link. The wlcfg database appropriate to a link is carried as the M_DATA part of the ioctl N_linkconfig. The U_LINK_ID member of the wlcfg structure specifies the link to be configured. The wlcfg database structure is defined in the /usr/include/netx25/x25_control.h file.

This ioctl affects currently open connections and could therefore disrupt users significantly. For this reason it can only be used by root.

The wlcfg database structure contains the members described below:

U_LINK_ID

The upper level link identifier which is quoted by upper level software in the xaddrf address structure to specify which link a call is to be sent on. It is also used to identify which link an incoming call arrived on.

NET_MODE

This determines the characteristics of the network protocol Possible values are:

X25_VSN

This determines the version of the X.25 protocol used over the network. Allowed values are:

• 0 indicating X.25(80)

• 1 indicating X.25(84)

• 2 indicating X.25(88)

Setting NET_MODE to X25_LLC overrides an X.25 (80) value.

L3PLPMODE

Indicates whether the link is DTE or DCE. Allowed values are:

• 0 indicating DCE

• 1 indicating DTE

• 2 indicating that this is to be resolved by following the procedures in ISO 8208 for DTE-DTE operation

LPC to HPC

Logical channel range assigned to PVCs.

LIC to HIC

Logical channel range assigned to one way incoming logical channels.

LTC to HTC

Logical channel range assigned to two-way logical channels.

LOC to HOC

Logical channel range assigned to one-way outgoing logical channels.

In a DTE/DTE environment, one of the interacting pairs views these ranges as a DCE, for example, LIC to HIC are viewed as one-way outgoing. HxC = LxC = 0 denotes no channels in that grouping.

NPCchannels, NICchannels, NTCchannels, NOCchannels and Nochnls

The number of logical channels assigned. This is calculated from the logical channel ranges and can only be changed only by altering these ranges.

THISGFI

0x10 indicates Modulo 8. 0x20 indicates Modulo 128 sequence numbering operates on the network.

LOCMAXPKTSIZE

The maximum acceptable size of local to remote data packets, expressed as a power of 2.

REMMAXPKTSIZE

The maximum acceptable size of remote to local data packets expressed as a power of 2.

LOCDEFPKTSIZE

The default local-to-remote packet size expressed as a power of 2.

REMDEFPKTSIZE

The default remote-to-local packet size on a particular link, expressed as a power of 2.

LOCMAXWSIZE

The maximum acceptable local to remote X.25 window size.

REMMAXWSIZE

The maximum acceptable remote to local X.25 window size.

LOCDEFWSIZE

The local-to-remote default window size.

REMDEFWSIZE

The remote-to-local default window size.

MAXNSDULEN

The default maximum length beyond which concatenation is stopped and the data currently held is passed to the NS-user. This parameter can be overridden on a per-circuit basis using the nsdulimit parameter on N-CONNECT requests and N-CONNECT responses.

ACKDELAY

The maximum delay in ticks (0.1 second units) over which a pending acknowledgement will be withheld. The default value is 5, the permitted range 1--32000.

T20value

The length of DTE timer T20, the Restart Request Response Timer, in ticks (0.1 second units). The default value is 1800. The permitted range is 0--32000.

T21value

The length of DTE timer T21, the Call Request Response Timer, in ticks (0.1 second units). The default value is 2000. The permitted range is 0--32000.

T22value

The length of DTE timer T22, the Reset Request Response Timer, in ticks (0.1 second units). The default value is 1800. The permitted range is 0--32000.

T23value

The length of DTE timer T20, the Clear Request Response Timer, in ticks (0.1 second units). The default value is 1800. The permitted range is 0--32000.

Tvalue

The maximum time over which acknowledgments of data received from the remote transmitter will be withheld. After this timer expires any withheld acknowledgments are carried by a Receive Not Ready (RNR) packet. This timer ensures that non-receipt of acknowledgment by the remote transmitter does not cause resets within the virtual circuit. This timer does not cause transmission of window status every Tvalue ticks (0.1 second units). The default value is 750. The permitted range is 0--32000.

T25value

The length of DTE timer T25, the Window Rotation Timer, in ticks (0.1 second units). The default value is 1500, as specified in ISO 8208. The permitted range is 0--32000.

The code may be configured to be lenient in the case of flow control inhibition (see Section 11.2 of ISO 8208). That is, a decision has to be made in order to cater for the case when the remote station does not rotate the window fast enough to prevent expiration of T25. ISO 8208 recommends strongly that high level protocols be used to effect recovery, to achieve this, set T25 to either zero (implying infinite) or a very large value.

The timer Tvalue, should be set to a value approximately half T25value, in order to prevent the remote PLP from resetting on T25 expiration. The timer ACKDELAY should be approximately 0.5 seconds, although this recommendation may change after evaluation and experience is gained.

Finally, the idlevalue timer may be set according to how quickly the LAN administration wishes the resource to be reclaimed, while connectvalue should be about three times the T20 value.

Note also that ISO 8208 recommends that the retry values R20, R22 and R23 should never be set to zero in order to cater for the possibility of collisions (see footnote to Figure 6, ISO 8208).

T26value

The length of DTE timer T26, the Interrupt Response Timer, in ticks (0.1 second units). The default value is 1800. The permitted range is 0--32000.

T28value

The length of DTE timer T28, the Registration Request Timer, in ticks (0.1 second units). The default value is 1800. The permitted range is 0--32000.

idlevalue

The number of ticks (0.1 second units) over which a link-level connection associated with no connections is maintained. This timer is meaningful on a LAN or on a dial-up WAN connection. The default value is 600. The permitted range is 0--32000.

connectvalue

The number of ticks (0.1 second units) over which the DTE/DCE resolution phase must be complete. On expiration of this timer, the link connection is disconnected and all pending connections are aborted. The default value is 2000. The permitted range is 0--32000.

R20value

The DTE Restart Request Retransmission Count. The default value is 1. The permitted range is 1--255.

R22value

The DTE Restart Request Retransmission Count. The default value is 1. The permitted range is 1--255.

R23value

The DTE Restart Request Retransmission Count. The default value is 1. The permitted range is 1--255.

localdelay and accessdelay

In milliseconds, the values of the transit delay attributed to internal processing and the effect of the line transmission rate. These values are used to check whether any maximum acceptable end-to-end transit delay specified in an N-CONNECT request or an N-CONNECT indication is in fact available.

locmaxthclass

The maximum value of the throughput class quality of service parameter in the local-to-remote direction which is supported. According to ISO 8208 this parameter is bounded in the range 3 and <= 12 corresponding to a range 75 to 48000 bits/second.

remmaxthclass

The maximum value of the throughput class quality of service parameter in the remote-to-local direction which is supported. According to ISO 8208 this parameter is bounded in the range 3 and <= 12 corresponding to a range 75 to 48000 bits/second.

locdefthclass

In some PSDNs, for example, TELENET, negotiation of throughput class is constrained to be towards a configured default throughput class. In such cases the flag thclass_neg_to_def (see below) is non-zero and locdefthclass is the default for the local-to-remote direction. In other PSDNs, locdefthclass should be set equal to the value of locmaxthclass (see above).

Note that locmaxthclass must be greater than or equal to locdefthclass.

remdefthclass

In some PSDNs, for example, TELENET, negotiation of throughput class is constrained to be towards a configured default throughput class. In such cases the flag thclass_neg_to_def is non-zero and remdefthclass is the default for the remote-to-local direction. In other PSDNs, set remdefthclass equal to the value of remmaxthclass (see above).

Note that remmaxthclass must be greater than or equal to remdefthclass.

locminthclass

According to ISO 8208, the throughput class parameter must be greater than or equal to 3 and less than or equal to 12. Some PSDNs may provide a different mapping, in which case locminthclass is the minimum value in the local-to-remote direction. Note that locmaxthclass must be less than or equal to locdefthclass which must be greater than or equal to locminthclass.

remminthclass

According to ISO 8208, the throughput class parameter is defined in the range 3 and 12. Some PSDNs may provide a different mapping, in which case remminthclass is the minimum value in the remote-to-local direction. Note that remmaxthclass must be greater than or equal to remdefthclass which must be greater than or equal to remminthclass.

CUG_CONTROL

This member controls Closed User Group actions in two ways. Firstly, it describes the type, if any, of Closed User Group facilities subscribed to. This is used to choose the appropriate encoding for any closed user group facilities in N-CONNECT requests. Secondly, it specifies the action to be taken if the Closed User Group optional facility is present in an incoming call. It is a bit map where the bits have the following meanings:

Bits 0 and 2 are mutually exclusive as are bits 4 and 5.

SUB_MODES

This member is a bit map, which contains information on the various subscription options for a particular PSDN link. The entries mean:

Some PSDNs require certain procedures to be followed which are not standard for all X.25 networks. The structure psdn_local contains the flags used to tune the actions of the X.25 driver to the requirements of the particular network to which the configuration refers. The entries and values taken by the psdn_local structure are described below.

PSDN_MODES

This is used to tune the various options for a particular PSDN link. It is a bit map in which the various entries when set imply:

The BAR_DIAG and DISC_NZ_DIAG entries specify the treatment of incoming diagnostic packets. When BAR_DIAG is set, incoming diagnostic packets are handled as follows. If USE_DIAG is set, and the link is configured as a DCE, then a diagnostic packet is sent to the DTE. Otherwise, the incoming diagnostic packet is simply discarded. When DISC_NZ_DIAG is set, diagnostic packets will be discarded when received on non-zero logical channel numbers. If ACC_HEX_ADD is set, DTE addresses are not restricted to containing only BCD digits.

intl_addr_recogn

The main use of this feature is in conjunction with the intl_prioritised member discussed below. Possible values are:

dnic1, dnic2

The first four BCD digits of the DNIC and is only used when intl_addr_recogn has the value one.

intl_prioritised

This determines whether some prioritization method is to be used for international calls, and is used in conjunction with prty_encode_control and prty_pkt_forced_value.

intl_prioritised has two values: zero implying no priority, while non-zero implies an attempt to prioritize according to ptry_encode_control.

intl_addr_recogn has the value one.

prty_encode_control

This describes how the priority request is to be encoded for this PSDN. Values are:

prty_pkt_forced_value

If this entry is non-zero then it implies that all priority call requests and incoming calls should have the associated packet size parameter forced to this value (note that the actual packet size is two to the power of this parameter; for example, 7 implies 128 byte packets). A zero value implies no special action on packet size is required.

src_addr_control

This provides the means to override or set the calling address in outgoing call requests for this PSDN. It takes the following values:

dbit_control

This member specifies the action to be taken:

• during the call setup phase, where both parties do not agree on the use of the D-bit;

• during the data transfer phase, on receipt of a data packet with the D-bit set, where the use of the D-bit has not been agreed by both parties.

Actions which may be specified during the call setup phase are:

• Leave the D-bit set and pass the packet on.

• Zero the D-bit and pass the packet on.

• Clear the call.

Actions which may be specified during the data transfer phase are:

• Leave the D-bit set and pass the packet on.

• Zero the D-bit and pass the packet on.

• Reset the call.

thclass_neg_to_def

This accommodates certain network procedures which dictate that negotiation of throughput class must be towards the default value (for example, TELENET), the default value being configured into the member defthclass. A non-zero value in this member requests use of this option, zero implies non-use.

thclass_type

This provides the means by which throughput class encodings can be used to assign window and packet sizes (according to the arrays thclass_wmap and thclass_pmap described below). It should be noted that some implementations of X.25 do not use the X.25 packet and window negotiation but instead rely on mapping the throughput class to these parameters (see thclass_type 1,2 and 3). Thclass_type should be used on such PSDNs. Note also that the values of locmaxthclass and remmaxthclass may have an effect on what is achieved through the mapping.

The values assigned to thclass_type to indicate the mapping are:

Values 1, 2 and 3 are intended for use on non-standard X.25 PSDN implementations. Note the following.

For the special values 1 and 2:

• Do not select these values when window and packet sizes can appear in call setup packets (that is, subscription to window and packet size negotiation) since this algorithm is designed for those PSDNs which support only the mapping procedure.

• In call requests, the network service user should specify equal values for locthroughput and remthroughput in the qosformat, to ensure that the correct behavior is obtained (see also high and low nibble usage for these two values).

• The user will be barred from negotiating window and packet sizes, and the throughput class will not be indicated in a connect indication.

For the value 3, window and packet sizes can be negotiated by the network service user only through the throughput class parameter. Negotiations through the flow negotiation parameters when subscribing to the extended facility option are overridden. However, as for values 1 and 2, this value is intended only for cases where this is the only means of negotiating window and packet sizes.

Since window and packet sizes can be mapped using these three values without the use of window and packet negotiation facilities, it is important that the map (thclass_wmap and thclass_pmap) is correct for the PSDN, in order to ensure that both called and calling parties agree on the values associated with a particular throughput class.

thclass_wmap, thclass_pmap

The mapping between the value of the throughput class (a number 0 to 15) and a window and packet parameter. Zero in this table indicates that the currently set or default value be used.

local_address

Holds the local DTE address for this X.25 link in a byte array, local_address.lsap_add, with an associated length byte local_address.lsap_len.

7.9 N_linkent--Configure a Newly Linked Driver

This ioctl is sent downstream by the x25netd process to configure a newly linked driver below the X.25 multiplexor. It supplies the parameters necessary to identify the link via the identifier and to register the mode of the lower driver.

This ioctl is only used when X.25 is initializing. As it affects currently open connections and could therefore disrupt users significantly, it can only be used by root. It should not be used by user applications, as it may be withdrawn from future versions of Solstice X.25.

7.10 N_linkmode--Alter the Characteristics of a Link

This ioctl is used to read or change the SUB_MODES Member of a particular wlcfg database appropriate to a link. This configuration ioctl is used to alter characteristics of a link's operation, for example, to temporarily bar incoming calls.

This ioctl affects currently open connections and could therefore disrupt users significantly. For this reason it can only be used by root.

Associated Structure

The parameters are carried as the M_DATA part of the N_linkmode ioctl as follows:

struct linkoptformat {
        uint32_t   U_LINK_ID;
        unsigned short  newSUB_MODES;
        unsigned char   rd_wr;
};

The members of the linkoptformat structure are:

In the case of read, the same structure is returned with the current value of SUB_MODES for the link.

7.11 N_linkread --Read the wlcfg Database

This ioctl is used to extract the wlcfg database for a link in a running system for examination. The wlcfg database is returned within the M_DATA part of the N_linkread ioctl. Make sure that there is enough space in the data area to receive the copy of the structure.

Refer to "7.8 N_linkconfig--Configure the wlcfg Database" for a complete list of the fields contained in the wlcfg database structure.

7.12 N_nuidel--Delete Specified NUI Mapping

This ioctl deletes the mapping for a specified Network User Identifier (NUI).

This ioctl can disrupt other users significantly. For this reason it can only be used by root.

Associated Structure

The following structure is associated with this ioctl:

struct nui_del {
     char    prim_class;          /* Always NUI_MSG             */
     char    op;                  /* Always NUI_DEL             */
     struct  nuiformat  nuid;     /* NUI  to delete             */
 };

The members of the nui_del structure are:

7.13 N_nuiget--Read the Mapping for a Specified NUI

This ioctl is used to read the mapping for a specified Network User Identifier (NUI).

Associated Structure

The following structure is associated with this ioctl:

struct nui_get {
         char            prim_class;     /* Always NUI_MSG               */
         char            op;             /* Always NUI_GET               */
         struct nuiformat        nuid;           /* NUI to get           */
         struct facformat        nuifacility;    /* NUI facilities       */

The members of the nui_get structure are:

7.14 N_nuimget--Read all Existing NUI Mappings

This ioctl is used to read all existing mappings for Network User Identifiers (NUI).

Associated Structure

The following structure is associated with this ioctl:

struct nui_mget {    
   unsigned int first_ent;          /* First entry required    */
   unsigned int last_ent;           /* Last entry required     */
   unsigned int num_ent;            /* No of entries required  */
   char         buf[MGET_NBUFSIZE]; /* Data Buffer             */
 };

The members of the nui_mget structure are:

7.15 N_nuiput--Store a set of NUIs

This ioctl is used to store a set of Network User Identifiers (NUIs) and associated facilities mappings within the X.25 multiplexor. It is used in conjunction with the NUI override facility option.

This ioctl affects currently open connections and could therefore disrupt users significantly. For this reason it can only be used by root.

Associated Structure

The following structures are associated with this ioctl:

struct nui_put {
         char    prim_class;     /* Always NUI_MSG                       */
         char    op;             /* Always NUI_ENT                       */
         struct nuiformat       nuid;           /* NUI                  */
        struct facformat      nuifacility;    /* NUI facilities    */
 };

The members of the nui_put structure are:

The nuiformat structure looks like this:

#define NUIMAXSIZE	64
 #define NUIFACMAXSIZE	32
 struct nuiformat {
   unsigned char nui_len;
   unsigned char nui_string[NUIMAXSIZE]; /* Network User Identifier */
 };

The members of the nuiformat structure are

The facformat structure looks like this:

struct facformat {
   unsigned short SUB_MODES;	/* Mode tuning bits for net */
   unsigned char  LOCDEFPKTSIZE;	/* Local default pkt size */
   unsigned char  REMDEFPKTSIZE;	/* Local default pkt size */
   unsigned char  LOCDEFWSIZE;	/* Local default window size */
   unsigned char  REMDEFWSIZE;	/* Local default window size */
   unsigned char  locdefthclass;	/* Local default value         */
   unsigned char  remdefthclass;	/* Remote default value        */
   unsigned char  CUG_CONTROL;	/* CUG facilities */
 };

The members of the facformat structure are:

7.16 N_nuireset --Delete all Existing NUI Mappings

This ioctl is used to delete all existing mappings for Network User Identifiers (NUIs).

This ioctl can disrupt other users significantly. For this reason it can only be used by root.

Associated Structure

The following structure is associated with this ioctl:

struct nui_reset {
         char            prim_class;     /* Always NUI_MSG       */
         char            op;             /* Always NUI_RESET     */
 };

The members of the nui_reset structure are:

7.17 N_putpvcmap--Change PVC Packet and Window Sizes

This ioctl is used to change the packet and window sizes of a PVC from the defaults configured for the link that the PVC is active on.

This ioctl can disrupt other users significantly. For this reason it can only be used by root.

Associated Structure

The following structure is associated with this ioctl:

struct pvcconff {
        uint32_t     link_id;      /* Link #           */
        unsigned short    lci;          /* Logical channel  */
        unsigned char     locpacket;    /* Loc packet size  */
        unsigned char     rempacket;    /* Rem packet size  */
        unsigned char     locwsize;     /* Loc window size  */
        unsigned char     remwsize;     /* Rem window size  */
};

7.18 N_traceoff ioctl--Cancel N_traceon

This ioctl is used to cancel a previously issued N_traceon ioctl.

This ioctl affects currently open connections and could therefore disrupt users significantly. For this reason it can only be used by root.

7.19 N_traceon --Turn on Packet Level Tracing

This ioctl turns on packet level tracing for a particular link or all configured links. Each incoming and outgoing X.25 packet will be sent up the stream on which the N_traceon ioctl was made.

This ioctl can have a serious impact on security. For this reason it can only be used by root.

Associated Structures

The following structures are associated with this ioctl:

struct trc_regioc {
    uint8     all_links;                /* Trace on all links           */
    uint8     spare[3];                 /* for alignment                */
    uint32    linkid;                   /* Link                         */
    uint8     level;                    /* Level of tracing required    */
    uint8     spare2[3];                /* for alignment                */
    uint32    active[MAX_LINKS+1];      /* tracing actively on          */
};

The members of the trc_regioc structure are:

Each X.25 packet is preceded by a trc_ctl structure:

/*
    Types of tracing message
*/
#define TR_CTL       100            /* Basic                   */
#define TR_LLC2_DAT  101            /* Basic + LLC2 parameters */
#define TR_LAPB_DAT  TR_CTL         /* Basic for now           */
#define TR_MLP_DAT   TR_CTL         /* Basic for now           */
#define TR_X25_DAT   TR_CTL         /* Basic for now           */
#define TR_DLPI      102            /* type used for tracing DLPI primitives */

/*
    Format for control part of trace messages
*/
struct trc_ctl {
    uint8           trc_prim;    /* Trace msg identifier     */
    uint8           trc_mid;     /* Id of protocol module    */
    uint16          trc_spare;   /* for alignment            */
    uint32          trc_linkid;  /* Link Id                  */
    uint8           trc_rcv;     /* Message tx or rx         */
    uint8           trc_spare2[3]; /* for alignment          */
    uint32          trc_time;    /* Time stamp               */
    uint16          trc_seq;     /* Message seq number       */
};

7.20 N_X25_ADD_ROUTE--Set Fields of X25_ROUTE Structure

Sets the fields in the X25_ROUTE structure to the desired values.

This ioctl can disrupt other users significantly. For this reason it can only be used by root.

Associated Structure

The x25_route_s data structure takes the following form:

typedef struct x25_route_s {
        uint32_t        index;          /* used for reading next route */
        u_char          r_type;
#define R_NONE          0
#define R_X121_HOST     1
#define R_X121_PREFIX   2
#define R_AEF_HOST      3
#define R_AEF_PREFIX    4
#define R_AEF_SOURCE    5
        CONN_ADR        x121;
        u_char          pid_len;
#define MAX_PID_LEN     4
        u_char          pid[MAX_PID_LEN];
        AEF             aef;
        int             linkid;
        X25_MACADDR     mac;
        int             use_count;
        char            pstn_number[16];
} X25_ROUTE;

Example

#include <sys/strupts.h>
 struct strioctl ioc ;
 int          fd ;
 X25_ROUTE      r;

 fd = open("/dev/x25", O,RDW);
  /*prepare route*/
           initialize

 io.ic_cmd = N_X25_ADD_ROUTE;
 io.ic_timeout = 0; /*system default : 15 secs */
 io.ic_len = sizeof(X25_ROUTE);
 io.ic_dp = (char *)&r;

 if (ioctl (fd, I_STR, &ioc) <0) {
                  perror(" xxxioctl");
      }
 }

7.21 N_X25_FLUSH_ROUTES--Flush all Routes

Flushes all routes out of X25_ROUTE structure.

This ioctl can disrupt other users significantly. For this reason it can only be used by root.

Associated Structure

The x25_route_s data structure takes the following form:

typedef struct x25_route_s {
        uint32_t        index;          /* used for reading next route */
        u_char          r_type;
#define R_NONE          0
#define R_X121_HOST     1
#define R_X121_PREFIX   2
#define R_AEF_HOST      3
#define R_AEF_PREFIX    4
#define R_AEF_SOURCE    5
        CONN_ADR        x121;
        u_char          pid_len;
#define MAX_PID_LEN     4
        u_char          pid[MAX_PID_LEN];
        AEF             aef;
        int             linkid;
        X25_MACADDR     mac;
        int             use_count;
        char            pstn_number[16];
} X25_ROUTE;

Example

#include <sys/strupts.h>
 struct strioctl ioc ;
 int          fd ;
 X25_ROUTE      r;

 fd = open("/dev/x25", O,RDW);
  /*prepare route*/
           initialize

  io.ic_cmd = N_X25_FLUSH_ROUTES;
        io.ic_timout = 0;
        io.ic_len = 0;
        io.ic_dp = (char *)NULL;


        if (ioctl(x25s, I_STR, &ioc))
                perror("ioctl(X25_FLUSH_ROUTES)");
      }
 }

7.22 N_X25_GET_ROUTE--Obtain Routing Information

Obtains the routing information for a given destination address.

Associated Structure

The x25_route_s data structure takes the following form:

typedef struct x25_route_s {
        uint32_t        index;          /* used for reading next route */
        u_char          r_type;
#define R_NONE          0
#define R_X121_HOST     1
#define R_X121_PREFIX   2
#define R_AEF_HOST      3
#define R_AEF_PREFIX    4
#define R_AEF_SOURCE    5
        CONN_ADR        x121;
        u_char          pid_len;
#define MAX_PID_LEN     4
        u_char          pid[MAX_PID_LEN];
        AEF             aef;
        int             linkid;
        X25_MACADDR     mac;
        int             use_count;
        char            pstn_number[16];
} X25_ROUTE;

Example

#include <sys/strupts.h>
 struct strioctl ioc ;
 int          fd ;
 X25_ROUTE      r;

 fd = open("/dev/x25", O,RDW);
  /*prepare route*/
           initialize

 io.ic_cmd = N_X25_GET_ROUTE;
 io.ic_timeout = 0; /*system default : 15 secs */
 io.ic_len = sizeof(X25_ROUTE);
 io.ic_dp = (char *)&r;

 if (ioctl (fd, I_STR, &ioc) <0) {
                  perror(" xxxioctl");
      }
 }

7.23 N_X25_GET_NEXT_ROUTE--Get Next Routing Entry

Obtains routing information for the next entry in the routing table. When there are no routes left, error will be -1, and errno will be set to ENOENT.

Associated Structure

The x25_route_s data structure takes the following form:

typedef struct x25_route_s {
        uint32_t        index;          /* used for reading next route */
        u_char          r_type;
#define R_NONE          0
#define R_X121_HOST     1
#define R_X121_PREFIX   2
#define R_AEF_HOST      3
#define R_AEF_PREFIX    4
#define R_AEF_SOURCE    5
        CONN_ADR        x121;
        u_char          pid_len;
#define MAX_PID_LEN     4
        u_char          pid[MAX_PID_LEN];
        AEF             aef;
        int             linkid;
        X25_MACADDR     mac;
        int             use_count;
        char            pstn_number[16];
} X25_ROUTE;

Example

#include <sys/strupts.h>
 struct strioctl ioc ;
 int          fd ;
 X25_ROUTE      r;

 fd = open("/dev/x25", O,RDW);
  /*prepare route*/
           initialize

 io.ic_cmd = N_X25_GET_NEXT_ROUTE;
 io.ic_timeout = 0; /*system default : 15 secs */
 io.ic_len = sizeof(X25_ROUTE);
 io.ic_dp = (char *)&r;

 if (ioctl (fd, I_STR, &ioc) <0) {
                  perror(" xxxioctl");
      }
 }

7.24 N_X25_RM_ROUTE--Remove Route From X25_ROUTE

Removes the route for a given destination address.

This ioctl can disrupt other users significantly. For this reason it can only be used by root.

Associated Structure

The x25_route_s data structure takes the following form:

typedef struct x25_route_s {
        uint32_t        index;          /* used for reading next route */
        u_char          r_type;
#define R_NONE          0
#define R_X121_HOST     1
#define R_X121_PREFIX   2
#define R_AEF_HOST      3
#define R_AEF_PREFIX    4
#define R_AEF_SOURCE    5
        CONN_ADR        x121;
        u_char          pid_len;
#define MAX_PID_LEN     4
        u_char          pid[MAX_PID_LEN];
        AEF             aef;
        int             linkid;
        X25_MACADDR     mac;
        int             use_count;
        char            pstn_number[16];
} X25_ROUTE;

Example

#include <sys/strupts.h>
 struct strioctl ioc ;
 int          fd ;
 X25_ROUTE      r;

 fd = open("/dev/x25", O,RDW);
  /*prepare route*/
           initialize

 io.ic_cmd = N_X25_RM_ROUTE;
 io.ic_timeout = 0; /*system default : 15 secs */
 io.ic_len = sizeof(X25_ROUTE);
 io.ic_dp = (char *)&r;

 if (ioctl (fd, I_STR, &ioc) <0) {
                  perror(" xxxioctl");
      }
 }

7.25 N_zerostats--Reset X.25 Multiplexor Statistics Count

This ioctl is used to reset the statistics counts for the X.25 multiplexor.

This ioctl affects currently open connections and could therefore disrupt users significantly. For this reason it can only be used by root.

Chapter 8 Support Functions

Solstice X.25 provides a library of functions that can be used in applications.

Many of the functions make use of the padent and xhostent structures, they are therefore described first. A description of the functions follows, in alphabetical order. The tables below group the functions together according to function. The PAD and xhosts related functions are based on similar functions that are available with IP.

8.1 Linking to the Support Library

The support library for use on 32-bit systems resides in /opt/SUNWconn/x25/lib/libsx25.so. To link against it, use a command like this:

hostname% cc -o test test.c -L /opt/SUNWconn/x25/lib -R /opt/SUNWconn/x25/lib -lsx25

The support library for use on 64-bit systems resides in /opt/SUNWconn/x25/lib/sparcv9/libsx25.so. To link against it, use a command like this:

hostname% cc -o test test.c -L /opt/SUNWconn/x25/lib -R /opt/SUNWconn/x25/lib -lsx25

8.2 Function Summary

The header files used by the NLI support functions are contained in the /usr/include/netx25 directory.

These functions are related to the PAD Hosts Database:

These entries are related to the xhosts file:

These functions are related to X.25 addressing:

These functions are related to configuration files:

These functions are related to links:

8.3 The padent Structure

The padent structure is defined in the /usr/include/netx25/xnetdb.h file. It has this format:

struct    padent {
           struct xaddrf       xaddr;
           unsigned char       x29;
           struct extraformat  xtras;
           unsigned char       cud[MAxnetdb.hXCUDFSIZE + 1];
      };

The padent structure contains a single entry from the /etc/SUNWconn/x25/padmapconf file. This contains information about facilities and so on to be used when making PAD calls to a particular address.

The members of the padent structure are:

8.4 The xhostent Structure

The xhostent structure is defined in the /usr/include/netx25/xnetdb.h file. It has this format:

 struct   xhostent {
           char *h_name;
           char **h_aliases;
           int  h_addrtype;
           int  h_length;
           char *h_addr;
      };

The xhostent structure contains a single entry from the xhosts file. This contains information mapping host names to X.25 addresses and is used when making PAD calls. By default this file is in the /etc/SUNWconn/x25 directory.

The members of the structure are:

8.5 endpadent--Closes the PAD Hosts Database

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    endpadent()

Description

endpadent closes the PAD Hosts Database.

Arguments

endpadent does not take any parameters.

8.6 endxhostent--Closes the xhosts File

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    endxhostent()

Description

endxhostent closes the xhosts file. By default, this file is located in the /etc/SUNWconn/x25/ directory.

Arguments

There are no parameters.

Return Value

This function has no return values.

8.7 equalx25--Compares two X.25 addresses

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/x25db.h>

    int equalx25 (
      struct xaddrf *x1,
      struct xaddrf *x2
  );

Description

Compares two X.25 addresses by checking to see whether the two xaddrf structures holding them are the same.

Arguments

The members of the structure are:

Return Values

Returns 1 if the two structures are the same, and 0 if they are not.

8.8 getnettype--Get Type of Network for a Link

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    int getnettype (
      unsigned char *linkid
  );

Description

Determines the type of network referred to by a particular link identifier.

Arguments

The parameters are:

Return Values

A negative value indicates an invalid link identifier. The possible network types are:

8.9 getpadbyaddr--Get PAD Database Entry for Address

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    struct padent * getpadbyaddr(
       char *addr
    );

Description

getpadbyaddr returns a pointer to the padent structure, containing the entry from the PAD Hosts Database for the specified address. See "8.3 The padent Structure" for a description of the padent structure.

Arguments

The parameters are:

Return Value

getpadbyaddr returns a pointer to static storage. You must copy the value in order to keep and reuse it. A return value of 0 indicates that no match was found.

8.10 getpadent--Get Next Line in PAD Hosts Database

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    struct padent *getpadent( )

Description

The getpadent subroutine returns a pointer to a padent structure, which contains the next entry from the PAD Hosts Database. If necessary getpadent opens the file.

Arguments

There are no parameters.

Return Value

A return value of 0 indicates an error.

8.11 getxhostbyaddr--Get X.25 Host Name by Address

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    struct xhostent *getxhostbyaddr(
      char *addr,
      int len, int type
  );

Description

getxhostbyaddr searches the xhosts file for an entry with a matching X.25 host address. By default, this file is located in the /etc/SUNWconn/x25 directory. It returns a pointer to a xhostent structure containing information on the entry.

Arguments

The parameters are:

Return Value

getxhostbyaddr returns a pointer to static storage. You must copy the value in order to keep and reuse it. A return value of 0 indicates the address supplied is either invalid or unknown.

8.12 getxhostbyname--Get X.25 Address by Name

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    struct xhostent *getxhostbyname(
      char *name
  );

Description

getxhostbyname searches the xhosts file for an entry with a matching host name.By default, this file is located in the /etc/SUNWconn/x25 directory. It returns a pointer to a xhostent structure containing information on the entry.

Arguments

The parameters are:

Return Value

A pointer to the xhostent structure. A return value of 0 indicates the name supplied is either invalid or unknown.

8.13 getxhostent--Reads Next Line of xhosts File

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    struct xhostent *getxhostent(
       );

Description

getxhostent reads the next line of the /etc/SUNWconn/x25/hosts file. It opens the file if necessary.

Arguments

There are no parameters.

Return Value

A pointer to an xhostent structure. A return value of 0 indicates an error.

8.14 linkidtox25--Convert Link Identifier to Numeric Form

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    uint32_t linkidtox25(linkid)
unsigned char *linkid;

Description

Converts a character string link identifier to the numeric format used in X.25 primitives, with a range of 0 - 254.

Arguments

The parameters are:

Return Values

On success 0 is returned. On failure the value of MAX_LINKID is returned. By default, this is 255.

8.15 padtos--Convert PAD Database Structure Into String

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

  int padtos (
     struct padent *p,
     unsigned char *strp
  );
 

Description

Converts a PAD structure into a string containing all the facilities, CUGs, RPOAs and call user data defined in the PAD structure. The validity of the structure is checked before conversion.

Arguments

The parameters are:

The character string pointed to by strp takes this format:

~CUD facilities  year CUG RPOA

All of the values are optional:

For example this string:

~hello p7/9w4/2fr 80 B1234 T5678

has the following meaning:

The CUD is hello. There is a local-to-remote packet size of 7 a remote-to-local packet size of 9, a local-to-remote window size of 4 a remote -to-local window size of 2. Fast select and reverse charging are set. The X.29(80) Yellow Book recommendation is being used. The bilateral CUG is 1234 and the RPOA is 5678.

Return Values

On success this function returns 0. A negative return value indicates that the pad structure was invalid.

8.16 setpadent--Open and Rewind the PAD Hosts Database

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    void setpadent(
       int stayopen
    );

Description

setpadent opens and rewinds the PAD Hosts Database.

Arguments

The parameters are:

8.17 setxhostent--Open and Rewind the xhosts File

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    void setxhostent(
      int stayopen
  );

Description

setxhostent opens the xhosts file and rewinds it. By default, this file is located in the /etc/SUNWconn/x25 directory.

Arguments

The parameters are:

8.18 stox25--Convert X.25 Address to xaddrf Structure

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/x25db.h>

  int stox25 (
    unsigned char *cp,       /*  X.25 dot format address  */
    struct xaddrf *xad,      /*  The returned structure  */
    int lookup
  );

Description

Converts an X.25 format address into an xaddrf structure. Can also be used as a validity check for X.25 addresses.

Arguments

The parameters are:

Return Values

0 indicates successful completion. A negative return value indicates that the X.25 address was invalid.

8.19 x25_find_link_parameters--Finds Link Configuration Files and Builds a Linked List of Links

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/x25db.h>
 #include <netx25/config_functions.h>

    int x25_find_link_parameters (
      struct link_data ** lptr
  );

Description

This function scans the directory containing the X.25 configuration files and builds a linked list of data structures.

Arguments

The members of the structure are:

Return Values

Returns 0 on success.

8.20 x25_read_config_parameters--Reads a Configuration File Into a Data Structure

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>
 #include <netx25/config_functions.h>

    int x25_read_config_parameters (
                         int linkid
                         struct config_ident     *ipt,
                         struct LINK_config_data *lpt,
                         struct X25_config_data  *xpt,
                         struct MLP_config_data  *mpt,
                         struct LAPB_config_data *lbp,
                         struct LLC2_config_data *l2p,
                         struct WAN_config_data  *wpt,
                         int *flags
     );

Description

x25_read_config_parameters reads the configuration file for the specified link into a data structure.

Arguments

The parameters are:

Return Value

A return value of 0 indicates success.

8.21 x25_read_config_parameters_file--Reads a Configuration File Into a Data Structure

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>
 #include <netx25/config_functions.h>

    int X25_read_config_parameters_file (
                         char filename
                         struct config_ident     *ipt,
                         struct LINK_config_data *lpt,
                         struct X25_config_data  *xpt,
                         struct MLP_config_data  *mpt,
                         struct LAPB_config_data *lbp,
                         struct LLC2_config_data *l2p,
                         struct WAN_config_data  *wpt,
                         int *flag
     );

Use

x25_read_config_parameters reads the specified configuration file into a data structure.

Description

The parameters are:

Return Value

A return value of 0 indicates success.

8.22 x25_save_link_parameters--Update Configuration Files

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/x25db.h>
 #include <netx25/config_functions.h>

    int x25_save_link_parameters (
      struct link_data * linkid
  );

Description

This function takes the information in the LINK_config_data structures and updates the X.25 configuration files as necessary.

Arguments

The parameters are:

Return Values

Returns 0 on success.

8.23 x25_set_parse_error_function--Install a Function as Default Error Handler

Synopsis

#include <netx25/config_functions.h>

    int (*x25_set_parse_error_function(int (*func)(char *)))(char *)

Description

By default, errors are handled by printing a message to stderr and continuing. The x25_set_parse_error_function function allows a different function to be installed for use, for example with windowing programs.

Arguments

The parameters are:

Return Values

The address of the previous error function is returned.

8.24 x25_write_config_parameters--Writes a Data Structure Into a Configuration File Identified by a Link Number

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>
 #include <netx25/config_functions.h>

    int x25_write_config_parameters (struct config_ident *idptr,
                        struct LINK_config_data *ptr,
                        struct X25_config_data  *xptr,
                        struct MLP_config_data  *mptr,
                        struct LAPB_config_data *lbptr,
                        struct LLC2_config_data *l2ptr,
                        struct WAN_config_data  *wptr);

Description

x25_write_config_parameters writes the specified data structure(s) into a configuration file identified by the number of the link it configures.

Arguments

The parameters are:

Return Value

A return value of 0 indicates success.

8.25 x25_write_config_parameters_file--Writes a Data Structure Into a Configuration File Identified by a Filename

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>
 #include <netx25/config_functions.h>

     int x25_write_config_parameter_file (char *infname,
                        struct config_ident *idptr,
                        struct LINK_config_data *ptr,
                        struct X25_config_data  *xptr,
                        struct MLP_config_data  *mptr,
                        struct LAPB_config_data *lbptr,
                        struct LLC2_config_data *l2ptr,
                        struct WAN_config_data  *wptr);

Use

x25_write_config_parameters_file writes the specified data structure(s) into a configuration file identified by its filename.

Description

Return Value

A return value of 0 indicates an error.

8.26 x25tolinkid--Convert Numeric Link Identifier to String

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/xnetdb.h>

    int x25tolinkid(linkid, str_linkid)
uint32_t linkid;
unsigned char *str_linkid;

Description

Converts a link identifier of the numeric format used in X.25 primitives to a character string.

Arguments

The parameters are:

Return Values

On success 0 is returned. On failure -1 is returned.

8.27 x25tos--Convert xaddrf Structure to X.25 Address

Synopsis

#include <netx25/x25_proto.h>
 #include <netx25/x25db.h>

    int x25tos (
      struct xaddrf *xad,      /*  The X.25 structure   */
      unsigned char *cp,       /*  The returned string  */
      int lookup
  );

Description

Converts an xaddrf structure into an X.25 address. Before doing so, it checks the validity of the xaddrf structure.

Arguments

The parameters are:

Return Values

0 indicates successful completion. A negative return value indicates that the structure was invalid.

Chapter 9 Error Codes

This chapter contains a summary of error codes returned by the NLI programming interface.

9.1 Originator and Reason Tables

The following tables list the OSI error codes defined in <netx25/x25_proto.h>.

To identify the originator in N_RI and N_DI messages:

NS_USER 1

NS_PROVIDER 2

To specify the reason when the originator is the Network Service provider in N_DI messages:

To specify the reason when the originator is the Network Service user in N_DI messages:

To specify the reason when the originator is the Network Service provider in N_RI messages:

NS_RUNSPECIFIED 0xE9

NS_RCONGESTION 0xEA

To specify the reason when the originator is the Network Service user in N_RI messages:

NU_RESYNC 0xFA

These codes are defined in ISO 8208 and are mapped from X.25 cause and diagnostic codes as described in ISO 8878.

9.2 Decoding Error Codes

You can decode the error codes listed in this chapter using the /opt/SUNWconn/x25/bin/x25diags utility. Enter x25diags followed by the hexadecimal value returned. For example:

hostname% x25diags E4
diag is 228 (decimal),  E4 (hexa) :

OSI Network service problem :                                             
 Connection rejection -- reason unspecified (permanent condition)