Chapter 4. NLI Message Primitives
Prev |  | Next

## Chapter 4. NLI Message Primitives

This chapter contains the following sections:

- “Connect Request/Indication”

- “Connect Response/Confirmation”

- “Data”

- “Data Acknowledgment”

- “Expedited Data”

- “Expedited Data Acknowledgment”

- “Reset Request/Indication”

- “Reset Response/Confirmation”

- “Disconnect Request/Indication”

- “Disconnect Confirmation”

- “Abort Indication”

- “Listen Request/Response”

- “Listen Cancel Request/Response”

- “PVC Attach”

- “PVC Detach”

The control part of the messages passed across the NLI has a format 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 */
    };

The above messages have common fields, which can be accessed by the following type:

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

The messages to and from the application are classified as control or data, depending on the value of xl_type, which is either XL_CTL (control) or XL_DAT (data). Within each classification, the exact message identity is determined by the xl_command qualifier, and it is important to ensure that the combination of xl_type and xl_command is consistent. Each of these cases is described below.

## Connect Request/Indication

The control part of a Connect Request or Indication message has a format defined in the following structure:

    struct xcallf {
        unsigned char xl_type;     /* Always XL_CTL */
        unsigned char xl_command;  /* Always N_CI */
        int conn_id;               /* The connection id returned
                                      in Connect 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 and */
        struct xaddrf callingaddr; /* calling addresses */
        struct qosformat qos;      /* Facilities and CONS qos: if
                                      negotiate_qos is set */
    };

This structure is used when calls are requested or indicated across the X.25 interface. The data part of the message contains the Call User Data (CUD), if any. Other components are:

conn_id |  | For incoming calls, an attempt is made to match the called address and CUD with that of one of the listening applications. If a match is found, then the indication is passed to that application with a conn_id identifier, which must be returned in the Connect Response or Disconnect Request to accept or reject the connection.
CONS_call |  | When this field is set in Connect Requests, it indicates that CONS procedures should be used for the call.
negotiate_qos |  | A nonzero value shows that facilities and quality of service (QOS) are being negotiated. A zero value for the flag means the initiator is requesting all default values.
qos |  | This structure holds the facilities requested/indicated. See the section “Opening a Connection” in Chapter 5 for more information on QOS negotiation.
calledaddr |  | Holds the called address.
callingaddr |  | Holds the calling address.

## Connect Response/Confirmation

The control part of a Connect Response or Confirmation message is defined in the following structure:

    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 */
    };

This structure is used when calls are being accepted. The data part of the message contains the CUD, if any. The components are:

conn_id |  | The connection identifier conn_id must be returned in the Connect Response so that the procedures described in the section “Listening” in Chapter 5 can be guaranteed to operate properly.
CONS_call |  | When this field is set in Connect Responses, it indicates that CONS procedures should be used for the call.
negotiate_qos |  | A nonzero value shows that facilities and quality of service(QOS) are being negotiated. A zero value for the flag means the initiator is requesting all default values.
responder |  | Holds the responding address.
qos |  | Holds selected facilities and CONS QOS parameters to be passed to the initiator.

## Data

The control part of a Data message is defined in the following structure:

    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 */
                 setDbit,              /* Set when data carries
                                          X.25 D-bit */
                 setQbit;              /* Set when data carries
                                          X.25 Q-bit */
    };

This structure is used when data crosses the X.25 interface.

More |  | Shows whether there is more of this network service data unit to be received or sent.
setQbit |  | Used to request or indicate that the Q-bit is set when user data is transmitted or received.
setDbit |  | Used to request or indicate that the D-bit is set when user data is transmitted or received.

The following M_DATA portion contains the user data.

| Note: No acknowledgment 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.

## Data Acknowledgment

This following structure is associated with Data Acknowledgment messages:

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

This structure is used when an N-DATA-ACK request or an N-DATA-ACK indication crosses the X.25 interface.

When receipt confirmation from the remote application is active on a virtual circuit, this structure is used to acknowledge a previous N-DATA request/indication which had the D-bit set. 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.

For CONS calls, if receipt acknowledgment has been negotiated on the connection, then the above procedures should apply for any D-bit data sent or received. However to be compatible with previous releases of the NLI, the value of the reqackservice field in the qos structure can be set to request that the D-bit signifies receipt confirmation by the remote DTE only, thus ensuring no acknowledgment is expected or given.

For non CONS calls, only if the reqackservice field in the qos structure has been set to the appropriate value will the above procedures apply for any D-bit data sent or received. Otherwise no acknowledgment is expected or given.

## Expedited Data

The control part of an Expedited Data message has a format defined in the following structure:

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

This structure is used when Expedited Data, carried by an X.25 interrupt packet, crosses the X.25 interface. No parameters are required.

The following M_DATA portion of the message contains the user data. The Expedited Data is a confirmed primitive and must be acknowledged (see the next section) before another Expedited Data unit can be requested or indicated.

## Expedited Data Acknowledgment

The control part of the Expedited Data Acknowledgment message has a format defined in the following structure:

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

This structure is used when Expedited Data needs to be, or is being, acknowledged.

No parameters or user data are required.

## Reset Request/Indication

The control part of a Reset Request or an Indication message has a format defined in the following structure:

    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 */
    };

This structure is used when a Reset Request/Indication crosses the X.25 interface. Data is never associated with the primitive.

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

| Note: A Reset Request 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 Request—no Reset Confirmation is then required.

## Reset Response/Confirmation

The control part of a Reset Response or Confirmation message has a format defined in the following structure:

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

This structure is used when a Reset Response/Confirmation to a previous Reset crosses the X.25 interface. There are no parameters or data associated with the primitive. The comments above on Reset collision also apply here.

## Disconnect Request/Indication

The control part of a Disconnect Request or Indication message has a format defined in the following structure:

    struct xdiscf {
        unsigned char xl_type;      /* Always XL_CTL */
        unsigned char xl_command;   /* Always N_DI */
        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 */
        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 */
    };

This structure is used when a Disconnect Request/Indication crosses the X.25 interface. The data part of the message contains the clear user data, if any.

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 Disconnect Request on a non-CONS call, the user can specify a nonzero cause code. This has no effect for a CONS call; the value is set to zero by the system.

Other parameters are:

indicated_qos |  | A nonzero value shows that facilities and QOS are being indicated.
responder |  | This field contains the responding address.
deflected |  | This field is used in conjunction with the call_deflect facility in the qos structure, to convey the address of the remote DTE that the call is to be deflected to.
qos |  | Contains the facilities indicated. Currently, this is used with the charging information facility and the call deflection facility.

The Disconnect 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 Disconnect Confirmation to the application when the Disconnect Request is received. This guarantees that, once the Disconnect Confirmation is observed 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 Disconnect Confirmation 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.

| Note: A disconnect collision can occur. If it does, the “acknowledgment” can be taken to be complete.

## Disconnect Confirmation

The control part of a Disconnect Confirmation message has a format defined in the following structure:

    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 */
    };

This structure is used when a Disconnect Confirmation crosses the X.25 interface. There is no data associated with this primitive. The components of the structure are:

indicated_qos |  | A nonzero value shows that facilities and QOS are being indicated.
rqos |  | Contains the facilities indicated. Currently, this is used only with the charging information facility.

## Abort Indication

The control part of an Abort Indication message has a format defined in the following structure:

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

This structure is used when the X.25 driver needs to send a Disconnect Indication 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.

| Note: This message is used only in the upstream direction—never downstream.

## Listen Request/Response

The control part of a Listen Request or Response message has a format defined in the following structure:

    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 */
    };

This structure is used when an NLI application wants to register interest in incoming calls. The components are:

lmax |  | This is the maximum number of Connect Indications that the listener is willing to handle at one time. The data part of the message carries the address(es) in which the listener is interested (see also Chapter 3, “Listens”).
| Note: Listen Requests are cumulative, but the lmax value (number of simultaneously handled Connect Indications) is not. This means that several Listen Requests can be made on a single Stream, in which case the lmax value contained in the last Listen Request message specifies the number of simultaneously handled Connect Indications.
l_result |  | The result of the Listen Request is acknowledged upstream with the same message. An error in the parameters or a lack of resources to set up the listen results in this flag being set to a nonzero value.

For more information, see Chapter 3, “Listens.”

## Listen Cancel Request/Response

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

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

This structure is used to cancel an interest in incoming calls. Like the Listen Request message described above, this request is confirmed. In this case, a nonzero value of the c_result flag indicates failure of the operation to cancel a Listen Request. For example, the Listen Request was not present or some connect event is outstanding. Naturally, the closure of a stream on which there is a Listen Request also cancels the Listen Request, but in the case of the Listen Cancel Request message, the stream remains open.

| Note: The Listen Cancel Request removes all listen addresses from the stream. There is no way of cancelling a Listen Request on a particular address; this message is probably used when the use of the stream is about to be changed by the application.

## PVC Attach

The control part of a PVC Attach message has a format defined in the following structure:

    struct pvcattf {
        unsigned char xl_type;        /* Always XL_CTL */
        unsigned char xl_command;     /* Always N_PVC_ATTACH */
        unsigned short lci;           /* Logical channel */
        unsigned long sn_id;          /* Subnetwork identifier */
        unsigned char reqackservice;  /* Receipt Acknowledgement
                                         0 for next parameter
                                         implies use of
                                         default */
        unsigned char reqnsdulimit;
        int nsdulimit;
        int result_code;              /* Nonzero - error */
    };

This structure is used when a PVC Attach crosses the X.25 interface.

This message is used when a user wants to “attach” to a PVC. The components are:

lci |  | Contains the logical channel identifier (LCI) of the required PVC.
sn_id |  | Denotes the particular subnetwork for the PVC.
reqackservice |  | If nonzero, denotes that the receipt acknowledgment service is requested by use of the D-bit. Setting reqackservice to 1 signifies receipt confirmation by the remote DTE. Setting reqackservice to 2 signifies receipt confirmation by the remote application. In the case of receipt confirmation by the remote DTE, no acknowledgments are expected or given over the X.25 interface. In the case of receipt confirmation by the remote application, there is a one-to-one correspondence between D-bit data and acknowledgments, with one data acknowledgment being received or sent for each D-bit data packet sent or received over the X.25 interface.
reqnsdulimit |  | If this is non-zero, look at the field nsdulimit.
nsdulimit |  | Specifies the packet concatenation limit for network service data units (NSDU).
result_code |  | In the attach message sent to the user as acknowledgment, this field denotes whether or not the attach was successful.

## PVC Detach

The control part of a PVC Detach message has a format defined in the following structure:

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

This structure is used when a PVC Detach crosses the X.25 interface. This message is used when a user wants to “detach” from the PVC. This allows the use of the stream to be changed.

The PVC Detach message is acknowledged to the user by returning a PVC Detach message, in which the field reason_code denotes whether or not the PVC Detach was successful.

This message is also used by the X.25 driver to inform the user of some failure of the PVC. These include link down, remote end not responding, and so on. When the message is sent by the X.25 driver, the field reason_code gives the reason for the PVC Detach.

Prev | Table of Contents | Next
Chapter 3. Listens |  | Chapter 5. Programming Examples