WebSVN – HelenOS – Diff – /branches/network/uspace/srv/net/include/socket.h

 /*
  * Copyright (c) 2009 Lukas Mejdrech
  * All rights reserved.
+ *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
+ *
  * - Redistributions of source code must retain the above copyright
  *   notice, this list of conditions and the following disclaimer.
  * - Redistributions in binary form must reproduce the above copyright
  *   notice, this list of conditions and the following disclaimer in the
  *   documentation and/or other materials provided with the distribution.
  * - The name of the author may not be used to endorse or promote products
  *   derived from this software without specific prior written permission.
+ *
  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 /** @addtogroup socket
  *  @{
  */
 /** @file
  *  Socket application program interface (API).
  *  This is a part of the network application library.
  *  Based on the linux src/include/linux/socket.h header file and BSD socket interface.
  */
 #ifndef __NET_SOCKET_H__
 #define __NET_SOCKET_H__
 #include <sys/types.h>
 #include "byteorder.h"
 #include "in.h"
 #include "inet.h"
-/* Supported address families. */
+/** @name Address families definitions
+*/
+/*@{*/
 /** Unspecified address family.
  */
 #define AF_UNSPEC   0
 /** Unix domain sockets address family.
  */
 #define AF_UNIXL    1
 /** POSIX name for AF_UNIX address family.
  */
 #define AF_LOCAL    1
 /** Internet IP Protocol address family.
  */
 #define AF_INET     2
 /** Amateur Radio AX.25 address family.
  */
 #define AF_AX25     3
 /** Novell IPX address family.
  */
 #define AF_IPX      4
 /** AppleTalk DDP address family.
  */
 #define AF_APPLETALK    5
 /** Amateur Radio NET/ROM address family.
  */
 #define AF_NETROM   6
 /** Multiprotocol bridge address family.
  */
 #define AF_BRIDGE   7
 /** ATM PVCs address family.
  */
 #define AF_ATMPVC   8
 /** Reserved for X.25 project address family.
  */
 #define AF_X25      9
 /** IP version 6 address family.
  */
 #define AF_INET6    10
 /** Amateur Radio X.25 PLP address family.
  */
 #define AF_ROSE     11
 /** Reserved for DECnet project address family.
  */
 #define AF_DECnet   12
 /** Reserved for 802.2LLC project address family.
  */
 #define AF_NETBEUI  13
 /** Security callback pseudo AF address family.
  */
 #define AF_SECURITY 14
 /** PF_KEY key management API address family.
  */
 #define AF_KEY      15
 /** Alias to emulate 4.4BSD address family.
  */
 #define AF_NETLINK  16
 /** Packet family address family.
  */
 #define AF_PACKET   17
 /** Ash address family.
  */
 #define AF_ASH      18
 /** Acorn Econet address family.
  */
 #define AF_ECONET   19
 /** ATM SVCs address family.
  */
 #define AF_ATMSVC   20
 /** Linux SNA Project (nutters!) address family.
  */
 #define AF_SNA      22
 /** IRDA sockets address family.
  */
 #define AF_IRDA     23
 /** PPPoX sockets address family.
  */
 #define AF_PPPOX    24
 /** Wanpipe API Sockets address family.
  */
 #define AF_WANPIPE  25
 /** Linux LLC address family.
  */
 #define AF_LLC      26
 /** Controller Area Network address family.
  */
 #define AF_CAN      29
 /** TIPC sockets address family.
  */
 #define AF_TIPC     30
 /** Bluetooth sockets address family.
  */
 #define AF_BLUETOOTH    31
 /** IUCV sockets address family.
  */
 #define AF_IUCV     32
 /** RxRPC sockets address family.
  */
 #define AF_RXRPC    33
 /** Maximum address family.
  */
 #define AF_MAX      34
+/*@}*/
+/** @name Protocol families definitions
-/* Protocol families, same as address families. */
+ *  Same as address families.
+ */
+/*@{*/
+/** Unspecified protocol family.
+ */
 #define PF_UNSPEC   AF_UNSPEC
+/** Unix domain sockets protocol family.
+ */
-#define PF_UNIX     AF_UNIX
+#define PF_UNIXL    AF_UNIXL
+/** POSIX name for AF_UNIX protocol family.
+ */
 #define PF_LOCAL    AF_LOCAL
+/** Internet IP Protocol protocol family.
+ */
 #define PF_INET     AF_INET
+/** Amateur Radio AX.25 protocol family.
+ */
 #define PF_AX25     AF_AX25
+/** Novell IPX protocol family.
+ */
 #define PF_IPX      AF_IPX
+/** AppleTalk DDP protocol family.
+ */
 #define PF_APPLETALK    AF_APPLETALK
+/** Amateur Radio NET/ROM protocol family.
+ */
 #define PF_NETROM   AF_NETROM
+/** Multiprotocol bridge protocol family.
+ */
 #define PF_BRIDGE   AF_BRIDGE
+/** ATM PVCs protocol family.
+ */
 #define PF_ATMPVC   AF_ATMPVC
+/** Reserved for X.25 project protocol family.
+ */
 #define PF_X25      AF_X25
+/** IP version 6 protocol family.
+ */
 #define PF_INET6    AF_INET6
+/** Amateur Radio X.25 PLP protocol family.
+ */
 #define PF_ROSE     AF_ROSE
+/** Reserved for DECnet project protocol family.
+ */
 #define PF_DECnet   AF_DECnet
+/** Reserved for 802.2LLC project protocol family.
+ */
 #define PF_NETBEUI  AF_NETBEUI
+/** Security callback pseudo AF protocol family.
+ */
 #define PF_SECURITY AF_SECURITY
+/** PF_KEY key management API protocol family.
+ */
 #define PF_KEY      AF_KEY
+/** Alias to emulate 4.4BSD protocol family.
+ */
 #define PF_NETLINK  AF_NETLINK
-#define PF_ROUTE    AF_ROUTE
+/** Packet family protocol family.
+ */
 #define PF_PACKET   AF_PACKET
+/** Ash protocol family.
+ */
 #define PF_ASH      AF_ASH
+/** Acorn Econet protocol family.
+ */
 #define PF_ECONET   AF_ECONET
+/** ATM SVCs protocol family.
+ */
 #define PF_ATMSVC   AF_ATMSVC
+/** Linux SNA Project (nutters!) protocol family.
+ */
 #define PF_SNA      AF_SNA
+/** IRDA sockets protocol family.
+ */
 #define PF_IRDA     AF_IRDA
+/** PPPoX sockets protocol family.
+ */
 #define PF_PPPOX    AF_PPPOX
+/** Wanpipe API Sockets protocol family.
+ */
 #define PF_WANPIPE  AF_WANPIPE
+/** Linux LLC protocol family.
+ */
 #define PF_LLC      AF_LLC
+/** Controller Area Network protocol family.
+ */
 #define PF_CAN      AF_CAN
+/** TIPC sockets protocol family.
+ */
 #define PF_TIPC     AF_TIPC
+/** Bluetooth sockets protocol family.
+ */
 #define PF_BLUETOOTH    AF_BLUETOOTH
+/** IUCV sockets protocol family.
+ */
 #define PF_IUCV     AF_IUCV
+/** RxRPC sockets protocol family.
+ */
 #define PF_RXRPC    AF_RXRPC
+/** Maximum protocol family.
+ */
 #define PF_MAX      AF_MAX
+/*@}*/
+/** @name Socket option levels definitions
-/* Setsockoptions(2) level. Thanks to BSD these must match IPPROTO_xxx */
+ *  Thanks to BSD these must match IPPROTO_xxx
+ */
+/*@{*/
+/** IP socket option level.
+ */
 #define SOL_IP      0
+/** ICMP socket option level.
+ */
 #define SOL_ICMP    1
+/** TCP socket option level.
+ */
 #define SOL_TCP     6
+/** UDP socket option level.
+ */
 #define SOL_UDP     17
+/** IPV socket option level.
+ */
 #define SOL_IPV6    41
+/** ICMPV socket option level.
+ */
 #define SOL_ICMPV6  58
+/** SCTP socket option level.
+ */
 #define SOL_SCTP    132
+/** UDP-Lite (RFC 3828) socket option level.
+ */
-#define SOL_UDPLITE 136     /* UDP-Lite (RFC 3828) */
+#define SOL_UDPLITE 136
+/** RAW socket option level.
+ */
 #define SOL_RAW     255
+/** IPX socket option level.
+ */
 #define SOL_IPX     256
+/** AX socket option level.
+ */
 #define SOL_AX25    257
+/** ATALK socket option level.
+ */
 #define SOL_ATALK   258
+/** NETROM socket option level.
+ */
 #define SOL_NETROM  259
+/** ROSE socket option level.
+ */
 #define SOL_ROSE    260
+/** DECNET socket option level.
+ */
 #define SOL_DECNET  261
+/** X25 socket option level.
+ */
 #define SOL_X25     262
+/** PACKET socket option level.
+ */
 #define SOL_PACKET  263
+/** ATM layer (cell level) socket option level.
+ */
-#define SOL_ATM     264 /* ATM layer (cell level) */
+#define SOL_ATM     264
-#define SOL_AAL     265 /* ATM Adaption Layer (packet level) */
+/** ATM Adaption Layer (packet level) socket option level.
+ */
+#define SOL_AAL     265
+/** IRDA socket option level.
+ */
-#define SOL_IRDA        266
+#define SOL_IRDA    266
+/** NETBEUI socket option level.
+ */
 #define SOL_NETBEUI 267
+/** LLC socket option level.
+ */
 #define SOL_LLC     268
+/** DCCP socket option level.
+ */
 #define SOL_DCCP    269
+/** NETLINK socket option level.
+ */
 #define SOL_NETLINK 270
+/** TIPC socket option level.
+ */
 #define SOL_TIPC    271
+/** RXRPC socket option level.
+ */
 #define SOL_RXRPC   272
+/** PPPOL socket option level.
+ */
 #define SOL_PPPOL2TP    273
+/** BLUETOOTH socket option level.
+ */
 #define SOL_BLUETOOTH   274
+/*@}*/
 //
 /* * IPX options.
  */
 //#define IPX_TYPE  1
-/** Socket type type definition.
+/** Socket types.
  */
 typedef enum sock_type{
     /** Stream (connection oriented) socket.
      */
     SOCK_STREAM = 1,
     /** Datagram (connectionless oriented) socket.
      */
     SOCK_DGRAM  = 2,
     /** Raw socket.
      */
     SOCK_RAW    = 3
 } sock_type_t;
+/** Type definition of the socket length.
+ */
 typedef int32_t socklen_t;
+/** @name Socket application programming interface
+ */
+/*@{*/
+/** Creates a new socket.
+ *  @param domain The socket protocol family. Input parameter.
+ *  @param type Socket type. Input parameter.
+ *  @param protocol Socket protocol. Input parameter.
+ *  @returns The socket identifier on success.
+ *  @returns EPFNOTSUPPORT if the protocol family is not supported.
+ *  @returns ESOCKNOTSUPPORT if the socket type is not supported.
+ *  @returns EPROTONOSUPPORT if the protocol is not supported.
+ *  @returns ENOMEM if there is not enough memory left.
+ *  @returns Other error codes as defined for the NET_SOCKET message.
+ */
 int socket( int domain, int type, int protocol );
+/** Binds the socket to a port address.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param my_addr The port address. Input parameter.
+ *  @param addrlen The address length. Input parameter.
+ *  @returns EOK on success.
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns EBADMEM if the my_addr parameter is NULL.
+ *  @returns NO_DATA if the addlen parameter is zero (0).
+ *  @returns Other error codes as defined for the NET_SOCKET_BIND message.
+ */
 int bind( int socket_id, const struct sockaddr * my_addr, socklen_t addrlen );
+/** Sets the number of connections waiting to be accepted.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param backlog The maximum number of waiting sockets to be accepted. Input parameter.
+ *  @returns EOK on success.
+ *  @returns EINVAL if the backlog parameter is not positive (<=0).
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns Other error codes as defined for the NET_SOCKET_LISTEN message.
+ */
 int listen( int socket_id, int backlog );
+/** Accepts waiting socket.
+ *  Blocks until such a socket exists.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param cliaddr The remote client address. Output parameter.
+ *  @param addrlen The address length. Input parameter.
+ *  @returns EOK on success.
+ *  @returns EBADMEM if the cliaddr or addrlen parameter is NULL.
+ *  @returns EINVAL if the backlog parameter is not positive (<=0).
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns Other error codes as defined for the NET_SOCKET_ACCEPT message.
+ */
 int accept( int socket_id, struct sockaddr * cliaddr, socklen_t * addrlen );
+/** Connects socket to the remote server.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param serv_addr The remote server address. Input parameter.
+ *  @param addrlen The address length. Input parameter.
+ *  @returns EOK on success.
+ *  @returns EBADMEM if the serv_addr parameter is NULL.
+ *  @returns NO_DATA if the addlen parameter is zero (0).
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns Other error codes as defined for the NET_SOCKET_CONNECT message.
+ */
 int connect( int socket_id, const struct sockaddr * serv_addr, socklen_t addrlen );
+/** Closes the socket.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @returns EOK on success.
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns Other error codes as defined for the NET_SOCKET_CLOSE message.
+ */
 int closesocket( int socket_id );
+/** Sends data via the socket.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param data The data to be sent. Input parameter.
+ *  @param datalength The data length. Input parameter.
+ *  @param flags Various send flags. Input parameter.
+ *  @returns EOK on success.
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns EBADMEM if the data parameter is NULL.
+ *  @returns NO_DATA if the datalength parameter is zero (0).
+ *  @returns Other error codes as defined for the NET_SOCKET_SEND message.
+ */
 int send( int socket_id, void * data, size_t datalength, int flags );
+/** Sends data via the socket to the remote address.
+ *  Binds the socket to a free port if not already connected/bound.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param data The data to be sent. Input parameter.
+ *  @param datalength The data length. Input parameter.
+ *  @param flags Various send flags. Input parameter.
+ *  @param toaddr The destination address. Input parameter.
+ *  @param addrlen The address length. Input parameter.
+ *  @returns EOK on success.
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns EBADMEM if the data or toaddr parameter is NULL.
+ *  @returns NO_DATA if the datalength or the addrlen parameter is zero (0).
+ *  @returns Other error codes as defined for the NET_SOCKET_SENDTO message.
+ */
 int sendto( int socket_id, const void * data, size_t datalength, int flags, const struct sockaddr * toaddr, socklen_t addrlen );
+/** Receives data via the socket.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param data The data buffer to be filled. Output parameter.
+ *  @param datalength The data length. Input parameter.
+ *  @param flags Various receive flags. Input parameter.
+ *  @returns EOK on success.
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns EBADMEM if the data parameter is NULL.
+ *  @returns NO_DATA if the datalength parameter is zero (0).
+ *  @returns Other error codes as defined for the NET_SOCKET_RECV message.
+ */
 int recv( int socket_id, void * data, size_t datalength, int flags );
+/** Receives data via the socket.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param data The data buffer to be filled. Output parameter.
+ *  @param datalength The data length. Input parameter.
+ *  @param flags Various receive flags. Input parameter.
+ *  @param fromaddr The source address. Output parameter.
+ *  @param addrlen The address length. The maximum address length is read. The actual address length is set. Input/output parameter.
+ *  @returns EOK on success.
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns EBADMEM if the data or fromaddr parameter is NULL.
+ *  @returns NO_DATA if the datalength or addrlen parameter is zero (0).
+ *  @returns Other error codes as defined for the NET_SOCKET_RECVFROM message.
+ */
 int recvfrom( int socket_id, void * data, size_t datalength, int flags, struct sockaddr * fromaddr, socklen_t * addrlen );
+/** Gets socket option.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param level The socket options level. Input parameter.
+ *  @param optname The socket option to be get. Input parameter.
+ *  @param value The value buffer to be filled. Output parameter.
+ *  @param optlen The value buffer length. The maximum length is read. The actual length is set. Input/output parameter.
+ *  @returns EOK on success.
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns EBADMEM if the value or optlen parameter is NULL.
+ *  @returns NO_DATA if the optlen parameter is zero (0).
+ *  @returns Other error codes as defined for the NET_SOCKET_GETSOCKOPT message.
+ */
 int getsockopt( int socket_id, int level, int optname, void * value, size_t * optlen );
+/** Sets socket option.
+ *  @param socket_id Socket identifier. Input parameter.
+ *  @param level The socket options level. Input parameter.
+ *  @param optname The socket option to be set. Input parameter.
+ *  @param value The value to be set. Input parameter.
+ *  @param optlen The value length. Input parameter.
+ *  @returns EOK on success.
+ *  @returns ENOTSOCK if the socket is not found.
+ *  @returns EBADMEM if the value parameter is NULL.
+ *  @returns NO_DATA if the optlen parameter is zero (0).
+ *  @returns Other error codes as defined for the NET_SOCKET_SETSOCKOPT message.
+ */
 int setsockopt( int socket_id, int level, int optname, const void * value, size_t optlen );
+/*@}*/
 #endif
 /** @}
  */

Subversion Repositories HelenOS

(root)/branches/network/uspace/srv/net/include/socket.h – Rev 4603 → 4701