The native API is the main interface between DCCP applications and the DCCP-TP stack. Ports of DCCP-TP may choose to make the native API directly available to applications, but more likely they'll need to wrap the native API in something more suitable to the operating environment (see the Lprocess API
page for an example of this).
The native API is implemented in core/dccp/dccpRawApi.[ch]. The flow of the native API is similar to the Posix sockets interface, although various parameters differ. All of the routines take a parameter called 'cerrno', which is a pointer to an 'int'. If the calls fail, and 'cerrno' is not NULL, '*cerrno' is set to an extended error value that mimics the standard Posix 'errno' values. The API funtions are:
- dctpSocket *dctpaSocket(int encap, uint32_t scode, int *cerrno) — Creates a socket. 'encap' must be one of DCTPENCAP_RAW (for IPv4 Raw), DCTPENCAP_NAT (for IPv4 NAT), DCTPENCAP_RAW6 (for IPv6 Raw) or DCTPENCAP_NAT6 (for IPv6 NAT). In r0.00, only DCTPENCAP_NAT is supported. 'scode' is the service code to associate with the socket (in network byte order). 'scode' must not be 0xffffffff. Returns a pointer to the socket on success or NULL if an error is encountered.
- int dctpaBind(dctpSocket *sock, dctpSockaddr *addr, int *cerrno) — Called to attach the address '*addr' to the socket, usually in preparation for putting the socket in LISTEN state. 'addr' is a dctpSockaddr structure that supports addresses in either IPv4 of IPv6 format. The format of the address must be consistent with the 'encap' value that was used to create the socket. Returns 0 on success or -1 on error.
- int dctpaListen(dctpSocket *sock, uint_t backlog, int *cerrno) — Called to start listening for incoming connection requests. dctpaBind must have been called beforehand. 'backlog' is the maximum number of pending connections to enqueue. Returns 0 on success and -1 on error.
- dctpSocket *dctpaAccept(dctpSocket *sock, dctpSockaddr *addr, int alen, int *cerrno) — Called to accept incoming connection request. 'sock' must be in the LISTEN state (previous call to dctpaListen). On success, '*addr' is set to the address of the remote peer. 'alen' is the expected length of that address. If no accpetable connections are immediately available, the function blocks the calling thread until one is available. Returns a pointer to a new (cloned) socket on success and NULL on failure.
- int dctpaConnect(dctpSocket *sock, dctpSockaddr *addr, dctpPacket *data, int *cerrno) — Called to send a connection request for a socket. 'addr' points to the remote address (IP and port). 'data' points to a packet with user data to include in the request (no user data sent if 'data' is NULL). The function blocks until the connection response is received (or fails). Returns 0 on success or -1 on failure.
- int dctpaSend(dctpSocket *sock, dctpPacket *data, int *cerrno) — Called to send user data on the connection. The socket must be connected (successful return from either dctpaConnect or dctpaAccept). The packet is sent immediately, if possible, or enqueued for later transmission. If the socket send queue is full, the function blocks until room is available. Returns the length of the packet data sent for success and -1 for error.
- int dctpaRecv(dctpSocket *sock, dctpPacket **data, int *cerrno) — Called to receive user data on a connection. The socket must be connected (successful return from either dctpaConnect or dctpaAccept). If receive data is available, the function returns immediately. Otherwise it blocks the calling thread until data is available (or an error occurs). On success, '*data' is set to a pointer to the received packet and the (positive) length of the data in the packet is returned. -1 is returned for failure.
- int dctpaClose(dctpSocket *sock, int *cerrno) — Called to terminate the use of a socket. If the socket is currently in connected state, the close procedure will be initiated. The socket will not be immediately destroyed but is unavailable for application use and will be eventually destroyed. If the socket is not connected, it will be immediately destroyed. Returns 0 on success and -1 on failure.
- int dctpaSetSockopt(dctpSocket *sock, int opt, int mandatory, void *opval, uint_t oplen, int *cerrno) — Set a socket option. 'opt' is the option number. 'mandatory' is non-zero to precede the option number with the mandatory option. 'optval' is a pointer to the option data. 'oplen' is the length of that data.
Created by: trphelan
last modification: Thursday 29 of May, 2008 [19:49:31 UTC] by trphelan