SCTP Ancillary Data Structures

The SCTP socket APIs can use the ancillary data structures to enable applications to control an association. These structures also enable SCTP to notify applications about association events.

The ancillary data mechanism uses the definition of struct msghdr, which is available to an SCTP application when it uses the X/Open socket.




	NOTE: An application that uses BSD43 socket cannot use the features related to ancillary data.

SCTP processes each ancillary data using the cmsghdr structure, which defines the function and purpose of the data. Following is the structure for the cmsghdr structure:

struct cmsghdr {
     socklen_t  cmsg_len;
     int        cmsg_level;
     int        cmsg_type;
     };

Where:

cms_len: Specifies the number of bytes, including the header.
cmsg_level: Specifies the originating protocol.
cmsg_type: Specifies the type of the protocol followed by an unsigned character, cmsg_data.

For the structure definition of the msghdr structure, see “The sendmsg() and recvmsg() Socket APIs”.

An SCTP application can use ancillary data structures to communicate certain aspects of an association, such as:

Treating a user date if it cannot be sent in a certain time
Specifying the number of inbound streams to be advertised during association setup

SCTP provides the following ancillary data structures:

SCTP Initiation Structure
SCTP Header Information

The following sections discuss these ancillary data structures in detail.

SCTP Initiation Structure (SCTP_INIT)

When an application calls sendmsg()() using a one-to-many style socket API, it uses an SCTP initiation structure to set the protocol parameters for a new association. The SCTP initiation structure is represented by the sctp_initmsg ancillary data structure. The name of the ancillary data type is SCTP_INIT, and the data type is defined at the IPPROTO_SCTP level.

Following is the data structure for the sctp_initmsg structure:

struct sctp_initmsg {
 uint16_t sinit_num_ostreams;
 uint16_t sinit_max_instreams;
 uint16_t sinit_max_attempts;
 uint16_t sinit_max_init_timeo;
};

where:

sinit_num_ostreams: Represents the number of outbound streams.
sinit_num_ostreams: Represents the number of inbound streams to be supported.
sinit_max_instreams: Represents the maximum number of times INIT must be transmitted before giving up an association setup.
sinit_max_init_timeo: Represents the largest time out value to use in attempting a INIT.

The values provided by an application are for a association and overrides the default values.

SCTP Header Information (SCTP_SNDRCV)

An application uses the SCTP header information to describe the SCTP header information of a message that is received through the recvmsg()() call, and to specify the SCTP options for the sendmsg()() call. The SCTP header information is represented by the sctp_sndrcvinfo ancillary data structure. The name of the ancillary data type is SCTP_SNDRCV, and the data type is defined at the IPPROTO_SCTP level.

Following is the data structure for the sctp_sndrcvinfo structure:

struct sctp_sndrcvinfo {
 uint16_t sinfo_stream;
 uint16_t sinfo_ssn;
 uint16_t sinfo_flags;
 uint32_t sinfo_ppid;
 uint32_t sinfo_context;
 uint32_t sinfo_timetolive;
 uint32_t sinfo_tsn;
 uint32_t sinfo_cumtsn;
 sctp_assoc_t sinfo_assoc_id;
 };

The msghdr structure in the recvmsg()() and sendmsg()() APIs uses the sctp_sndrcvinfo structure to set and get various control information from the SCTP endpoint.

Table 2-1 lists the elements in the sctp_sndrcvinfo structure for the recvmsg()() and sendmsg()() calls.

Table 2-1 Data Structures in the recvmsg()() and sendmsg()() Calls

Variable	recvmsg()	sendmsg()
`sinfo_stream`	Specifies the stream number of the message.	Specifies the stream number to which the application wants to send the message.
`sinfo_ssn`	Contains the stream sequence number in the `DATA` chunk.	Not applicable
`sinfo_ppid`	Specifies the information that is passed by the upper layer in the peer application.	Specifies an opaque unsigned value that is passed to the remote endpoint in each user message.
`sinfo_context`	Not applicable	Specifies an opaque context data that is passed back to the application while reporting an error on the concerned `sendmsg()`() call.
`sinfo_flags`	Specifies the flag (`MSG_UNORDRED`) to inform the application that the message received was unordered. The `recvmsg()`() API contains only one flag (`MSG_UNORDRED`), whereas the `sendmsg()`() API contains multiple flags.	Specifies the flag that controls the send behavior of the data chunk, or the association itself. For example, `sendmsg()`() contains the `MSG_UNORDRED` flag to indicate unordered send of data, and `MSG_EOF` to close a given association.
`sinfo_timetolive`	Not applicable	Specifies the time-to-live (TTL ) for a given message. If an application does not send a message within the specified TTL value, the message expires and a notification is sent to the application, if notification is enabled.
`sinfo_tsn`	Specifies the transmission sequence number (TSN) assigned to one of the SCTP data chunks.	Not applicable
`sinfo_cumtsn`	Specifies the cumulative TSN, while presenting an unordered message (if the `MSG_UNORDRED` flag is set)	Not applicable
`sinfo_assoc_id`	Specifies the association ID.	Specifies the association ID.

SCTP Ancillary Data Structures

Technical documentation

» Table of Contents

» Glossary

» Index

SCTP Initiation Structure (SCTP_INIT)

SCTP Header Information (SCTP_SNDRCV)