Chapter 5. Network Provider Interface Programming Reference

This chapter discusses how the network provider interface (NPI) is used with X.25. It includes the primitives necessary to run NPI on an X.25 network and illustrates how programs can use NPI.

The network provider interface (NPI) provides a connection-oriented programming interface based on the UNIX International standard NPI V2.0. A connection-oriented subset of the standard has been implemented with enhancements to better suit it to an X.25 environment.

NPI consists of a set of primitives defined as STREAMS messages that provide access to the network layer services. The primitives are transferred between the network service (NS) user entity and the NS provider . An NPI primitive can be one of the following types:

The following figure illustrates the NPI:

Multiple NPI applications can access the X.25 protocol code.

The main features of the connection-mode communication are:

• Virtual circuits.
• Data transfer by a pre-established path.
• Data transfer reliability.

There are three phases to each instance of communication: connection establishment, data transfer, and connection termination. Units of data arrive at their destination in the same order as they departed their source, and the data is protected against duplication or loss. Along with the NPI primitives required to use the X.25 communications, there are a number of local management primitives that act locally to the NPI module.

For an application to use NPI, it would typically follow these steps:

1. Open a stream to the packet driver.
2. Push the NPI module.
3. Bind the application to the NPI module.
4. Submit a connection request to establish a connection between the local and remote X.25 systems.
5. Once the connection becomes established, transfer the required data.
6. Disconnect the two systems.

Sample Program

The use of NPI is demonstrated in a set of sample programs, which are in one of the following directories:

Local Management Primitives

Local management primitives are called to open, close, manage, and report information on a stream connected to the NPI module. They also manage options supported by it and report information on its supported parameter values.

The following local management primitives are supported:

Connection-Mode Primitive Formats and Rules

A network connection (NC), once established, is like a pair of queues linking two network addresses, or X.25 hosts. There is one queue for each direction of information flow, and each queue provides a flow control function for its information flow. The pair of queues is considered to be available for each potential NC. As with the X.25 protocol, NPI is a state machine, what action the application should take at a given time is sometimes due to the state that the protocol layer is in. For example, a call cannot be established until the application binds to the NPI module.

The following rules and guidelines apply to connection-mode service:

• Primitives can be put onto a queue by the application, subject to the control of the NPI module.
• The NPI module can add data to the queue.
• The receiving application controls the removal of objects from the queue. The objects are normally removed in the order they were received, except when:
  • The object is of a type defined to be able to advance ahead of the preceding object.

    Note: No object can advance ahead of another object of the same type.

  • The following object is defined to be destructive with respect to the preceding object on the queue. If necessary, the last object on the queue would be deleted to allow a destructive object to be put on the queue. For example, disconnect objects are defined to be destructive with respect to all other objects. Reset objects are defined to be destructive with respect to all other objects except connect, disconnect, and other reset objects.

The CONS primitives can be grouped as follows:

• Connection establishment primitives
• Normal data transfer primitives
• Receipt confirmation service primitives
• Reset service primitives
• Network connection release primitives

The following sections describe the format and rules of CONS primitives. The expedited data transfer service primitives are not supported.

Connection Establishment Primitives

The following network service primitives pertain to establishing a connection. To make a connection, the application must previously have bound to the NPI module.

A pair of queues is associated with the connection between the two systems when one of the NPI modules receives an N_CONN_REQ primitive. This is added to the applications read queue. The queues will remain associated with the connection until an N_DISCON_REQ primitive is either entered or removed from a queue. So once the application has bound to the NPI module, it associates a queue pair with a particular connection from the initial connection request/indication through to the final disconnection.

Normal Data Transfer Primitives

The following NPI primitives provide normal data transfer service:

These primitives provide a way to exchange data between the two systems. NPI refers to the units of data passed as network service data units (NSDUs). The exchange can occur in one direction or in both directions simultaneously. The X.25 layer preserves the sequence and the boundaries of these data units. If an N_DATA_REQ for an NSDU greater than the NIDU packet parameter is sent to NPI, the receiving application gets several N_DATA_IND primitives. It is the responsibility of the receiving application to check the N_MORE_DATA_FLAG in each data indication until the entire NSDU is received.

Receipt Confirmation Service Primitives

The following NPI primitives provide receipt confirmation service:

The N_RC_FLAG flag of the N_DATA_REQ primitive enables the receipt confirmation service. For each data unit received with the confirmation request parameter set, the receiving user should return an N_DATACK_REQ primitive. These acknowledgments are issued in the same order as the corresponding N_DATA_IND primitives are received. The NS provider responds to the primitives such that each acknowledgment is distinct from previous or subsequent acknowledgments. The application would have to correlate the acknowledgments with the original requests. When an NSDU has been segmented into more than one network interface data unit (NIDU), only the last NIDU can request receipt confirmation.

N_DATACK_REQ primitives are not subject to the flow control that affects N_DATA_REQ primitives at the same NC endpoint. N_DATACK_IND primitives are not subject to the flow control affecting N_DATA_IND primitives at the same NC endpoint.

To use receipt-confirmation, the two applications must agree upon its use at connection time, assuming it is supported by the underlying X.25 network. The REC_CONF_OPT flag of the N_CONN primitives requests receipt-confirmation service. As it is based on the X.25 D bit, the X.25 subscription being used must have D bit support.

Reset Service Primitives

The following NPI primitives provide a reset service:

An application would use the reset service to resynchronize the connection. The underlying X.25 layer uses the service to report a detected loss of unrecoverable data within the network service. The reset causes the NS provider to discard all data, expedited data, and receipt confirmations associated with this connection.

Network Connection Release Primitives

The following NPI primitives provide for network connection release:

The connection can be released in the following ways:

• Either or both of the NS users can issue a N_DISCON_REQ to release an established connection.
• The destination application can reject an N_CONN_IND primitive.
• The NS provider, or underlying network, can release the connection. (All failures by the network to maintain a connection are indicated in this manner.)
• The NS provider can fail to establish a requested NC.

A connection can be released at any time, regardless of its current state. A disconnection request cannot be rejected, so once invoked, the connection will be released. Once the release phase is entered, the network service does not guarantee delivery of any data.