mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
Add documentation for destiny/socket.h
This commit is contained in:
Martin Lenders
parent
3149e83826
commit
75064eb630
@ -11,6 +11,9 @@
|
||||
* @{
|
||||
* @file
|
||||
* @brief Header for BSD socket API
|
||||
* @see <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_socket.h.html">
|
||||
* IEEE Std 1003.1, 2013 Edition - sys/socket.h
|
||||
* </a>
|
||||
* @author Oliver Gesch <oliver.gesch@googlemail.com>
|
||||
* @author Martin Lenders <mlenders@inf.fu-berlin.de>
|
||||
*/
|
||||
@ -23,119 +26,182 @@
|
||||
#include "ipv6.h"
|
||||
#include "destiny/in.h"
|
||||
|
||||
typedef uint8_t sa_family_t; ///< POSIX compatible type for address family.
|
||||
typedef uint32_t socklen_t; ///< POSIX compatible type for address length.
|
||||
|
||||
|
||||
#define SOCK_STREAM 1 ///< POSIX compatible stream socket type.
|
||||
#define SOCK_DGRAM 2 ///< POSIX compatible datagram socket type.
|
||||
#define SOCK_RAW 3 ///< POSIX compatible raw-protocol interface type.
|
||||
#define SOCK_RDM 4 ///< POSIX compatible reliably-delivered message type.
|
||||
#define SOCK_SEQPACKET 5 ///< POSIX compatible sequenced packet stream type.
|
||||
|
||||
#define AF_UNSPEC 0 ///< unspecified address family.
|
||||
#define AF_LOCAL 1 ///< local to host (pipes, portals) address family.
|
||||
#define AF_UNIX AF_LOCAL ///< alias for AF_LOCAL for backward compatibility.
|
||||
#define AF_INET 2 ///< internetwork address family: UDP, TCP, etc.
|
||||
#define AF_IMPLINK 3 ///< ARPAnet IMP address family.
|
||||
#define AF_PUP 4 ///< PUP protocols address family: e.g. BSP
|
||||
#define AF_CHAOS 5 ///< MIT CHAOS protocols address family
|
||||
#define AF_NS 6 ///< XEROX NS protocols address family
|
||||
#define AF_ISO 7 ///< ISO protocols address family
|
||||
#define AF_OSI AF_ISO ///< alias for AF_ISO
|
||||
#define AF_ECMA 8 ///< European computer manufacturers address family
|
||||
#define AF_DATAKIT 9 ///< datakit protocols address family
|
||||
#define AF_CCITT 10 ///< CCITT protocols address family, X.25 etc
|
||||
#define AF_SNA 11 ///< IBM SNA address family
|
||||
#define AF_DECnet 12 ///< DECnet address family
|
||||
#define AF_DLI 13 ///< DEC Direct data link interface address family
|
||||
#define AF_LAT 14 ///< LAT address family
|
||||
#define AF_HYLINK 15 ///< NSC Hyperchannel address family
|
||||
#define AF_APPLETALK 16 ///< Apple Talk address family
|
||||
#define AF_ROUTE 17 ///< Internal Routing Protocol address family
|
||||
#define AF_LINK 18 ///< Link layer interface address family
|
||||
#define pseudo_AF_XTP 19 ///< eXpress Transfer Protocol (no AF)
|
||||
#define AF_COIP 20 ///< connection-oriented IP, aka ST II address family.
|
||||
#define AF_CNT 21 ///< Computer Network Technology address family
|
||||
#define pseudo_AF_RTIP 22 ///< Help Identify RTIP packets address family
|
||||
#define AF_IPX 23 ///< Novell Internet Protocol (no AF)
|
||||
#define AF_SIP 24 ///< Simple Internet Protocol address family
|
||||
#define pseudo_AF_PIP 25 ///< Help Identify PIP packets (no AF)
|
||||
#define AF_ISDN 26 ///< Integrated Services Digital Network address family
|
||||
#define AF_E164 AF_ISDN ///< CCITT E.164 recommendation
|
||||
#define pseudo_AF_KEY 27 ///< Internal key-management function (no AF)
|
||||
/**
|
||||
* POSIX compatible type for address family.
|
||||
* IPv6 address family.
|
||||
*
|
||||
* @see <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_socket.h.html">
|
||||
* IEEE Std 1003.1, 2013 Edition - sys/socket.h
|
||||
* </a>
|
||||
* @see AF_INET
|
||||
*/
|
||||
typedef uint8_t sa_family_t;
|
||||
typedef uint32_t socklen_t; ///< POSIX compatible type for address lengths.
|
||||
|
||||
/*
|
||||
* Types
|
||||
*/
|
||||
#define SOCK_STREAM 1 /* stream socket */
|
||||
#define SOCK_DGRAM 2 /* datagram socket */
|
||||
#define SOCK_RAW 3 /* raw-protocol interface */
|
||||
#define SOCK_RDM 4 /* reliably-delivered message */
|
||||
#define SOCK_SEQPACKET 5 /* sequenced packet stream */
|
||||
|
||||
/*
|
||||
* Address families.
|
||||
*/
|
||||
#define AF_UNSPEC 0 /* unspecified */
|
||||
#define AF_LOCAL 1 /* local to host (pipes, portals) */
|
||||
#define AF_UNIX AF_LOCAL /* backward compatibility */
|
||||
#define AF_INET 2 /* internetwork: UDP, TCP, etc. */
|
||||
#define AF_IMPLINK 3 /* arpanet imp addresses */
|
||||
#define AF_PUP 4 /* pup protocols: e.g. BSP */
|
||||
#define AF_CHAOS 5 /* mit CHAOS protocols */
|
||||
#define AF_NS 6 /* XEROX NS protocols */
|
||||
#define AF_ISO 7 /* ISO protocols */
|
||||
#define AF_OSI AF_ISO
|
||||
#define AF_ECMA 8 /* European computer manufacturers */
|
||||
#define AF_DATAKIT 9 /* datakit protocols */
|
||||
#define AF_CCITT 10 /* CCITT protocols, X.25 etc */
|
||||
#define AF_SNA 11 /* IBM SNA */
|
||||
#define AF_DECnet 12 /* DECnet */
|
||||
#define AF_DLI 13 /* DEC Direct data link interface */
|
||||
#define AF_LAT 14 /* LAT */
|
||||
#define AF_HYLINK 15 /* NSC Hyperchannel */
|
||||
#define AF_APPLETALK 16 /* Apple Talk */
|
||||
#define AF_ROUTE 17 /* Internal Routing Protocol */
|
||||
#define AF_LINK 18 /* Link layer interface */
|
||||
#define pseudo_AF_XTP 19 /* eXpress Transfer Protocol (no AF) */
|
||||
#define AF_COIP 20 /* connection-oriented IP, aka ST II */
|
||||
#define AF_CNT 21 /* Computer Network Technology */
|
||||
#define pseudo_AF_RTIP 22 /* Help Identify RTIP packets */
|
||||
#define AF_IPX 23 /* Novell Internet Protocol */
|
||||
#define AF_SIP 24 /* Simple Internet Protocol */
|
||||
#define pseudo_AF_PIP 25 /* Help Identify PIP packets */
|
||||
#define AF_ISDN 26 /* Integrated Services Digital Network*/
|
||||
#define AF_E164 AF_ISDN /* CCITT E.164 recommendation */
|
||||
#define pseudo_AF_KEY 27 /* Internal key-management function */
|
||||
#define AF_INET6 28 /* IPv6 */
|
||||
#define AF_NATM 29 /* native ATM access */
|
||||
#define AF_ATM 30 /* ATM */
|
||||
#define pseudo_AF_HDRCMPLT 31 /* Used by BPF to not rewrite headers
|
||||
* in interface output routine
|
||||
*/
|
||||
#define AF_NETGRAPH 32 /* Netgraph sockets */
|
||||
#define AF_MAX 33
|
||||
#define AF_INET6 28
|
||||
#define AF_NATM 29 ///< native ATM access address family
|
||||
#define AF_ATM 30 ///< ATM address family
|
||||
#define pseudo_AF_HDRCMPLT 31 ///< Used by BPF to not rewrite headers in interface output routine
|
||||
#define AF_NETGRAPH 32 ///< Netgraph sockets address family
|
||||
#define AF_MAX 33 ///< Maximum for address families
|
||||
|
||||
/*
|
||||
* Protocol families, same as address families for now.
|
||||
*/
|
||||
#define PF_UNSPEC AF_UNSPEC
|
||||
#define PF_LOCAL AF_LOCAL
|
||||
#define PF_UNIX PF_LOCAL /* backward compatibility */
|
||||
#define PF_INET AF_INET
|
||||
#define PF_IMPLINK AF_IMPLINK
|
||||
#define PF_PUP AF_PUP
|
||||
#define PF_CHAOS AF_CHAOS
|
||||
#define PF_NS AF_NS
|
||||
#define PF_ISO AF_ISO
|
||||
#define PF_OSI AF_ISO
|
||||
#define PF_ECMA AF_ECMA
|
||||
#define PF_DATAKIT AF_DATAKIT
|
||||
#define PF_CCITT AF_CCITT
|
||||
#define PF_SNA AF_SNA
|
||||
#define PF_DECnet AF_DECnet
|
||||
#define PF_DLI AF_DLI
|
||||
#define PF_LAT AF_LAT
|
||||
#define PF_HYLINK AF_HYLINK
|
||||
#define PF_APPLETALK AF_APPLETALK
|
||||
#define PF_ROUTE AF_ROUTE
|
||||
#define PF_LINK AF_LINK
|
||||
#define PF_XTP pseudo_AF_XTP /* really just proto family, no AF */
|
||||
#define PF_COIP AF_COIP
|
||||
#define PF_CNT AF_CNT
|
||||
#define PF_SIP AF_SIP
|
||||
#define PF_IPX AF_IPX /* same format as AF_NS */
|
||||
#define PF_RTIP pseudo_AF_RTIP /* same format as AF_INET */
|
||||
#define PF_PIP pseudo_AF_PIP
|
||||
#define PF_ISDN AF_ISDN
|
||||
#define PF_KEY pseudo_AF_KEY
|
||||
#define PF_INET6 AF_INET6
|
||||
#define PF_NATM AF_NATM
|
||||
#define PF_ATM AF_ATM
|
||||
#define PF_NETGRAPH AF_NETGRAPH
|
||||
#define PF_MAX AF_MAX
|
||||
#define PF_UNSPEC AF_UNSPEC ///< protocol family
|
||||
///< @see AF_UNSPEC
|
||||
#define PF_LOCAL AF_LOCAL ///< protocol family
|
||||
///< @see AF_LOCAL
|
||||
#define PF_UNIX PF_LOCAL ///< alias for PF_LOCAL for backward compatibility
|
||||
#define PF_INET AF_INET ///< protocol family
|
||||
///< @see AF_INET
|
||||
#define PF_IMPLINK AF_IMPLINK ///< protocol family
|
||||
///< @see AF_IMPLINK
|
||||
#define PF_PUP AF_PUP ///< protocol family
|
||||
///< @see AF_PUP
|
||||
#define PF_CHAOS AF_CHAOS ///< protocol family
|
||||
///< @see AF_CHAOS
|
||||
#define PF_NS AF_NS ///< protocol family
|
||||
///< @see AF_NS
|
||||
#define PF_ISO AF_ISO ///< protocol family
|
||||
///< @see AF_ISO
|
||||
#define PF_OSI AF_OSI ///< protocol family
|
||||
///< @see AF_OSI
|
||||
#define PF_ECMA AF_ECMA ///< protocol family
|
||||
///< @see AF_ECMA
|
||||
#define PF_DATAKIT AF_DATAKIT ///< protocol family
|
||||
///< @see AF_DATAKIT
|
||||
#define PF_CCITT AF_CCITT ///< protocol family
|
||||
///< @see AF_CCITT
|
||||
#define PF_SNA AF_SNA ///< protocol family
|
||||
///< @see AF_SNA
|
||||
#define PF_DECnet AF_DECnet ///< protocol family
|
||||
///< @see AF_DECnet
|
||||
#define PF_DLI AF_DLI ///< protocol family
|
||||
///< @see AF_DLI
|
||||
#define PF_LAT AF_LAT ///< protocol family
|
||||
///< @see AF_LAT
|
||||
#define PF_HYLINK AF_HYLINK ///< protocol family
|
||||
///< @see AF_HYLINK
|
||||
#define PF_APPLETALK AF_APPLETALK ///< protocol family
|
||||
///< @see AF_APPLETALK
|
||||
#define PF_ROUTE AF_ROUTE ///< protocol family
|
||||
///< @see AF_ROUTE
|
||||
#define PF_LINK AF_LINK ///< protocol family
|
||||
///< @see AF_LINK
|
||||
#define PF_XTP pseudo_AF_XTP ///< protocol family (no address family defined, only PF)
|
||||
///< @see pseudo_AF_XTP
|
||||
#define PF_COIP AF_COIP ///< protocol family
|
||||
///< @see AF_COIP
|
||||
#define PF_CNT AF_CNT ///< protocol family
|
||||
///< @see AF_CNT
|
||||
#define PF_SIP AF_SIP ///< protocol family
|
||||
///< @see AF_SIP
|
||||
#define PF_IPX AF_IPX ///< protocol family (same format as AF_NS)
|
||||
///< @see AF_IPX
|
||||
///< @see AF_NS
|
||||
#define PF_RTIP pseudo_AF_RTIP ///< protocol family (same format as AF_INET)
|
||||
///< @see pseudo_AF_RTIP
|
||||
#define PF_PIP pseudo_AF_PIP ///< protocol family
|
||||
///< @see pseudo_AF_PIP
|
||||
#define PF_ISDN AF_ISDN ///< protocol family
|
||||
///< @see AF_ISDN
|
||||
#define PF_KEY pseudo_AF_KEY ///< protocol family
|
||||
///< @see pseudo_AF_KEY
|
||||
#define PF_INET6 AF_INET6 ///< protocol family
|
||||
///< @see AF_INET6
|
||||
#define PF_NATM AF_NATM ///< protocol family
|
||||
///< @see AF_NATM
|
||||
#define PF_ATM AF_ATM ///< protocol family
|
||||
///< @see AF_ATM
|
||||
#define PF_NETGRAPH AF_NETGRAPH ///< protocol family
|
||||
///< @see AF_NETGRAPH
|
||||
#define PF_MAX AF_MAX ///< maximum of protocol families
|
||||
///< @see AF_MAX
|
||||
|
||||
#define DESTINY_SOCKET_STATIC_MSS 48
|
||||
#define DESTINY_SOCKET_STATIC_MSS 48 ///< Static TCP maxmimum segment size.
|
||||
|
||||
/**
|
||||
* Static TCP flow control window for window size 1.
|
||||
*/
|
||||
#define DESTINY_SOCKET_STATIC_WINDOW 1 * DESTINY_SOCKET_STATIC_MSS
|
||||
|
||||
/**
|
||||
* Maximum size of TCP buffer.
|
||||
*/
|
||||
#define DESTINY_SOCKET_MAX_TCP_BUFFER 1 * DESTINY_SOCKET_STATIC_WINDOW
|
||||
|
||||
/**
|
||||
* Socket address type for IPv6 communication.
|
||||
*/
|
||||
typedef struct __attribute__((packed)) {
|
||||
uint8_t sin6_family; /* AF_INET6 */
|
||||
uint16_t sin6_port; /* transport layer port # */
|
||||
uint32_t sin6_flowinfo; /* IPv6 flow information */
|
||||
ipv6_addr_t sin6_addr; /* IPv6 address */
|
||||
uint8_t sin6_family; ///< set to AF_INET6
|
||||
uint16_t sin6_port; ///< transport layer port number
|
||||
uint32_t sin6_flowinfo; ///< IPv6 flow information
|
||||
ipv6_addr_t sin6_addr; ///< IPv6 address
|
||||
} sockaddr6_t;
|
||||
|
||||
/**
|
||||
* Creates new socket for communication in family *domain*, of type *type*,
|
||||
* and with protocol *protocol*. Roughly identical to POSIX's
|
||||
* <a href="http://man.he.net/man2/socket">socket(2)</a>.
|
||||
*
|
||||
* @param[in] domain Address family. Only AF_INET6 is supported by now (no
|
||||
* check on creation).
|
||||
* @param[in] type Communication type.
|
||||
* @param[in] protocol Protocol type. May be left 0 if domain and type are
|
||||
* sufficiant enough (I. e. domain=AF_INET6 and type=SOCK_STREAM
|
||||
* imply IPPROTO_TCP, etc.)
|
||||
* @return Socket ID on success, -1 otherwise.
|
||||
*/
|
||||
int destiny_socket(int domain, int type, int protocol);
|
||||
|
||||
/**
|
||||
* Connects socket *socket* with a foreign host with IPv6 address *addr*
|
||||
* (of length *addrlen*) for connection orientated communication (e. g.
|
||||
* SOCK_STREAM). Roughly identical to POSIX's
|
||||
* <a href="http://man.he.net/man2/connect">connect(2)</a>.
|
||||
*
|
||||
* @param[in] socket The ID of the socket.
|
||||
* @param[in] addr The IPv6 address to connect to
|
||||
* @param[in] addrlen Length of the IPv6 address in byte (always 16)
|
||||
*
|
||||
* @return 0 on success, -1 otherwise
|
||||
*/
|
||||
int destiny_socket_connect(int socket, sockaddr6_t *addr,
|
||||
socklen_t addrlen);
|
||||
|
||||
@ -201,12 +267,58 @@ int32_t destiny_socket_send(int s, const void *buf, uint32_t len, int flags);
|
||||
*/
|
||||
int32_t destiny_socket_sendto(int s, const void *buf, uint32_t len, int flags,
|
||||
sockaddr6_t *to, socklen_t tolen);
|
||||
int32_t destiny_socket_send(int s, void *msg, uint32_t len, int flags);
|
||||
int32_t destiny_socket_recv(int s, void *buf, uint32_t len, int flags);
|
||||
|
||||
/**
|
||||
* Closes the socket *s* and removes it.
|
||||
*
|
||||
* @param[in] s The ID of the socket to close.
|
||||
*
|
||||
* @return 0 on success, -1 otherwise.
|
||||
*/
|
||||
int destiny_socket_close(int s);
|
||||
int destiny_socket_bind(int s, sockaddr6_t *name, int namelen);
|
||||
|
||||
/**
|
||||
* Assigns an IPv6 address *addr* to the socket *s*. Roughly identical to
|
||||
* POSIX's <a href="http://man.he.net/man2/bind">bind(2)</a>.
|
||||
*
|
||||
* @param[in] s The ID of the socket.
|
||||
* @param[in] addr The IPv6 address to bind to.
|
||||
* @param[in] addrlen Length of address in byte (always 16)
|
||||
*
|
||||
* @return 0 on success, -1 otherwise.
|
||||
*/
|
||||
int destiny_socket_bind(int s, sockaddr6_t *addr, int addrlen);
|
||||
|
||||
/**
|
||||
* Marks socket *s* as an passive socket, that listens for incoming messages.
|
||||
* Roughly identical to POSIX's <a href="http://man.he.net/man2/listen">listen(2)</a>.
|
||||
*
|
||||
* @param[in] s The ID of the socket.
|
||||
* @param[in] backlog Not implemented yet, may be 0.
|
||||
*
|
||||
* @return 0 on success, -1 otherwise.
|
||||
*/
|
||||
int destiny_socket_listen(int s, int backlog);
|
||||
|
||||
/**
|
||||
* Blocks the current thread and waits for incoming communication on the listening
|
||||
* socket *s*. Roughly identical to POSIX's
|
||||
* <a href="http://man.he.net/man2/accept">accept(2)</a>.
|
||||
*
|
||||
* @param[in] s The ID of the socket.
|
||||
* @param[in] addr The IPv6 address of the peer socket, or NULL if not
|
||||
* needed (not implemented yet).
|
||||
* @param[in] addrlen The length of *addr*, or NULL if not needed.
|
||||
*
|
||||
* @return New socket ID for communication. -1 on error.
|
||||
*/
|
||||
int destiny_socket_accept(int s, sockaddr6_t *addr, socklen_t *addrlen);
|
||||
|
||||
/**
|
||||
* Outputs a list of all open sockets to stdout. Information includes its
|
||||
* creation parameters, local and foreign address and ports, it's ID and the
|
||||
* PIDs of the send and receive thread.
|
||||
*/
|
||||
void destiny_socket_print_sockets(void);
|
||||
|
||||
/**
|
||||
|
||||
Loading…
Reference in New Issue
Block a user