Network Provider Interface Specification

Network Provider Interface

1 Introduction

This document specifies a STREAMS-based kernel-level instantiation of the ISO/CCITT network service definition. The Network Provider Interface (NPI) enables the user of a network layer service to access and use any of a variety of conforming network layer service providers without specific knowledge of the provider's protocol. The service interface is designed to support any connection-mode network protocol and connectionless network protocol. This interface only specifies access to network layer service providers, and does not address issues concerning network layer management,protocol performance, and performance analysis tools.

The specification assumes that the reader is familiar with the OSI reference model terminology, ISO/CCITT Network Layer Service, and STREAMS.

1.1 Related Documentation

• 1986 CCITT X.213 Recommendation [1]
• ISO 8348 [2]
• ISO 8348/AD1 [3]
• ISO 8473 [4]
• ISO 8208 [5]
• ISO 8878 [6]
• System V Interface Definition, Issue 2 - Volume 3 [7]

1.1.1 Role

This document specifies an interface that supports the service provided by the Network Services Definition for Open Systems Interconnection for CCITT Applications as described in CCITT Recommendation X.213 and ISO 8348 (for CONS) and ISO8348/Addendum 1 (for CLNS). These specifications are targeted for use by developers and testers of protocol modules that require network layer service.

1.2 Definitions, Acronyms, and Abbreviations

Calling NS user

An NS user that initiates a Network Connection (NC).

Called NS User

An NS user with whom a calling NS user wishes to establish a network connection (NC).

CLNP

Connection-less Network Protocol

CLNS

Connection-less Network Service

CONP

Connection Oriented Network Protocol

CONS

Connection Oriented Network Service

DLSAP

Data Link Service Access Point

ISO

International Organization for Standardization

NC

Network Connection

Network User

Kernel level protocol or user level application that is accessing the services of the network layer.

Network Provider

Network layer entity/entities that provide/s the services of the network interface.

NPI

Network Provider Interface

NS

Network Service

NIDU

Network Interface Data Unit

NSAP

Network Service Access Point

NSDU

Network Service Data Unit

OSI

Open Systems Interconnection

QOS

Quality of Service

STREAMS

A communication services development facility first available with UNIX System V Release 3

2 The Network Layer

The Network Layer provides the means to manage the operation of the network. It is responsible for the routing and management of data exchange between network-user entities.

2.1 Model of the NPI

The NPI defines the services provided by the network layer to the network-user at the boundary between the network layer and the network layer user entity. The interface consists of a set of primitives defined as STREAMS messages that provide access to the network layer services, and are transferred between the NS user entity and the NS provider. These primitives are of two types; ones that originate from the NS user, and others that originate from the NS provider. The primitives that originate from the NS user make requests to the NS provider, or respond to an event of the NS provider. The primitives that originate from the NS provider are either confirmations of a request or are indications to the NS user that the event has occurred. Figure 1 shows the model of the NPI.

Figure 1. Model of the NPI

The NPI allows the NS provider to be configured with any network layer user (such as the OSI Transport Layer) that also conforms to the NPI. A network layer user can also be a user program that conforms to the NPI and accesses the NS provider via “putmsg” and “getmsg” system calls.

2.2 NPI Services

The features of the NPI are defined in terms of the services provided by the NS provider,and the individual primitives that may flow between the NS user and the NS provider.

The services supported by the NPI are based on two distinct modes of communication, connection (CONS) and connectionless (CLNS). In addition, the NPI supports services for local management.

2.2.1 CONS

The main features of the connection mode communication are:

1. It is virtual circuit oriented;
2. It provides transfer of data via a pre-established path;
3. It provides reliable data transfer.

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 of data units within some specified quality of service.

2.2.2 CLNS

The main features of the connectionless mode communication are:

1. It is datagram oriented;
2. It provides transfer of data in self contained units;
3. There is no logical relationship between these units of data;
4. It is unreliable.

Connectionless mode communication has no separate phases. Each unit of data is transmitted from source to destination independently, appropriate addressing information is included with each unit of data. As the units of data are transmitted independently from source to destination, there are, in general, no guarantees of proper sequence and completeness of the data stream.

2.2.3 Local Management

The NPI specifications also define a set of local management functions that apply to both CONS and CLNS modes of communication. These services have local significance only.

Tables 1 and 2 summarizes the NPI service primitives by their state and service.

Table 1. Service Primitives for Connection Mode Data Transfer

Table 2. Service Primitives for Connectionless Mode Data Transfer

3 NPI Services Definition

This section describes the services of the NPI primitives. Time-sequence diagrams that illustrate the sequence of primitives are included. (Conventions for the time-sequence diagrams are defined in CCITT X.210 [8].) The format of the primitives will be defined later in this document.

3.1 Local Management Services Definition

The services defined in this section are outside the scope of the international standards. These services apply to both connection-mode as well as the connection-less modes of communication. They are invoked for the initialization/de-initialization of a stream connected to the NS provider. They are also used to manage options supported by the NS provider and to report information on the supported parameter values.

3.1.1 Network Information Reporting Service

This service provides information on the options supported by the NS provider.

• N_INFO_REQ: This primitive requests that the NS provider return the values of all the supported protocol parameters. This request may be invoked during any phase.
• N_INFO_ACK: This primitive is in response to the N_INFO_REQ primitive and returns the values of the supported protocol parameters to the NS user.

The sequence of primitives for network information management is shown in Figure 2.

Figure 2. Sequence of Primitives; Network Information Reporting Service

3.1.2 NS User Bind Service

This service allows a network address to be associated with a stream. It allows the NS user to negotiate the number of connect indications that can remain unacknowledged for that NS user (a connect indication is considered unacknowledged while it is awaiting a corresponding connect response or disconnect request from the NS user). This service also defines a mechanism that allows a stream (bound to a network address of the NS user) to be reserved to handle incoming calls only. This stream is referred to as the listener stream.

• N_BIND_REQ: This primitive requests that the NS user be bound to a particular network address, and negotiate the number of allowable outstanding connect indications for that address.
• N_BIND_ACK: This primitive is in response to the N_BIND_REQ primitive and indicates to the user that the specified NS user has been bound to a network address.

The sequence of primitives for NS user bind service is shown in Figure 3.

Figure 3. Sequence of Primitives; NS User Bind Service

3.1.3 NS User Unbind Service

This service allows the NS user to be unbound from a network address.

• N_UNBIND_REQ: This primitive requests that the NS user be unbound from the network address that it had previously been bound to.

The sequence of primitives for NS user unbind service is shown in Figure 4.

Figure 4. Sequence of Primitives; NS User Unbind & Receipt Acknowledgement

3.1.4 Receipt Acknowledgement Service

• N_OK_ACK: This primitive indicates to the NS user that the previous NS user originated primitive was received successfully by the NS provider.

An example showing the sequence of primitives for successful receipt acknowledgement is depicted in Figure 4.

3.1.5 Options Management Service

This service allows the NS user to manage the QOS parameter values associated with the NS provider.

• N_OPTMGMT_REQ: This primitive allows the NS user to select default values for QOS parameters within the range supported by the NS provider, and to indicate the default selection of receipt confirmation.

Figure 5 shows the sequence of primitives for network options management.

Figure 5. Sequence of Primitives; Options Management Service

3.1.6 Error Acknowledgement Service

• N_ERROR_ACK: This primitive indicates to the NS user that a non-fatal error has occurred in the last NS user originated request or response primitive (listed in Figure 6), on the stream.

Figure 6 shows the sequence of primitives for the error management primitive.

Figure 6. Sequence of Primitives; Error Acknowledgement Service

3.2 Connection-Mode Network Services Definition

This section describes the required network service primitives that define the CONS interface.

The queue model for CONS is discussed in more detail in CCITT X.213 section 9.2. The queue model represents the operation of a network connection in the abstract by a pair of queues linking the two network addresses. There is one queue for each direction of information flow. Each queue represents a flow control function in one direction of transfer. The ability of a user to add objects to a queue will be determined by the behaviour of the user removing objects from that queue, and the state of the queue. The pair of queues is considered to be available for each potential NC. Objects that are entered or removed from the queue are either as a result of interactions at the two network addresses, or as the result of NS provider initiatives.

• A queue is empty until a connect object has been entered and can be returned to this state, with loss of its contents, by the NS provider.
• Objects may be entered into a queue as a result of the actions of the source NS user, subject to control by the NS provider;
• Objects may also be entered into a queue by the NS provider.
• Objects are removed from the queue under the control of the receiving NS user.
• Objects are normally removed under the control of the NS user in the same order as they were entered except:
  • if the object is of a type defined to be able to advance ahead of the preceding object (however, no object is defined to be able to advance ahead of another object of the same type), or
  • if 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 will be deleted to allow a destructive object to be entered - they will therefore always be added to 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.

Table 3 shows the ordering relationships among the queue model objects.

Table 3. Ordering Relationships Between Queue Model Objects

3.2.1 Connection Establishment Phase

A pair of queues is associated with an NC between two network addresses when the NS provider receives an N_CONNECT_REQ primitive at one of the network addresses resulting in a connect object being entered into the queue. The queues will remain associated with the NC until a N_DISCON_REQ primitive (resulting in a disconnect object) is either entered or removed from a queue. Similarly, in the queue from the called NS user, objects can be entered into the queue only after the connect object associated with the N_CONN_RES has been entered into the queue. Alternatively, the called NS user can enter a disconnect object into the queue instead of the connect object to terminate the NC. The NC establishment procedure will fail if the NS provider is unable to establish an NC,or if the destination NS user is unable to accept the N_CONN_IND (see NC Release primitive definition).

3.2.1.1 User Primitives for Successful Network Connection Establishment

• N_CONN_REQ: This primitive requests that the NS provider make a connection to the specified destination.
• N_CONN_RES: This primitive requests that the NS provider accept a previous connection indication.

3.2.1.2 Provider Primitives for Successful Network Connection Establishment

• N_CONN_IND: This primitive indicates to the NS user that a connect request has been made by a user at the specified source address.
• N_CONN_CON: This primitive indicates to the NS user that a connect request has been confirmed on the specified responding address.

The sequence of primitives in a successful NC establishment is defined by the time sequence diagram as shown in Figure 7. The sequence of primitives for the NC response token value determination is shown in Figure 8 (procedures for NC response token value determination are discussed in sections 4.1.3 and 4.1.4.).

Figure 7. Sequence of Primitives; Successful NC Establishment

Figure 8. Sequence of Primitives; NC Response Token Value Determination

3.2.2 Data Transfer Phase

Flow control on the NC is done by management of the queue capacity, and by allowing objects of certain types to be inserted to the queues, as shown in Table 4.

Table 4. Flow Control Relationships Between Queue Model Objects

3.2.2.1 User Primitives for Data Transfer

• N_DATA_REQ: This primitive requests that the NS provider transfer the specified data.
• N_DATACK_REQ: This primitive requests that the NS provider acknowledge the data that had previously been received with receipt confirmation requested.
• N_EXDATA_REQ: This primitive requests that the NS provider transfer the specified expedited network service data unit.

3.2.2.2 Provider Primitives for Data Transfer

• N_DATA_IND: This primitive indicates to the NS user that this message contains data.
• N_DATACK_IND: This primitive indicates to the NS user that the remote NS user has acknowledged the data that had previously been sent with receipt confirmation requested.
• N_EXDATA_IND: This primitive indicates to the NS user that this message unit contains expedited data.

Figure 9 shows the sequence of primitives for successful normal data transfer. The sequence of primitives may remain incomplete if a N_RESET or N_DISCON primitive occurs.

Figure 9. Sequence of Primitives; Data Transfer

The sequence of primitives in a successful confirmation of receipt is defined in the time sequence diagram as shown in Figure 10.

Figure 10. Sequence of Primitives; Successful Confirmation of Receipt

The sequence of primitives as shown above may remain incomplete if an N_RESET or an N_DISCON primitive occurs (see Table 3). A NS user must not issue an N_DATACK_REQ primitive if no N_DATA_IND with confirmation request set has been received, or if all such N_DATA_IND have been previously acknowledged. Following a reset procedure (N_RESET_REQ or N_RESET_IND), a NS user may not issue aN_DATACK_REQ to acknowledge an outstanding N_DATA_IND received before the reset procedure was signalled.

Note — The withholding of confirmation of receipt by a NS user can have an effect on the attainable throughput on the NC.

The sequence of primitives for expedited data transfer is shown in the time sequence diagram in Figure 11. This sequence of primitives may remain incomplete if a N_RESET or N_DISCON primitive is issued.

Figure 11. Sequence of Primitives; Expedited Data Transfer

3.2.3 Reset Operation Primitives

The reset service is used by the NS user to resynchronize the use of the NC, or by the NS provider to report detected loss of unrecoverable data.

The reset procedure involves the following interactions:

1. a N_RESET_REQ from the NS user, followed by a N_RESET_CON from the NS provider; or
2. a N_RESET_IND from the NS provider, followed by a N_RESET_RES from the NS user.

The complete sequence of primitives depends upon the origin/s of the reset action. The reset service may be:

1. invoked by one NS user, leading to interaction (A) with that NS user and interaction (B) with the peer NS user;
2. invoked by both NS users, leading to interaction (A) with both NS users;
3. invoked by the NS provider, leading to interaction (B) with both NS users;
4. invoked by one NS user and the NS provider, leading to interaction (A) with the originating NS user and (B) with the peer NS user.

The N_RESET_REQ acts as a synchronization mark in the flow of N_DATA,N_EXDATA, and N_DATACK primitives transmitted by the issuing NS user; the N_RESET_IND acts as a synchronization mark in the flow of N_DATA, N_EXDATA,and N_DATACK primitives received by the receiving NS user. Similarly, N_RESET_RES acts as a synchronization mark in the flow of N_DATA, N_EXDATA,and N_DATACK primitives transmitted by the responding NS user, while the N_RESET_CON acts as a synchronization mark in the flow of N_DATA, N_EXDATA, and N_DATACK primitives received by the NS user that originally issued the reset. The resynchronizing properties of the reset service are the following:

1. All N_DATA, N_EXDATA, and N_DATACK primitives issued before issuing the N_RESET_REQ/N_RESET_RES that have not been delivered to the other NS user before the N_RESET_IND/N_RESET_CON are issued by the NS provider,should be discarded by the NS provider.
2. Any N_DATA, N_EXDATA, and N_DATACK primitives issued after the synchronization mark will not be delivered to the other NS user before the synchronization mark is received.

3.2.3.1 User Primitives for Reset Operations

• N_RESET_REQ: This primitive requests that the NS provider reset the network connection.
• N_RESET_RES: This primitive indicates to the NS provider that the NS user has accepted a reset indication.

3.2.3.2 Provider Primitives for Reset Operations

• N_RESET_IND: This primitive indicates to the NS user that the network connection has been reset.
• N_RESET_CON: This primitive indicates to the NS user that the reset request has been confirmed.

The sequence of primitives as shown in Figures 12, 13, 14, and 15 may remain in complete if a N_DISCON primitive occurs.

Figure 12. Sequence of Primitives; NS User Invoked Reset

Figure 13. Sequence of Primitives; Simultaneous NS User Invoked Reset

Figure 14. Sequence of Primitives; NS Provider Invoked Reset

Figure 15. Sequence of Primitives; Simultaneous NS User & NS Provider

3.2.4 Connection Termination Phase

The NC release procedure is initialized by the insertion of a disconnect object (associated with a N_DISCON_REQ) into the queue. As shown in Table 3, the disconnect procedure is destructive with respect to other objects in the queue, and eventually results in the emptying of queues and termination of the NC connection.

The sequence of primitives depends on the origin of the release action. The sequence may be:

1. invoked by one NS user, with a request from that NS user leading to an indication to the other;
2. invoked by both NS users, with a request from each of the NS users;
3. invoked by the NS provider, with an indication to each of the NS users;
4. invoked independently by one NS user and the NS provider, with a request from the originating NS user and an indication to the other.

3.2.4.1 User Primitives for Connection Termination

• N_DISCON_REQ: This primitive requests that the NS provider deny an outstanding request for a connection or disconnect an existing connection.

3.2.4.2 Provider Primitives for Connection Termination

• N_DISCON_IND: This primitive indicates to the NS user that either a request for connection has been denied or an existing connection has been terminated.

The sequence of primitives are shown in the time sequence diagrams in Figures 16, 17, 18, and 19.

Figure 16. Sequence of Primitives; NS User Invoked Release

Figure 17. Sequence of Primitives; Simultaneous NS User Invoked Release

Figure 18. Sequence of Primitives; NS Provider Invoked Release

Figure 19. Sequence of Primitives; Simultaneous NS User & NS Provider

A NS user may reject an NC establishment attempt by issuing a N_DISCON_REQ. The originator parameter in the N_DISCON primitives will indicate NS user invoked release. The sequence of events is shown in Figure 20.

Figure 20. Sequence of Primitives; NS User Rejection of an NC Establishment Attempt

If the NS provider is unable to establish an NC, it indicates this to the requester by an N_DISCON_IND. The originator in this primitive indicates an NS provider invoked release. This is shown in Figure 21.

Figure 21. Sequence of Primitives; NS Provider Rejection of an NC Establishment Attempt

3.3 Connectionless Network Services Definition

The CLNS allows for the transfer of the NS user data in one or both directions simultaneously without establishing a network connection. A set of primitives are defined that carry user data and control information between the NS user and NS provider entities. The primitives are modelled as requests initiated by the NS user and indications initiated by the NS provider. Indications may be initiated by the NS provider independently from requests by the NS user.

The connectionless network service consists of one phase.

3.3.1 User Request Primitives

• N_UNITDATA_REQ: This primitive requests that the NS provider send the data unit to the specified destination.

3.3.2 Provider Response Primitives

• N_UNITDATA_IND: This primitive indicates to the NS user that a data unit has been received from the specified source address.

Figure 22 shows the sequence of primitives for the connectionless mode of data transfer.

Figure 22. Sequence of Primitives; Connectionless Data Transfer

• N_UDERROR_IND: This primitive indicates to the NS user that the data unit with the specified destination address and QOS parameters produced an error. This primitive is specific to CLNS.

Figure 23 shows the sequence of primitives for the CLNS error management primitive.

Figure 23. Sequence of Primitives; CLNS Error Indication Service

4 NPI Primitives

This section describes the format and parameters of the NPI primitives (Appendix A shows the mapping of the NPI primitives to the primitives defined in ISO 8348 and CCITT X.213). In addition, it discusses the states the primitive is valid in, the resulting state, and the acknowledgement that the primitive expects. (The state/event tables for these primitives are shown in Appendix B. The precedence tables for the NPI primitives are shown in Appendix C.) Rules for OSI conformance are described in Addendum 1 to this document.

Tables 5, 6, and 7 provide a summary of the NS primitives and their parameters.

Table 5. NC Establishment Network Service Primitives

Table 6. Data Transfer Network Service Primitives

Table 7. NC Release Network Service Primitives

4.1 Management Primitives

These primitives apply both to CONS as well as CLNS.

4.1.1 Network Information Request

N_INFO_REQ

This primitive requests the NS provider to return the values of all supported protocol parameters (see under N_INFO_ACK), and also the current state of the NS provider (as defined in Appendix B). This primitive does not affect the state of the network provider and does not appear in the state tables.

Format

The format of the message is one M_PCPROTO message block and its structure is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_INFO_REQ */
     } N_info_req_t;
     

Parameters

PRIM_type

Indicates the primitive type.

Valid States

This primitive is valid in any state where a local acknowledgement is not pending.

New State

The new state remains unchanged.

Acknowledgements

This primitive requires the NS provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful: Acknowledgement of the primitive via the N_INFO_ACK primitive.
• Non-fatal_errors: There are no errors associated with the issuance of this primitive.

4.1.2 Network Information Acknowledgement

N_INFO_ACK

This primitive indicates to the NS user any relevant protocol-dependent parameters. ¹ It should be initiated in response to the N_INFO_REQ primitive described above.

Format

The format of this message is one M_PCPROTO message block and its structure is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_INFO_ACK */
             ulong NSDU_size;                /* maximum NSDU size */
             ulong ENSDU_size;               /* maximum ENSDU size */
             ulong CDATA_size;               /* connect data size */
             ulong DDATA_size;               /* discon data size */
             ulong ADDR_size;                /* address size */
             ulong ADDR_length;              /* address length */
             ulong ADDR_offset;              /* address offse t */
             ulong QOS_length;               /* length of default QOS values */
             ulong QOS_offset;               /* offset of default QOS values from
                                                the beginning of block */
             ulong QOS_range_length;         /* length of range of QOS values */
             ulong QOS_range_offset;         /* offset of range of QOS values from
                                                the beginning of block */
             ulong OPTIONS_flags;            /* bit masking for options supported */
             ulong NIDU_size;                /* network interface data unit size */
             long SERV_type;                 /* service type */
             ulong CURRENT_state;            /* current state */
             ulong PROVIDER_type;            /* type of provider */
             ulong NODU_size;                /* optimal NSDU size */
             ulong PROTOID_length;           /* length of bound protocol ids */
             ulong PROTOID_offset;           /* offset of bound protocol ids */
             ulong NPI_version;              /* version number of NPI that's
                                                supported */
     } N_info_ack_t;
     
     /* Flags to indicate support of NS provider options */
     #define REC_CONF_OPT    0x00000001L
     #define EX_DATA_OPT     0x00000002L
     #define DEFAULT_RC_SEL  0x00000004L
     
     /* Service types supported by the NS provider */
     #define N_CONS 1
     #define N_CLNS 2
     
     /* Valid provider types */
     #define N_SNICFP 1
     #define N_SUBNET 2

Parameters

The above fields have the following meaning:

PRIM_type

Indicates the primitive type.

NSDU_size

Specifies the maximum size (in octets) of a Network Service Data Unit (NSDU) supported by the NS provider.

ENSDU_size

Specifies the maximum size (in octets) of an Expedited Network Service Data Unit (ENSDU) supported by the NS provider.

CDATA_size

Specifies the maximum number of octets of data that may be associated with connection establishment primitives.

DDATA_size

Specifies the maximum number of octets of data that may be associated with the disconnect primitives.

ADDR_size

Specifies the maximum size (in decimal digits) of a network address.

ADDR_length

Specifies the length in bytes of the network address bound on the STREAM on which the N_INFO_REQ was issued (a network address is bound to a STREAM via a N_BIND_REQ).

ADDR_offset

Specifies the offset of the bound network address from the beginning of the M_PCPROTO message block (this field should be ignored if the ADDR_length field is zero).

QOS_length

in an addendum to this document. In the connection-mode environment, when this primitive is invoked before the NC is established on the stream, the values returned specify the the default values supported by the NS provider. When this primitive is invoked after a NC has been established on the stream, the values returned indicate the negotiated values for the QOS parameters. In the connection-less environment, these values represent the default or the selected QOS parameter values. In case a QOS parameter is not supported by the NS Provider, a value of QOS_UNKNOWN will be returned. In the case where no QOS parameters are supported by the NS provider, this field will be zero.

QOS_offset

Indicates the offset of the QOS parameters from the beginning of the M_PCPROTO message block.

QOS_range_length

Indicates the length in bytes, of the available range of QOS parameters values supported by the NS provider. These ranges are used by the NS user to select QOS parameter values that are valid with the NS provider. QOS parameter values are selected, or the default values altered via the N_OPTMGMT_REQ primitive. In the connection-mode environment, the values for end-to-end QOS parameters may be specified with the N_CONN primitives for negotiation. If the NS provider does not support a certain QOS parameter, its value will be set to QOS_UNKNOWN. In the case where no QOS parameters are supported by the NS provider, the length of this field will be zero.

QOS_range_offset

Indicates the offset of the range of QOS parameter values from the beginning of the M_PCPROTO message block.

OPTIONS_flags

Defines flags that indicate whether the options described below are supported by the NS provider. The possible options are receipt confirmation, expedited data and default selection for use of receipt confirmation.

NIDU_size

This indicates the amount of user data that may be present in a N_DATA primitive. The NIDU_size should not be larger than the NSDU_size specification.

SERV_type

Specifies the service type supported by the NS provider. The possible values can be N_CONS, N_CLNS, (or both as indicated by using N_CONS|N_CLNS).

CURRENT_state

This indicates the current state of the NS provider.

PROVIDER_type

This indicates the type of NS provider. The possible values can be N_SNICFP or N_SUBNET. The value N_SNICFP indicates that the provider is the Subnetwork Independent Convergence Function/Protocol sub-layer of the network layer. The value N_SUBNET indicates that the provider is a subnetwork.

NODU_size

This specifies the optimal NSDU size (in octets) of an NSDU given the current routing information.

PROTOID_length

This specifies the length of the protocol ids that were bound using the N_BIND_REQ.

PROTOID_offset

This specifies the offset of the protocol ids that were bound using the N_BIND_REQ.

NPI_version

This indicates the current version of NPI that is supported.

Flags

REC_CONF_OPT

When set, it indicates that the NS provider supports receipt confirmation.

This flag is used only in the connection-mode environment.

EX_DATA_OPT

When set, it indicates that the NS provider supports expedited data transfer.

This flag is used only in the connection-mode environment.

DEFAULT_RC_SEL

When set, it indicates that the default selection is for the use of receipt confirmation for every N_DATA_REQ primitive (This parameter is applicable only when use of receipt confirmation is successfully negotiated via the N_CONN primitives).

This flag is used only in the connection-mode environment.

N_CONS

When set, it indicates that the NS provider supports connection-mode network services.

N_CLNS

When set, it indicates that the NS provider supports connection-less network services.

Valid States

This primitive is valid in any state in response to a N_INFO_REQ primitive.

New State

The state remains the same.

4.1.3 Bind Protocol Address Request

N_BIND_REQ

This primitive requests that the NS provider bind a NS user entity to a network address and negotiate the number of connect indications allowed to be outstanding by the NS provider for the specified NS user entity being bound.

Format

The format of the message is one M_PROTO message block and its structure is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_BIND_REQ */
             ulong ADDR_length;              /* length of address */
             ulong ADDR_offset;              /* offset of address */
             ulong CONIND_number;            /* req # of conn-indications to be
                                                queued */
             ulong BIND_flags;               /* flags associated with N_BIND_REQ */
             ulong PROTOID_length;           /* length of the protocol id */
             ulong PROTOID_offset;           /* offset of protocol id */
     } N_bind_req_t;
     
     /* Flags associated with N_BIND_REQ */
     #define DEFAULT_LISTENER    0x00000001L
     #define TOKEN_REQUEST       0x00000002L
     #define DEFAULT_DEST        0x00000004L

Parameters

PRIM_type

Is the primitive type.

ADDR_length

Is the length in bytes of the network address to be bound to the stream.

ADDR_offset

Is the offset from the beginning of the M_PROTO block where the network address begins.

CONIND_number

Is the requested number of connect indications allowed to be outstanding by the NS provider for the specified protocol address. (If the number of outstanding connect indications equals CONIND_number, the NS provider need not discard further incoming connect indications, but may choose to queue them internally until the number of outstanding connect indications drops below the CONIND_number.) Only one stream per network address is allowed to have a CONIND_number value greater than zero. This indicates to the network provider that this stream is the listener stream for the NS user. This stream will be used by the NS provider for connect indications for that network address.

If a stream is bound as a listener stream, it will not be able to initiate connect requests. If the NS user attempts to send an N_CONN_REQ primitive down this stream, an N_ERROR_ACK message will be sent to the NS user by the NS provider with an error value of NACCESS.

This field should be ignored in CLNS.

PROTOID_length

Is the length in bytes of the protocol ids to be bound to the stream.

PROTOID_offset

Is the offset from the beginning of the M_PROTO block where the protocol id begins.

Flags

DEFAULT_LISTENER

When set, this flag indicates that this stream is the “default listener stream”. This stream is used to pass connect indications for all incoming calls that contain protocol identifiers that are not bound to any other listener, or when a listener stream with CONIND_number value of greater than zero is not found. Also, the default listener will receive all incoming call indications that contain no user data.

Only one default listener stream is allowed per occurrence of NPI. An attempt to bind a default listener stream when one is already bound should result in an error (of type NBOUND).

The DEFAULT_LISTENER flag is ignored in CLNS.

TOKEN_REQUEST

When set, this flag indicates to the NS provider that the NS user has requested that a “token” be assigned to the stream (to be used in the NC response message), and the token value be returned to the NS user via the N_BIND_ACK primitive.

The token assigned by the NS provider can then be used by the NS user in a subsequent N_CONN_RES primitive to identify the stream on which the NC is to be established.

The TOKEN_REQUEST flag is ignored in CLNS.

DEFAULT_DEST

When set, this flag indicates that this stream is the “default destination stream.” This stream will receive all packets destined for the NSAP specified in the bind request. If no NSAP is indicated in the bind request, then this stream should receive all packets destined to an NSAP which is bound to no other stream.

Only one default destination stream per NSAP is allowed per occurrence of NPI. An attempt to bind a default destination stream to an NSAP when one is already bound should result in an error of type NBOUND.

The DEFAULT_DEST flag is ignored in the CONS.

Valid States

This primitive is valid in state NS_UNBND (see Appendix B).

New State

The new state is NE_WACK_BREQ.

Acknowledgements

The NS provider will generate one of the following acknowledgements upon receipt of the N_BIND_REQ primitive:

• Successful: Correct acknowledgement of the primitive is indicated using the N_BIND_ACK primitive.
• Non-fatal errors: These errors will be indicated using the N_ERROR_ACK primitive. The applicable non-fatal errors are as follows:

  NBADADDR

  The network address was in an incorrect format or the address contained illegal information. It is not intended to indicate protocol errors.

  
  

  NBOUND

  The NS user attempted to bind a second stream to a network address with the CONIND_number set to a non-zero value, or attempted to bind a second stream with the DEFAULT_LISTENER flag value set to non-zero.

  
  

  NNOADDR

  The NS provider could not allocate an address.

  
  

  NACCESS

  The user did not have proper permissions for the use of the requested address.

  
  

  NOUTSTATE

  The primitive was issued from an invalid state.

  
  

  NSYSERR

  A system error has occurred and the UNIX system error is indicated in the primitive.

  
  

  NNOPROTOID

  Protocol identifier could not be allocated.

4.1.4 Bind Protocol Address Acknowledgement

N_BIND_ACK

This primitive indicates to the NS user that the specified network user entity has been bound to the requested network address and that the specified number of connect indications are allowed to be queued by the NS provider for the specified network address.

Format

The format of the message is one M_PCPROTO message block, and its structure is the following:

     typedef struct {
             ulong PRIM_type;                /* always N_BIND_ACK */
             ulong ADDR_length;              /* address length */
             ulong ADDR_offset;              /* offset of address */
             ulong CONIND_number;            /* connection indications */
             ulong TOKEN_value;              /* NC response token value */
             ulong PROTOID_length;           /* length of protocol id */
             ulong PROTOID_offset;           /* offset from beg. of block */
     } N_bind_ack_t;
     

Parameters

PRIM_type

Indicates the primitive type.

ADDR_length

Is the length of the network address that was bound.

ADDR_offset

Is the offset from the beginning of the M_PCPROTO block where the network address begins.

CONIND_number

Is the accepted number of connect indications allowed to be outstanding by the NS provider for the specified network address. If its value is zero, this stream cannot acceptN_CONN_IND messages. If its value is greater than zero, then the NS user can accept N_CONN_IND messages up to the value specified in this parameter before having to respond with a N_CONN_RES or a N_DISCON_REQ message.

This field should be ignored for CLNS.

TOKEN_value

Conveys the value of the “token” assigned to this stream that can be used by the NS user in a N_CONN_RES primitive to accept a NC on this stream. It is a non-zero value, and is unique to all streams bound to the NS provider.

This field should be ignored for CLNS.

PROTOID_length

Conveys the length of the protocol ids that were bound.

PROTOID_offset

Conveys the offset of the protocol ids that were bound.

The proper alignment of the address in the M_PCPROTO message block is not guaranteed.

Bind Rules:

The following rules apply to the binding of the specified network address to the stream:

• If the ADDR_length field in the N_BIND_REQ primitive is zero, then the NS provider is to assign a network address to the user.
• The NS provider is to bind the network address as specified in the N_BIND_REQ primitive. If the NS provider cannot bind the specified address, it may assign another network address to the user. It is the network user's responsibility to check the network address returned in the N_BIND_ACK primitive to see if it is the same as the one requested.

The following rules apply to negotiating CONIND_number argument:

• The CONIND_number in the N_BIND_ACK primitive must be less than or equal to the corresponding requested number as indicated in the N_BIND_REQ primitive.
• Only one stream that is bound to the indicated network address may have a negotiated accepted number of maximum connect requests greater than zero. If a N_BIND_REQ primitive specifies a value greater than zero, but another stream has already bound itself to the given network address with a value greater than zero, the NS provider should assign another protocol address to the user.
• If a stream with CONIND_number greater than zero is used to accept a connection,the stream will be found busy during the duration of that connection and no other streams may be bound to that network address with a CONIND_number greater than zero. This will prevent more than one stream bound to the identical network address from accepting connect indications.
• A stream requesting a CONIND_number of zero should always be legal. This indicates to the NS provider that the stream is to be used to request connections only.
• A stream with a negotiated CONIND_number greater than zero may generate connect requests or accept connect indications.

If the above rules result in an error condition, then the NS provider must issue anN_ERROR_ACK primitive to the NS user specifying the error as defined in the description of the N_BIND_REQ primitive.

Valid States

This primitive is in response to a N_BIND_REQ primitive and is valid in the state NS_WACK_BREQ.

New State

The new state is NS_IDLE.

4.1.5 Unbind Protocol Address Request

N_UNBIND_REQ

This primitive requests that the NS provider unbind the NS user entity that was previously bound to the network address.

Format

The format of the message is one M_PROTO block, and its structure is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_UNBIND_REQ */
     } N_unbind_req_t;
     

Parameters

PRIM_type

Indicates the primitive type.

Valid States

This primitive is valid in the NS_IDLE state.

New State

The new state is NS_WACK_UREQ.

Acknowledgements

This primitive requires the NS provider to generate the following acknowledgements upon receipt of the primitive:

• Successful: Correct acknowledgement of the primitive is indicated via the N_OK_ACK primitive, see N_OK_ACK.
• Unsuccessful (Non-fatal errors): These errors will be indicated via the N_ERROR_ACK primitive. The applicable non-fatal errors are as follows:

  NOUTSTATE

  The primitive was issued from an invalid state.

  
  

  NSYSERR

  A system error has occurred and the UNIX system error is indicated in the primitive.

4.1.6 Network Options Management Request

N_OPTMGMT_REQ

This primitive allows the NS user to manage the QOS parameter values associated with the stream.

Format

The format of the message is one M_PROTO message block, and its structure is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_OPTMGMT_REQ */
             ulong QOS_length;               /* length of QOS values */
             ulong QOS_offset;               /* offset of QOS values */
             ulong OPTMGMT_flags;            /* default receipt conf. selection */
     } N_optmgmt_req_t;
     

Parameters

PRIM_type

Indicates the primitive type.

QOS_length

Indicates the length of the default values of the QOS parameters as selected by the NS user. In the connection-mode environment these values will be used in subsequent N_CONN_REQprimitives on the stream that do not specify values for these QOS parameters. In the connection-less environment, these values represent the selected QOS values that would apply to each unit data transmission. If the NS user cannot determine the value of a QOS parameter, its value should be set to QOS_UNKNOWN. If the NS user does not specify any QOS parameter values, the length of this field should be set to zero.

QOS_offset

Indicates the offset of the QOS parameters from the beginning of the M_PROTO message block.

Flags

DEFAULT_RC_SEL

When set, it indicates to the NS provider that the NS user's default selection is for the use of receipt confirmation with every N_DATA_REQ message (applicable only when its use is successfully negotiated via the N_CONN primitives). This default indication is used only when the M_PROTO message block is not present in the N_DATA_REQ primitive.

This flag should be ignored in the connection-less environment.

Valid States

This primitive is valid in the NS_IDLE state.

New State

The new state is NS_WACK_OPTREQ.

Acknowledgements

The N_OPTMGMT_REQ primitive requires the NS provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful: Acknowledgement is via the N_OK_ACK primitive. At successful completion, the resulting state is NS_IDLE.
• Non-fatal errors: These errors are indicated in the N_ERROR_ACK primitive. The resulting state remains unchanged. The applicable non-fatal errors are defined as follows:

  NOUTSTATE

  The primitive was issued from an invalid state.

  
  

  NBADQOSPARAM

  The QOS parameter values specified are outside the range supported by the NS provider.

  
  

  NBADQOSTYPE

  The QOS structure type is not supported by the NS provider.

  
  

  NSYSERR

  A system error has occurred and the UNIX system error is indicated in the primitive.

4.1.7 Error Acknowledgement

N_ERROR_ACK

This primitive indicates to the NS user that a non-fatal error has occurred in the last network-user-originated primitive. This may only be initiated as an acknowledgement for those primitives that require one. It also indicates to the user that no action was taken on the primitive that caused the error.

Format

The format of the message is one M_PCPROTO message block, and its structure is asfollows:

     typedef struct {
             ulong PRIM_type;                /* always N_ERROR_ACK */
             ulong ERROR_prim;               /* primitive in error */
             ulong NPI_error;                /* NPI error code */
             ulong UNIX_error;               /* UNIX system error code */
     } N_error_ack_t;
     

Parameters

PRIM_type

Identifies the primitive type

ERROR_prim

Identifies the primitive type that caused the error.

NPI_error

Contains the Network Provider Interface error code.

UNIX_error

Contains the UNIX system error code. This may only be non-zero if the NPI_error is equal to NSYSERR.

Valid Error Codes

The following error codes are allowed to be returned:

NBADADDR

The network address as specified in the primitive was in an incorrect format, or the address contained illegal information.

NBADOPT

The options values as specified in the primitive were in an incorrect format, or they contained illegal information.

NBADQOSPARAM

The QOS values specified are outside the range supported by the NS provider. illegal.

NBADQOSTYPE

The QOS structure type is not supported by the NS provider.

NBADTOKEN

Token used is not associated with an open stream.

NNOADDR

The NS provider could not allocate an address.

NACCESS

The user did not have proper permissions.

NOUTSTATE

The primitive was issued from an invalid state.

NBADSEQ

The sequence number specified in the primitive was incorrect or illegal.

NBADFLAG

The flags specified in the primitive were incorrect or illegal.

NBADDATA

The amount of user data specified was outside the range supported by the NS provider.

NSYSERR

A system error has occurred and the UNIX system error is indicated in the primitive.

NNOTSUPPORT

Specified primitive type is not known to the NS provider.

Valid States

This primitive is valid in all states that have a pending acknowledgement or confirmation.

New State

The new state is the same as the one from which the acknowledged request or response was issued.

4.1.8 Successful Receipt Acknowledgement

N_OK_ACK

This primitive indicates to the NS user that the previous network- user-originated primitive was received successfully by the network provider. It does not indicate to the NS user any network protocol action taken due to the issuance of the last primitive. The N_OK_ACK primitive may only be initiated as an acknowledgement for those user originated primitives that have no other means of confirmation.

Format

The format of the message is one M_PCPROTO message block, and its structure is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_OK_ACK */
             ulong CORRECT_prim;             /* primitive being acknowledged */
     } N_ok_ack_t;
     

Parameters

PRIM_type

Identifies the primitive.

CORRECT_prim

Identifies the successfully received primitive type.

Valid States

This primitive is issued in states

• NS_WACK_UREQ,
• NS_WACK_OPTREQ,
• NS_WACK_RRES,
• NS_WACK_CRES,
• NS_WACK_DREQ6,
• NS_WACK_DREQ7,
• NS_WACK_DREQ9,
• NS_WACK_DREQ10, and
• NS_WACK_DREQ11,

• N_UNBIND_REQ,
• N_RESET_RES,
• N_CONN_RES, and
• N_DISCON_REQ

New State

The resulting state depends on the current state (see Appendix B, Tables B-7 and B-8.)

4.2 CONS Primitive Format and Rules

This section describes the format of the CONS primitives and the rules associated with these primitives. The default values of the QOS parameters associated with a NC may be selected via the N_OPTMGMT_REQ primitive.

4.2.1 Connection Establishment Primitives

The following network service primitives pertain to the establishment of an NC, provided the NS users exist, and are known to the NS provider.

4.2.1.1 Network Connection Request

N_CONN_REQ

This primitive requests that the NS provider make a network connection to the specified destination.

Format

The format of the message is one M_PROTO message block followed by one or more M_DATA blocks for the NS user data transfer. The specification of the NS user data is optional. The NS user can send any integral number of octets of data within the range supported by the NS provider (see N_INFO_ACK). If the user does not specify QOS parameter values, the default values (specified via N_OPTMGMT_REQ) are used by the NS provider.

The structure of the M_PROTO message block is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_CONN_REQ */
             ulong DEST_length;              /* destination address length */
             ulong DEST_offset;              /* destination address offset */
             ulong CONN_flags;               /* bit masking for options flags */
             ulong QOS_length;               /* QOS parameters' length */
             ulong QOS_offset;               /* QOS parameters' offset */
     } N_conn_req_t;
     
     /* Flags to indicate if options are requested */
     #define REC_CONF_OPT    0x00000001L
     #define EX_DATA_OPT     0x00000002L

Parameters

PRIM_type

Indicates the primitive type.

DEST_length

Indicates the length of the destination address parameter that conveys an address identifying the NS user to which the NC is to be established. This field will accommodate variable length addresses within a range supported by the NS provider.

DEST_offset

Is the offset of the destination address from the beginning of the M_PROTO message block.

QOS_length

Indicates the length of the QOS parameters values that apply to the NC being requested. If the NS user cannot determine the value of a QOS parameter, its value should be set to QOS_UNKNOWN. If the NS user does not specify any QOS parameter values, the length of this field should be set to zero.

QOS_offset

Indicates the offset of the QOS parameters from the beginning of the M_PROTO message block.

Flags

REC_CONF_OPT

The receipt confirmation selection parameter indicates the use/availability of the receipt confirmation service on the NC. The receipt confirmation service must be supported by the NS provider to be used on the NC.

EX_DATA_OPT

Indicates the use of the expedited data transfer service on the NC. The expedited data transfer service must be provided by the NS provider for it to be used on the NC.

Valid States

This primitive is valid in state NS_IDLE.

New State

The new state is NS_WCON_CREQ.

Acknowledgements

The following acknowledgements are valid for this primitive:

• Successful NC Establishment: This is indicated via the N_CONN_CON primitive. This results in the data transfer state.
• Unsuccessful NC Establishment: This is indicated via the N_DISCON_IND primitive. For example, a connection may be rejected because either the called NS user cannot be reached, or the NS provider and/or the called NS user did not agree with the specified QOS. This results in the idle state.
• Non-fatal errors: These are indicated via the N_ERROR_ACK primitive. The applicable non-fatal errors are defined as follows:

  NACCESS

  The user did not have proper permissions for the use of the requested address or options.

  
  

  NBADQOSPARAM

  The QOS parameter values specified are outside the range supported by the NS provider.

  
  

  NBADQOSTYPE

  The QOS structure type is not supported by the NS provider.

  
  

  NBADADDR

  The network address was in an incorrect format or contained illegal information. It is not intended to indicate NC errors, such as an unreachable destination. These errors types are indicated via the N_DISCON_IND primitive.

  
  

  NBADOPT

  The options were in an incorrect format, or they contained illegal information.

  
  

  NOUTSTATE

  The primitive was issued from an invalid state.

  
  

  NBADDATA

  The amount of user data specified was outside the range supported by the NS provider.

  
  

  NSYSERR

  A system error has occurred and the UNIX system error is indicated in the primitive.

4.2.1.2 Network Connection Indication

N_CONN_IND

This primitive indicates to the destination NS user that a network connect request has been made by the user at the specified source address.

Format

The format of this message is one M_PROTO message block followed by one or more M_DATA blocks for NS user data. The specification of NS user data is optional. The NS user can send any integral number of octets of data within the range supported by the NS provider. The NS user data will only be present if the corresponding N_CONN_REQ had NS user data parameter specified, and their data will be identical.

The structure of the M_PROTO message block is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_CONN_IND */
             ulong DEST_length;              /* destination address length */
             ulong DEST_offset;              /* destination address offset */
             ulong SRC_length;               /* source address length */
             ulong SRC_offset;               /* source address offset */
             ulong SEQ_number;               /* sequence number */
             ulong CONN_flags;               /* bit masking for options flags */
             ulong QOS_length;               /* QOS parameters' length */
             ulong QOS_offset;               /* QOS parameters' offset */
     } N_conn_ind_t;
     

Parameters

PRIM_type

Indicates the primitive type.

DEST_length

Indicates the length of the destination address parameter that conveys an address identifying the NS user to which the NC is to be established.

DEST_offset

Is the offset of the destination address from the beginning of theM_PROTO message block.

SRC_length

The source address parameter conveys the network address of the NS user from which the NC has been requested. The semantics of the value in the N_CONN_IND primitive is identical to the value associated with the stream on which the N_CONN_REQ was issued.

SRC_offset

Is the offset of the destination address from the beginning of theM_PROTO message block.

SEQ_number

Identifies the sequence number that can be used by the NS user to associate this message with the N_CONN_RES or N_DISCON_REQ primitive that is to follow. This value must be unique among the outstanding N_CONN_IND messages. The use of this field allows the NS user to issue the N_CONN_RES or the N_DISCON_REQ messages in any order.

QOS_length

Indicates the length of the QOS parameters values that are negotiated during NC establishment. If the destination NS user does not agree to the range of QOS values specified by the source NS user in the N_CONN_REQ primitive, it will reject the NC establishment by invoking a N_DISCON_REQ primitive(the originator parameter in the N_DISCON_REQ primitive will indicate NS user initiated release). If the NS user does not support or cannot determine the value of a QOS parameter, its value will be set to QOS_UNKNOWN. If the NS user does not specify any QOS parameter values, the length of this field should be set to zero.

QOS_offset

Indicates the offset of the QOS parameters from the beginning of the M_PROTO message block.

Flags

REC_CONF_OPT

The receipt confirmation selection parameter indicates the use/availability of the receipt confirmation service on the NC. The receipt confirmation service must be provided in the network service to be used on the NC.

EX_DATA_OPT

The expedited data selection parameter indicates the use/ availability of the expedited data transfer service on the NC. The expedited data transfer service must be provided by the NS provider for it to be used on the NC. Valid States This primitive is valid in the states NS_IDLE and NS_WRES_CIND. New State In both cases the resulting state is NS_WRES_CIND (the number of connect indications waiting for user response is incremented by one).

4.2.1.3 Network Connection Response

N_CONN_RES

This primitive allows the destination NS user to request that the network provider accept a previous connect request.

Format

The format of this message is one M_PROTO message block followed by one or more M_DATA blocks (for NS user data). The specification of the NS user data is optional.

The NS user can send any integral number of octets of data within the range supported by the NS provider.

The structure of the M_PROTO block is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_CONN_RES */
             ulong TOKEN_value;              /* NC response token value */
             ulong RES_length;               /* responding address length */
             ulong RES_offset;               /* responding address offset */
             ulong SEQ_number;               /* sequence number */
             ulong CONN_flags;               /* bit masking for options flags */
             ulong QOS_length;               /* QOS parameters' length */
             ulong QOS_offset;               /* QOS parameters' offset */
     } N_conn_res_t;
     

Parameters

PRIM_type

Indicates the primitive type.

TOKEN_value

Is used to identify the stream that the NS user wants to establish the NC on. (Its value is determined by the NS user by issuing a N_BIND_REQ primitive with the TOKEN_REQUEST flag set.The token value is returned in the N_BIND_ACK). The value of this field should be non-zero when the NS user wants to establish the NC on a stream other than the stream on which the N_CONN_IND arrived. If the NS user wants to establish a NC on the same stream that the N_CONN_IND arrived on, then the value of this field should be zero.

RES_length

Indicates the length of the responding address parameter that conveys the network address of the NS user to which the NC has been established. Under certain circumstances, such as call redirection, generic addressing, etc., the value of this parameter may be different from the destination address parameter specification in the corresponding N_CONN_REQ.

RES_offset

Indicates the offset of the responding address from the beginning of the M_PROTO message block.

SEQ_number

Indicates the sequence number of the N_CONN_RES message.It is used by the NS provider to associate the N_CONN_RES message with an outstanding N_CONN_IND message. An invalid sequence number should result in error with the message type NBADSEQ.

QOS_length

Indicates the length of the QOS parameters values that are negotiated during NC establishment. If the NS user does not agree to the QOS values, it will reject the NC establishment by invoking a N_DISCON_REQ primitive (the originator parameter in the N_DISCON_REQ primitive will indicate NS user invoked release). If the NS user cannot determine the value of a QOS parameter, its value should be set to QOS_UNKNOWN. If the NS user does not specify any QOS parameter values, the length of this field should be set to zero.

QOS_offset

Indicates the offset of the QOS parameters from the beginning of the M_PROTO message block.

Flags

REC_CONF_OPT

The receipt confirmation selection parameter indicates the use/availability of the receipt confirmation service on the NC. The receipt confirmation service must be provided in the network service to be used on the NC.

EX_DATA_OPT

The expedited data selection parameter indicates the use/availability of the expedited data transfer service on the NC. The expedited data transfer service must be provided by the NS provider for it to be used on the NC.

Valid States

This primitive is valid in state NS_WRES_CIND.

New State

The new state is NS_WACK_CRES.

Acknowledgements

The NS provider should generate one of the following acknowledgements upon receipt of this primitive:

• Successful: Successful completion is indicated via the N_OK_ACK primitive.
• Unsuccessful (Non-fatal errors): Errors are indicated via the N_ERROR_ACK primitive. The applicable non-fatal errors are defined as follows:

  NBADOPT

  The options were in an incorrect format, or they contained illegal information.

  
  

  NBADQOSPARAM

  The QOS parameter values specified are outside the range supported by the NS provider.

  
  

  NBADQOSTYPE

  The QOS structure type is not supported by the NS provider.

  
  

  NBADTOKEN

  The token specified is not associated with an open stream.

  
  

  NACCESS

  The user did not have proper permissions for the use of the options of the options or response id.

  
  

  NOUTSTATE

  The primitive was issued from an invalid state.

  
  

  NBADDATA

  The amount of user data specified was outside the range supported by the NS provider.

  
  

  NBADSEQ

  The sequence number specified in the primitive was incorrect or illegal.

  
  

  NSYSERR

  A system error has occurred and the UNIX system error is indicated in the primitive.

4.2.1.4 Network Connection Confirm

N_CONN_CON

This primitive indicates to the source NS user that the network connect request has been confirmed on the specified responding address.

Format

The format of this message is one M_PROTO message block followed by one or more M_DATA blocks (for NS user data). The specification of the NS user data is optional.

The NS user can send any integral number of octets of NS user data within a range supported by the NS provider (see N_INFO_ACK). The NS user data will only be present if the corresponding N_CONN_RES had NS user data specified with it, and their data will always be identical.

The structure of the M_PROTO block is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_CONN_CON */
             ulong RES_length;               /* responding address length */
             ulong RES_offset;               /* responding address offset */
             ulong CONN_flags;               /* bit masking for options flags */
             ulong QOS_length;               /* QOS parameters' length */
             ulong QOS_offset;               /* QOS parameters' offset */
     } N_conn_con_t;
     

Parameters

PRIM_type

Indicates the primitive type.

RES_length

Indicates the length of the responding address parameter that conveys the network address of the NS user entity to which the NC has been established. The semantics of the values in the N_CONN_CON is identical to the values in N_CONN_RES. Under certain circumstances, such as call redirection, generic addressing, etc., the value of this parameter may be different from the destination address parameter specification in the corresponding N_CONN_REQ.

RES_offset

Indicates the offset of the responding address from the beginning of the M_PROTO message block.

QOS_length

Indicates the length of the QOS parameters values selected by the responding NS user. If the NS provider does not support or cannot determine the selected value of a QOS parameter, its value will be set to QOS_UNKNOWN. If the NS provider does not specify any QOS parameter values, the length of this field should be set to zero.

QOS_offset

Indicates the offset of the QOS parameters from the beginning of the M_PROTO message block.

Flags

REC_CONF_OPT

The receipt confirmation selection parameter indicates the use/availability of the receipt confirmation service on the NC. The receipt confirmation service must be provided in the network service to be used on the NC.

EX_DATA_OPT

The expedited data selection parameter indicates the use/ availability of the expedited data transfer service on the NC. The expedited data transfer service must be provided by the NS provider for it to be used on the NC. Valid States This primitive is valid in state NS_WCON_CREQ. New State The new state is NS_DATA_XFER.

4.2.2 Normal Data Transfer Phase

The data transfer service primitives provide for an exchange of NS user data known as NSDUs, in either direction or in both directions simultaneously on a NC. The network service preserves both the sequence and the boundaries of the NSDUs (when the NS provider supports NSDUs).

4.2.2.1 Normal Data Transfer Request

N_DATA_REQ

This user-originated primitive indicates to the NS provider that this message contains NS user data. It allows the transfer of NS_user_data between NS users, without modification by the NS provider. The NS user must send any integral number of octets of data greater than zero. In a case where the size of the NSDU exceeds the NIDU (as specified by the size of the NIDU_size parameter of the N_INFO_ACK primitive), the NSDU may be broken up into more than one NIDU. When an NSDU is broken up into more than one NIDU, the N_MORE_DATA_FLAG will be set on each NIDU except the last one. The RC_flagmay only be set on the last NIDU.

Format

The format of the message is one or more M_DATA blocks. Use of a M_PROTOmessage block is optional. The M_PROTO message block is used for two reasons:

1. to indicate that the NSDU is broken into more than one NIDUs, and that the data carried in the following M_DATA message block constitutes one NIDU;
2. to indicate whether receipt confirmation is desired for the NSDU.

Guidelines for use of M_PROTO:

The following guidelines must be followed with respect to the use of the M_PROTO message block:

1. The M_PROTO message block need not be present when the NSDU size is less than or equal to the NIDU size and one of the following is true:
   • receipt confirmation has been negotiated for non-use (via the N_CONNprimitives); or
   • receipt confirmation has been successfully negotiated for use or non-use and the default selection as specified via the N_OPTMGMT primitive is to be used.
2. The M_PROTO message block must be present when:
   • the NSDU size is greater than the NIDU size;
   • receipt confirmation has been successfully negotiated for use and the default selection as specified via N_OPTMGMT_REQ primitive needs to be overridden.

The structure of the M_PROTO message block, if present, is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_DATA_REQ */
             ulong DATA_xfer_flags;          /* bit masking for data xfer flags */
     } N_data_req_t;
     
     /* Data Transfer Flags */
     #define N_MORE_DATA_FLAG    0x00000001L
     #define N_RC_FLAG           0x00000002L

Parameters

PRIM_type

Indicates the primitive type.

Flags

N_MORE_DATA_FLAG

When set, the MORE_DATA_FLAG indicates that the next N_DATA_REQ message (NIDU) is also part of this NSDU.

N_RC_FLAG

By setting this flag on the N_DATA_REQ, the originating NS user can request confirmation of receipt of the N_DATA primitive. The receipt is provided by the N_DATACK primitives. The parameter may only be present if use of Receipt Confirmation was agreed by both NS users and the NS provider during NC establishment.

Valid States

This primitive is valid in the NS_DATA_XFER state.

New State

The resulting state remains the same (NS_DATA_XFER).

Acknowledgements

This primitive does not require any acknowledgements, although it may generate a fatal error. This is indicated to the NS user via a M_ERROR STREAMS message type (specifying an errno value of EPROTO) which results in the failure of all system calls on that stream. The applicable errors are defined as follows:

EPROTO

This indicates one of the following unrecoverable protocol conditions:

• The network interface was found to be in an incorrect state.
• The amount of NS user data associated with the primitive is outside the range supported by the NS provider (as specified by the NIDU_size parameter ofN_INFO_ACK primitive).
• The options requested are either not supported by the NS provider or its use not specified with the N_CONN_REQ primitive.
• The M_PROTO message block was not followed by one or more M_DATA message blocks.
• The amount of NS user data associated with the current NSDU is outside the range supported by the NS provider (as specified by the NSDU_sizeparameter if the N_INFO_ACK primitive.)
• The N_RC_FLAG and N_MORE_DATA_FLAG were both set in the primitive, or the flags field contained an unknown value.

NOTE: If the interface is in the NS_IDLE or NS_WRES_RIND states when the provider receives the N_DATA_REQ primitive, then the NS provider should discard the request without generating a fatal error.

4.2.2.2 Normal Data Transfer Indication

N_DATA_IND

This network-provider-originated primitive indicates to the NS user that this message contains NS user data. As in the N_DATA_REQ primitive, the NSDU can be segmented into more than one NIDUs. The NIDUs are associated with the NSDU by using theMORE_DATA_FLAG. The RC_FLAG is allowed to be set only on the last NIDU.

Format

The format of the message is one or more M_DATA message blocks. The value of the NS user data field is always the same as that supplied in the corresponding N_DATA_REQ primitive at the peer service access point. Use of M_PROTO message blocks is optional (see guidelines under N_DATA_REQ).

The structure of the M_PROTO message block, if present, is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_DATA_IND */
             ulong DATA_xfer_flags;          /* bit masking for data xfer flags */
     } N_data_ind_t;
     
     /* Data Transfer Flags */
     #define N_MORE_DATA_FLAG    0x00000001L
     #define N_RC_FLAG           0x00000002L

Parameters

PRIM_type

Indicates the primitive type.

Flags

MORE_DATA_FLAG

When set, indicates that the next N_DATA_IND message (NIDU) is part of this NSDU.

RC_FLAG

The value of the parameter may indicate either that confirmation is requested or that it is not requested. The parameter is allowed to be set only if use of Receipt Confirmation was agreed to between both the NS users and the NS provider during NC establishment. The value of this parameter is always identical to that supplied in the corresponding N_DATA_REQ primitive.

Valid States

This primitive is valid in state NS_DATA_XFER.

New State

The resulting state remains the same (NS_DATA_XFER).

4.2.3 Receipt Confirmation Service Primitives

The receipt confirmation service is requested by the confirmation request parameter on the N_DATA_REQ primitive. For each and every NSDU with the confirmation request parameter set, the receiving NS user should return an N_DATACK_REQ primitive.Such acknowledgements should be issued in the same sequence as the corresponding N_DATA_IND primitives are received, and are to be conveyed by the NS provider in such a way so as to preserve them distinct from any previous or subsequent acknowledgements. The NS user may thus correlate them with the original requests by counting. When an NSDU has been segmented into more than one NIDUs, only the last NIDU is allowed to request receipt confirmation. N_DATACK_REQ primitives will not be subject to the flow control affectingN_DATA_REQ primitives at the same NC endpoint. N_DATACK_IND primitives will not be subject to the flow control affecting N_DATA_IND primitives at the same NC endpoint.

The use of the receipt confirmation service must be agreed to by the two NS users of the NC and the NS provider during the NC establishment by using the RC_selection parameter on the N_CONN primitives.

4.2.3.1 Data Acknowledgement Request

N_DATACK_REQ

This is a user-originated primitive that requests that the network provider acknowledge the N_DATA_IND that had previously been received with the receipt confirmation parameter set.

Format

The format of the message is one M_PROTO message block and its structure is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_DATACK_REQ */
     } N_datack_req_t;
     

Parameters

PRIM_type

Indicates the primitive type.

Valid States

This primitive is valid in state NS_DATA_XFER.

New State

The resulting state remains the same (NS_DATA_XFER).

Acknowledgements

This primitive does not require any acknowledgements, although it may generate a fatal (unrecoverable) error. This is indicated via an M_ERROR STREAMS message type (issued to the NS user specifying the errno value of EPROTO), which results in the failure of all system calls on that stream. The allowable errors are as follows:

EPROTO

This indicates the following unrecoverable protocol condition:

• The network interface was found to be in an incorrect state.

NOTE: If the interface is in the NS_IDLE state when the provider receives the N_DATACK_REQ primitive, then the NS provider should discard the request without generating a fatal error. If the NS provider had no knowledge of a previous N_DATA_IND with the receipt confirmation flag set, then the NS provider should just ignore the request without generating a fatal error.

4.2.3.2 Data Acknowledgement Indication

N_DATACK_IND

This is a NS provider originated primitive that indicates to the network service user that the remote network service user has acknowledged the data that had previously been sent with the receipt confirmation set.

Format

The format of the message is one M_PROTO message block and its structure is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_DATACK_IND */
     } N_datack_ind_t;
     

Parameters

PRIM_type

Indicates the primitive type.

Valid States

This primitive is valid in state NS_DATA_XFER.

New State

The resulting state remains the same (NS_DATA_XFER).

4.2.4 Expedited Data Transfer Service

The expedited data transfer service provides a further means of information exchange on an NC in both directions simultaneously. The transfer of expedited network service data unit (ENSDU) is subject to separate flow control from that applying to NS user data (However, a separate STREAMS message type for expedited data is not available with UNIX® System V Release 3.1. Until a new STREAMS message type is provided, expedited data will be implemented via queue manipulation). The NS provider should guarantee that an expedited-NSDU will not be delivered after any subsequently issued NSDU or expedited-NSDU on that NC. The relationship between normal and expedited data is shown in Table 2. Expedited data can still be delivered when the receiving NS user is not accepting normal data (however this cannot be guaranteed if there are blockages occurring in the lower layers). The expedited data transfer service is a NS provider option, and its use must be agreed by the two NS users of the NC and the NS provider during NC establishment by using the EX_DATA_OPT parameter on the N_CONN primitives.

4.2.4.1 Expedited Data Transfer Request

N_EXDATA_REQ

This is a NS user originated primitive and is used to indicate to the network provider that the message block contains an ENSDU.

Format

The format of the message is one M_PROTO message block, followed by one or more M_DATA blocks. The NS user must send an integral number of octets of data within the range supported by the NS provider (see N_INFO_ACK).

The structure of the M_PROTO message block is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_EXDATA_REQ */
     } N_exdata_req_t;
     

Parameters

PRIM_type

Indicates the primitive type.

Valid States

This primitive is valid in state NS_DATA_XFER.

New State

The resulting state remains the same (NS_DATA_XFER).

Acknowledgements

This primitive does not require any acknowledgements, although it may generate a fatal (unrecoverable) error. This is indicated via an M_ERROR STREAMS message type (issued to the NS user with the errno value of EPROTO), which results in the failure of all system calls on that stream. The applicable errors are as follows:

EPROTO

This indicates one of the following unrecoverable protocol conditions:

• The network interface was found to be in an incorrect state.
• The amount of NS user data associated with the primitive defines an expedited network service data unit of a size that is outside the range supported by the NS provider.
• Expedited data transfer is either not supported by the NS provider or not requested with the N_CONN_REQ primitive.

NOTE: If the interface is in the NS_IDLE or NS_WRES_RIND states when the provider receives the N_EXDATA_REQ primitive, then the NS provider should discard the request without generating a fatal error.

4.2.4.2 Expedited Data Transfer Indication

N_EXDATA_IND

This is a NS provider originated primitive and is used to indicate to the NS user that this message contains an ENSDU.

Format

The format of the message is one M_PROTO message block, followed by one or more M_DATA blocks. The value of the data in the M_DATA blocks is identical to that supplied with the corresponding N_EXDATA_REQ primitive.

The structure of the M_PROTO message block is as follows:

     typedef struct {
             ulong PRIM_type;                /* always N_EXDATA_IND */
     } N_exdata_ind_t;
     

Parameters

PRIM_type

Indicates the primitive type.