 |
» |
|
|
|
This section discusses the SCTP-specific socket APIs. Following are the SCTP-specific socket APIs: The sctp_getpaddrs()() API The sctp_freepaddrs()() API The sctp_getladdrs()() API The sctp_freeladdrs()() API The sctp_connectx()() API
The following subsections discuss these APIs in detail. The sctp_bindx() SCTP Socket API | |
Applications can use the sctp_bindx()() API
to associate with multiple addresses. Following is the syntax for
the sctp_bindx()() socket API: int sctp_bindx(int sd, struct sockaddr *addrs, int addrcnt,
int flags);
|
where: - sd
Specifies the socket descriptor. If sd is an IPv4 socket, the addresses passed must be IPv4 addresses.
If the sd is an IPv6 socket, the addresses passed
can either be an IPv4 or an IPv6 addresses. - addrs
Specifies a pointer to an array of one or more socket
addresses. Each address is specified in its appropriate structure.
For an IPv6 socket, sctp_bindx()() returns an array
of type sockaddr_in6. For an IPv4 socket, sctp_bindx()() returns an array of type sockaddr_in. - addrcnt
Specifies the number of addresses in the array (sockaddr_in6 or sockaddr_in). You cannot use wildcard addresses with sctp_bindx()(). - flags
Contains flags affecting the message that is being
sent. The flags parameter is formed from the bitwise OR of zero or more of the following flags: SCTP_BINDX_ADD_ADDR directs SCTP to add the
given addresses to the association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given addresses from the association.
These flags are mutually exclusive.
On success, sctp_bindx()() returns 0. On
failure, sctp_bindx()() returns -1, and sets errno to the appropriate error code. The sctp_peeloff() SCTP Socket API | |
Applications can use the sctp_peeloff()() socket API to branch off an association into a separate socket. This
API is a one-to-one style socket API. Following is the syntax for the sctp_peeloff()() socket API: sctp_peeloff(int sd, sctp_assoc_t assoc_id) |
where: - sd
Specifies the socket descriptor representing the branched-off association. - assoc_id
Specifies the identifier of the association that must
be branched off to a separate file descriptor.
The sctp_getpaddrs() SCTP Socket API | |
Applications can use the sctp_getpaddrs()() socket API to return all peer addresses in an association. Following is the syntax for the sctp_getpaddrs()() socket API: int sctp_getpaddrs(int sd, sctp_assoc_t id,
struct sockaddr **addrs);
|
where: - sd
Specifies the socket descriptor. If sd is an IPv4 socket, the addresses returned will be IPv4 addresses.
If sd is an IPv6 socket, the addresses returned
can be either an IPv4 or an IPv6 addresses. - id
Specifies the association ID. For one-to-many style
sockets, ID specifies the association to query. An application ignores id for one-to-one style sockets. - addrs
Points to the dynamically allocated array of sockaddr structures of the appropriate socket type.
An application must use the sctp_freepaddrs()() call to free the memory.
On success, sctp_getpaddrs()() returns the
number of peer addresses in the association. The sctp_getpaddrs()() API can fail for the following reasons: If an association does not exist on a socket, sctp_getpaddrs()() returns 0. The value of *addrs is undefined. If an error occurs, sctp_getpaddrs()() returns -1 and the value of *addrs is left undefined.
The sctp_freepaddrs() SCTP Socket API | |
Applications must use the sctp_freepaddrs()() socket API to free all resources allocated by the sctp_getpaddrs()() API. Following is the syntax for the sctp_freepaddrs()() socket API: void sctp_freepaddrs(struct sockaddr *addrs); |
where: - addrs
Specifies the array of peer addresses returned by sctp_getpaddrs()().
The sctp_getladdrs() SCTP Socket API | |
Applications can use the sctp_getladdrs()() SCTP socket API to return all the locally bound addresses on a socket. Following is the syntax for the sctp_getladdrs()() SCTP socket API: int sctp_getladdrs(int sd, sctp_assoc_t id, struct sockaddr **ss); |
where: - sd
Specifies the socket descriptor. If sd is an IPv4 socket, the addresses returned will be an IPv4 addresses.
If sd is an IPv6 socket, the addresses returned
can be either an IPv4 or IPv6 address. - id
Specifies the association ID. For one-to-many style
sockets, id specifies the association to query.
An application ignores id for one-to-one style
sockets. If id is set to 0 (zero), the locally
bound addresses are returned irrespective of the particular association. - ss
Points to a dynamically allocated array of sockaddr structures of the appropriate socket type.
An application must use sctp_freeaddrs()() to free the memory that is allocated by sctp_getladdrs()(), to store addresses. On success, sctp_getladdrs()() returns the
number of local addresses bound to the socket. If the socket is unbound, sctp_getladdrs()() returns 0, and the value of *addrs is left undefined. If an error occurs, sctp_getladdrs()() returns -1, and the value of *addrs is left undefined. The sctp_freeladdrs() SCTP Socket API | |
Applications use the sctp_freeladdrs()() API
to free
all resources allocated by the sctp_getladdrs()() socket API. Following is the syntax for the sctp_freeladdrs()() API: void sctp_freeladdrs(struct sockaddr *addrs); |
where: - addrs
Specifies the array of peer addresses returned by
the sctp_getladdrs()() socket API.
The sctp_sendmsg() SCTP Socket API | |
Applications can use sctp_sendmsg()() to
send an SCTP message. This API is similar to the sendmsg()() call, with the SCTP_SNDRCV option. Following is the syntax for the sctp_sendmsg()() SCTP socket API: ssize_t sctp_sendmsg(int sd,
const void *msg,
size_t len,
const struct sockaddr *to,
socklen_t tolen,
uint32_t ppid,
uint32_t flags,
uint16_t stream_no,
uint32_t timetolive,
uint32_t context)
|
where: - sd
Specifies the socket descriptor. - msg
Specifies the message to be sent. - len
Specifies the length of the message. - to
Specifies the destination address of the message. - tolen
Specifies the length of the destination address. - ppid
Specifies the payload protocol identifier, which is
entered in the payload protocol identifier field of the SCTP data
header. - flags
Contains flags affecting the message being sent. - stream_no
Contains the stream number of the message. - timetolive
Specifies the TTL value for a message in milliseconds. - context
Specifies a 32-bit unsigned integer that is used by sendmsg()(). When an application fails to send the data
and an SCTP_SEND_FAILED notification is sent to
the upper layer in the peer application, an application returns context as part of the information.
The sctp_recvmsg() SCTP Socket API | |
Applications can use the sctp_recvmsg()() SCTP socket API to receive messages. This API is similar to the recvmsg()() API, with the SCTP_SNDRCV option.
For the sctp_sndrcvinfo structure to be populated
by sctp_recvmsg()(), an application must enable
the sctp_data_io_events with the SCTP_EVENTS option. Following is the syntax for the sctp_recvmsg()() socket API: ssize_t sctp_recvmsg(int sd,
void *msg,
size_t len,
struct sockaddr *from,
socklen_t *fromlen
struct sctp_sndrcvinfo *sinfo
int *msg_flags)
|
where: - sd
Specifies the socket descriptor. - msg
Specifies a message buffer. - len
Specifies the length of the message buffer. - from
Specifies the sender of a message. - fromlen
Specifies the length of the address. - sinfo
Denotes a pointer to an sctp_sndrcvinfo structure that is filled after the message is received. - msg_flags
Denotes a pointer to an integer to be filled with
a message flag.
The sctp_connectx() SCTP Socket API | |
Applications can use the sctp_connectx()() SCTP socket API to associate to an endpoint that is multihomed.
This API enables an application to specify multiple addresses
on which a peer can be reached. This API only specifies that the SCTP
will try to make use of all the addresses in the list when required. Following is the syntax for the sctp_connectx()() SCTP socket API: int sctp_connectx(int sd,
struct sockaddr *addrs,
int addrcnt)
|
where: - sd
Specifies the socket descriptor. - addrs
Specifies an array of addresses. - addrcnt
Specifies the number of addresses in the array.
The list of addresses passed to sctp_connectx()() is used only for setting up the association and does not specify
the set of addresses the peer uses for the resulting association.
If applications want to find out the set of peer addresses, applications
must use the sctp_getpaddrs()() to retrieve them
after the association is set up. The sctp_send() SCTP Socket API | |
Applications can use the sctp_send()() SCTP
socket API to send data without using the cmsg header structures. This API is similar to the sendmsg()() API, with the SCTP_SNDRCV option. Following is the syntax for the sctp_send()() SCTP socket API: int sctp_send(int sd,
const void *msg,
size_t len,
const struct sctp_sndrcvinfo *sinfo,
int flags);
|
where: - sd
Specifies the socket descriptor. - msg
Specifies the message to be sent. - len
Specifies the length of the message. - sinfo
Specifies a pointer to a sctp_sndrcvinfo structure that is used for a sendmsg()() call. - flags
Contains flags similar to the flags passed to the sendmsg()() call.
Applications can also use this API to terminate an association
using an association ID, by setting the sinfo.sinfo_flags to MSG_EOF, and the sinfo.sinf_associd to
the association that must be terminated. In this case, the length
of the message is 0 (zero). The sctp_sendx() SCTP Socket API | |
Applications can use the sctp_sendx()() SCTP
socket API to send data, without using the cmsg header structures that provide a list of addresses. Following is the syntax for the sctp_sendx()() SCTP socket API: int sctp_sendx(int sd,
const void *msg,
size_t len,
struct sockaddr *addrs,
int addrcnt,
struct sctp_sndrcvinfo *sinfo,
int flags);
|
where: - sd
Specifies the socket descriptor. - msg
Specifies the message to be sent. - len
Specifies the length of the message. - addrs
Specifies an array of addresses. - addrcnt
Specifies the number of addresses in the array. - sinfo
Specifies a pointer to an sctp_sndrcvinfo structure used for a sendmsg()() call. - flags
Contains flags in the same format as the sendmsg()() call flags (for example, MSG_DONTROUTE)
This API can also be used to terminate an association using
an association ID, by setting the sinfo.sinfo_flags to MSG_EOF, and the sinfo.sinf_associd to the association that must be terminated. In such a case, the
length of the message is 0 (zero). |
Printable version
