/*************************************************************************** * Copyright 2007 - 2012 VMware, Inc. All rights reserved. ***************************************************************************/ /* * @VMKAPIMOD_LICENSE@ */ /* *********************************************************************** * Sockets */ /** * \defgroup Socket Network Socket Interfaces * @{ * *********************************************************************** */ #ifndef _VMKAPI_SOCKET_H_ #define _VMKAPI_SOCKET_H_ /** \cond never */ #ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H #error This vmkapi file should never be included directly but only via vmkapi.h #endif /** \endcond never */ /** * \brief Opaque socket handle. */ typedef struct vmk_SocketInt *vmk_Socket; /** * \brief Definition for an invalid vmk_Socket. */ #define VMK_SOCKET_INVALID ((vmk_Socket)NULL) /* * Address families */ /** \brief IPv4 */ #define VMK_SOCKET_AF_INET 2 /** \brief IPv6 */ #define VMK_SOCKET_AF_INET6 28 /* * Socket types */ /** \brief Streaming */ #define VMK_SOCKET_SOCK_STREAM 1 /** \brief Datagrams */ #define VMK_SOCKET_SOCK_DGRAM 2 /** \brief Raw datagrams */ #define VMK_SOCKET_SOCK_RAW 3 /* * Flags for vmk_SocketSendTo() and vmk_SocketRecvFrom() */ /** \brief Send/receive of this message should not block */ #define VMK_SOCKET_MSG_DONTWAIT 0x80 /* * Socket option levels */ /** \brief Operate on the socket itself */ #define VMK_SOCKET_SOL_SOCKET 0xffff /* * Socket-level socket options */ /** \brief Allow local address reuse */ #define VMK_SOCKET_SO_REUSEADDR 0x0004 /** \brief Keep connections alive */ #define VMK_SOCKET_SO_KEEPALIVE 0x0008 /** \brief Just use interface addresses */ #define VMK_SOCKET_SO_DONTROUTE 0x0010 /** \brief Linger on close if data present */ #define VMK_SOCKET_SO_LINGER 0x0080 /** \brief Allow local address and port reuse */ #define VMK_SOCKET_SO_REUSEPORT 0x0200 /** \brief Timestamp received dgram traffic */ #define VMK_SOCKET_SO_TIMESTAMP 0x0400 /** \brief Use non-blocking socket semantics */ #define VMK_SOCKET_SO_NONBLOCKING 0x1015 /** \brief Bind socket to a vmknic * \note Note that the TCP/IP stack will only transmit the packet if the routing * decision indicates that it can be sent out of the specified vmknic. */ #define VMK_SOCKET_SO_BINDTOVMK 0x1016 /* * Values for the vmk_SocketShutdown()'s "how" parameter */ /** \brief Further receives will be disallowed */ #define VMK_SOCKET_SHUT_RD 0 /** \brief Further sends will be disallowed. */ #define VMK_SOCKET_SHUT_WR 1 /** \brief Further sends and receives will be disallowed. */ #define VMK_SOCKET_SHUT_RDWR 2 /** * \brief * Abstract socket network address * * A protocol-specific address is used in actual practice. */ typedef struct vmk_SocketAddress { vmk_uint8 sa_len; vmk_uint8 sa_family; vmk_uint8 sa_data[254]; } VMK_ATTRIBUTE_PACKED vmk_SocketAddress; /** * \brief * Data structure for setting the VMK_SOCKET_SO_LINGER option */ typedef struct vmk_SocketLingerData { /** \brief Whether linger is enabled or not */ vmk_uint32 enabled; /** \brief Linger duration (in seconds) */ vmk_uint32 duration; } VMK_ATTRIBUTE_PACKED vmk_SocketLingerData; /* *********************************************************************** * vmk_SocketAddrToString -- */ /** * * \ingroup Socket * \brief Convert an address into a simple string for a particular * address family. * * \nativedriversdisallowed * * \note This function will not block. * * \param[in] addr Address to translate to a string. * \param[out] buffer Buffer to place the converted string into. * \param[in] bufferLength Length of the buffer in bytes. * * \retval VMK_OK Success. * \retval VMK_BAD_PARAM Bad input addr or buffer * \retval VMK_NOT_SUPPORTED Unknown address family. * * \note This call does *not* do any sort of network lookup. It merely * converts an address into a human-readable format. In most * cases the converted string is simply a numeric string. * *********************************************************************** */ VMK_ReturnStatus vmk_SocketAddrToString(const vmk_SocketAddress *addr, char *buffer, int bufferLength); /* *********************************************************************** * vmk_SocketStringToAddr -- */ /** * * \ingroup Socket * \brief Convert an address into a simple string for a particular * address family. * * \nativedriversdisallowed * * \note This function will not block. * * \param[in] addressFamily Address family that the string address * will be converted into. * \param[in] buffer Buffer containing the string to convert. * \param[in] bufferLength Length of the buffer in bytes. * \param[in,out] addr Address the string is converted into. * * \retval VMK_OK Success. * \retval VMK_BAD_PARAM Bad input addr or buffer * \retval VMK_NOT_SUPPORTED Unknown address family. * \note This call does *not* do any sort of network lookup. It merely * converts a simple human-readable string into a address. In most * cases, this is simply a conversion of a numeric string into * a network address. * *********************************************************************** */ VMK_ReturnStatus vmk_SocketStringToAddr(int addressFamily, const char *buffer, int bufferLength, vmk_SocketAddress *addr); /* *********************************************************************** * vmk_SocketCreate -- */ /** * * \ingroup Socket * \brief Create a new unbound socket. * * \nativedriversdisallowed * * \note This function will not block. * \note The default behavior is to create a blocking socket. If * nonblocking behavior is required then the * VMK_SOCKET_SO_NONBLOCKING socket option must be set. * * \param[in] domain Protocol family for this socket. * \param[in] type Type of communication on this socket * \param[in] protocol Specific protocol to use from address family * \param[out] socket Newly created socket * * \retval VMK_OK Success. * \retval VMK_BAD_PARAM Bad input parameter. * \retval VMK_NO_MODULE_HEAP The module's heap is not set. * \retval VMK_NO_MEMORY Unable to allocate memory for socket. * \retval VMK_EPROTONOSUPPORT Maps to BSD error code EPROTONOSUPPORT. * \retval VMK_BAD_PARAM_TYPE Maps to BSD error code EPROTOTYPE. * \retval VMK_NO_BUFFERSPACE Maps to BSD error code ENOBUFS. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_NO_ACCESS Maps to BSD error code EACCESS. * * \note For BSD error code definitions see the FreeBSD 7 man page * socket(2). * * \note Specific domain (VMK_SOCKET_AF_*), type (VMK_SOCKET_SOCK_*), * and protocol (VMK_SOCKET_*PROTO*) values are implementation * dependent, an application can determine if a specific domain * and type is supported by trying to create a socket with zero * protocol value. * *********************************************************************** */ VMK_ReturnStatus vmk_SocketCreate(int domain, int type, int protocol, vmk_Socket *socket); /* *********************************************************************** * vmk_SocketBind -- */ /** * * \ingroup Socket * \brief Bind a socket to a network address endpoint. * * \nativedriversdisallowed * * \note This function will not block. * * \param[in] socket Socket to bind to the network address * \param[in] address Information describing the network address * that the socket will be bound to. * \param[in] addressLength Length in bytes of the network address * information. * * \retval VMK_BAD_PARAM Socket was already bound * \retval VMK_NOT_SUPPORTED Unknown socket type. * \retval VMK_NO_MODULE_HEAP This module's heap is not set. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_BAD_PARAM Maps to BSD error code EINVAL. * \retval VMK_EADDRNOTAVAIL Maps to BSD error code EADDRNOTAVAIL. * \retval VMK_ADDRFAM_UNSUPP Maps to BSD error code EAFNOSUPPORT. * \retval VMK_EADDRINUSE Maps to BSD error code EADDRINUSE. * \retval VMK_NO_ACCESS Maps to BSD error code EACCESS. * * \note For BSD error code definitions see the FreeBSD 7 man page * bind(2). * *********************************************************************** */ VMK_ReturnStatus vmk_SocketBind(vmk_Socket socket, vmk_SocketAddress *address, int addressLength); /* *********************************************************************** * vmk_SocketConnect -- */ /** * * \ingroup Socket * \brief Connect to a network address * * \nativedriversdisallowed * * \note This function may block if the socket is blocking socket * (this is the default behavior). If nonblocking behavior is required * then the VMK_SOCKET_SO_NONBLOCKING socket option must be set. * * \param[in] socket Socket to connect through. * \param[in] address The network address info for the address * to connect to. * \param[in] addressLength The length of the address info. * * \retval VMK_NOT_SUPPORTED Unknown socket type. * \retval VMK_EALREADY Socket already connected. * \retval VMK_EINPROGRESS Socket is nonblocking and connection * is still in progress. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_ALREADY_CONNECTED Maps to BSD error code EISCONN. * \retval VMK_BAD_PARAM Maps to BSD error code EINVAL. * \retval VMK_EADDRNOTAVAIL Maps to BSD error code EADDRNOTAVAIL. * \retval VMK_ADDRFAM_UNSUPP Maps to BSD error code EAFNOSUPPORT. * \retval VMK_EADDRINUSE Maps to BSD error code EADDRINUSE. * \retval VMK_NO_ACCESS Maps to BSD error code EACCESS. * * \note For BSD error code definitions see the FreeBSD 7 man page * connect(2). * *********************************************************************** */ VMK_ReturnStatus vmk_SocketConnect(vmk_Socket socket, vmk_SocketAddress *address, int addressLength); /* *********************************************************************** * vmk_SocketShutdown -- */ /** * * \ingroup Socket * \brief Shutdown part or all of a connection on a socket * * \nativedriversdisallowed * * \note This function may block if VMK_SOCKET_SO_LINGER has been set * otherwise it will not block. * * \param[in] socket Socket to query. * \param[in] how Data direction(s) to shutdown on the socket. * * \retval VMK_NOT_SUPPORTED Unknown socket type. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_ECONNRESET Maps to BSD error code ECONNRESET. * \retval VMK_ENOTCONN Maps to BSD error code ENOTCONN. * * \note For BSD error code definitions see the FreeBSD 7 man page * shutdown(2). * *********************************************************************** */ VMK_ReturnStatus vmk_SocketShutdown(vmk_Socket socket, int how); /* *********************************************************************** * vmk_SocketClose -- */ /** * * \ingroup Socket * \brief Destroy an existing socket. * * \nativedriversdisallowed * * \note This function may block if VMK_SOCKET_SO_LINGER has been set * otherwise will not block. * * \param[in] socket Socket to close * * \retval VMK_OK Success. * \retval VMK_BAD_PARAM Input socket is invalid. * \retval VMK_NO_MODULE_HEAP The module's heap is not set. * \retval VMK_BUSY Socket is already closing. * \retval VMK_NOT_SUPPORTED Unknown socket type. * *********************************************************************** */ VMK_ReturnStatus vmk_SocketClose(vmk_Socket socket); /* *********************************************************************** * vmk_SocketGetSockOpt -- */ /** * * \ingroup Socket * \brief Get the option information from a socket * * \nativedriversdisallowed * * \note This function will not block. * * \param[in] socket Socket to get the option info from. * \param[in] level Level of communication infrastructure from which * to get the socket option. * \param[in] option The option to get the information about. * \param[out] optval Data that is currently set on the option. * \param[out] optlen The length of option data. * * \retval VMK_OK Success. * \retval VMK_BAD_PARAM Input socket is invalid. * \retval VMK_NOT_SUPPORTED Unknown socket type. * \retval VMK_NOT_SUPPORTED Maps to BSD error code ENOPROTOOPT. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_BAD_PARAM Maps to BSD error code EINVAL. * * \note For BSD error code definitions see the FreeBSD 7 man page * getsockopt(2). * *********************************************************************** */ VMK_ReturnStatus vmk_SocketGetSockOpt(vmk_Socket socket, int level, int option, void *optval, int *optlen); /* *********************************************************************** * vmk_SocketSetSockOpt -- */ /** * * \ingroup Socket * \brief Set the option information on a socket * * \nativedriversdisallowed * * \note This function will not block. * * \param[in] socket Socket to set the option info on. * \param[in] level Level of communication infrastructure from which * to set the socket option. * \param[in] option The option to set the information about. * \param[in] optval Data to set on the option. * \param[in] optlen The length of the option data. * * \retval VMK_OK Success. * \retval VMK_BAD_PARAM Input socket is invalid. * \retval VMK_NOT_SUPPORTED Unknown socket type. * \retval VMK_NOT_SUPPORTED Maps to BSD error code ENOPROTOOPT. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_BAD_PARAM Maps to BSD error code EINVAL. * * \note For BSD error code definitions see the FreeBSD 7 man page * setsockopt(2). * *********************************************************************** */ VMK_ReturnStatus vmk_SocketSetSockOpt(vmk_Socket socket, int level, int option, const void *optval, int optlen); /* *********************************************************************** * vmk_SocketSendTo -- */ /** * * \ingroup Socket * \brief Send data to a network address. * * \nativedriversdisallowed * * \note This function may block if the VMK_SOCKET_MSG_DONTWAIT flag is * not set or the socket is a blocking socket. * * \param[in] socket Socket to send the data through. * \param[in] flags Settings for this send transaction. * \param[in] address Address information describing the * data's destination. * \param[in] data Pointer to data buffer to send. * \param[in] len Length in bytes of the data buffer to send. * \param[out] bytesSent Number of bytes actually sent. * * \retval VMK_OK Success. * \retval VMK_NOT_SUPPORTED Unknown socket type. * \retval VMK_BAD_PARAM Unsupported flags setting. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_ENOTCONN Maps to BSD error code ENOTCONN. * \retval VMK_EDESTADDRREQ Maps to BSD error code EDESTADDRREQ. * \retval VMK_MESSAGE_TOO_LONG Maps to BSD error code EMSGSIZE. * \retval VMK_WOULD_BLOCK Maps to BSD error code EAGAIN. * \retval VMK_NO_BUFFERSPACE Maps to BSD error code ENOBUFS. * \retval VMK_EHOSTUNREACH Maps to BSD error code EHOSTUNREACH. * \retval VMK_ALREADY_CONNECTED Maps to BSD error code EISCONN. * \retval VMK_ECONNREFUSED Maps to BSD error code ECONNREFUSED. * \retval VMK_EHOSTDOWN Maps to BSD error code EHOSTDOWN. * \retval VMK_ENETDOWN Maps to BSD error code ENETDOWN. * \retval VMK_EADDRNOTAVAIL Maps to BSD error code EADDRNOTAVAIL. * \retval VMK_BROKEN_PIPE Maps to BSD error code EPIPE. * * \note For BSD error code definitions see the FreeBSD 7 man page * sendto(2). * *********************************************************************** */ VMK_ReturnStatus vmk_SocketSendTo(vmk_Socket socket, int flags, vmk_SocketAddress *address, void *data, int len, int *bytesSent); /* *********************************************************************** * vmk_SocketRecvFrom -- */ /** * * \ingroup Socket * \brief Receive data from a network address. * * \nativedriversdisallowed * * \note This function may block if the VMK_SOCKET_MSG_DONTWAIT flag is * not set or the socket is a blocking socket. * * \param[in] socket Socket to receive the data through. * \param[in] flags Settings for this receive transaction. * \param[in] address The source address information the * messages should be received from, * or NULL if this is not necessary for * the socket's protocol or settings. * \param[in,out] addressLength Length in bytes of the address * information. * \param[in] data Pointer to data buffer to receive to. * \param[in] len Length in bytes of the data buffer. * \param[out] bytesReceived Number of bytes actually received. * * \retval VMK_NOT_SUPPORTED Receive on unbound VMKLINK socket is * not supported. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_ENOTCONN Maps to BSD error code ENOTCONN. * \retval VMK_MESSAGE_TOO_LONG Maps to BSD error code EMSGSIZE. * \retval VMK_WOULD_BLOCK Maps to BSD error code EAGAIN. * \retval VMK_ECONNRESET Maps to BSD error code ECONNRESET. * \retval VMK_INVALID_ADDRESS Maps to BSD error code EFAULT. * * \note For BSD error code definitions see the FreeBSD 7 man page * recvfrom(2). * *********************************************************************** */ VMK_ReturnStatus vmk_SocketRecvFrom(vmk_Socket socket, int flags, vmk_SocketAddress *address, int *addressLength, void *data, int len, int *bytesReceived); /* *********************************************************************** * vmk_SocketGetSockName -- */ /** * * \ingroup Socket * \brief Get the socket's local endpoint network address information. * * \nativedriversdisallowed * * \note This function will not block. * * \param[in] socket Socket to query. * \param[out] address The network address info for the socket * local endpoint. * \param[in,out] addressLength The length of the address info. * * \retval VMK_OK Success. * \retval VMK_BAD_PARAM Bad input socket or address. * \retval VMK_NOT_SUPPORTED Unknown socket family. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_BAD_PARAM Maps to BSD error code EINVAL. * \retval VMK_NO_MEMORY Maps to BSD error code ENOMEM. * * \note For BSD error code definitions see the FreeBSD 7 man page * getsockname(2). * *********************************************************************** */ VMK_ReturnStatus vmk_SocketGetSockName(vmk_Socket socket, vmk_SocketAddress *address, int *addressLength); /* *********************************************************************** * vmk_SocketGetPeerName -- */ /** * * \ingroup Socket * \brief Get the socket's far endpoint network address information. * * \nativedriversdisallowed * * \note This function will not block. * * \param[in] socket Socket to query. * \param[out] address The network address info for the * socket remote endpoint. * \param[in,out] addressLength The length of the address info. * * \retval VMK_OK Success. * \retval VMK_BAD_PARAM Bad input socket or address. * \retval VMK_NOT_SUPPORTED Unknown socket family. * \retval VMK_EOPNOTSUPP Maps to BSD error code EOPNOTSUPP. * \retval VMK_NO_MEMORY Maps to BSD error code ENOMEM. * \retval VMK_ENOTCONN Maps to BSD error code ENOTCONN. * * \note For BSD error code definitions see the FreeBSD 7 man page * getpeername(2). * *********************************************************************** */ VMK_ReturnStatus vmk_SocketGetPeerName(vmk_Socket socket, vmk_SocketAddress *address, int *addressLength); #endif /* _VMKAPI_SOCKET_H_ */ /** @} */