/***************************************************************************
 * Copyright 2007 - 2009 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;

/*
 * Address families
 */
/** \brief IPv4 */
#define VMK_SOCKET_AF_INET       2

/*
 * Socket types
 */
/** \brief Datagrams */
#define VMK_SOCKET_SOCK_DGRAM    2

/** \brief Raw datagrams */
#define VMK_SOCKET_SOCK_RAW      3

/*
 * Socket option levels
 */
/** \brief Operate on the socket itself */
#define VMK_SOCKET_SOL_SOCKET       0xffff

/*
 * Socket-level socket options
 */
/** \brief Bind socket to a vmknic */
#define VMK_SOCKET_SO_BINDTOVMK       0x1016

/**
 * \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;

/*
 ***********************************************************************
 * vmk_SocketAddrToString --                                      */ /**
 *
 * \ingroup Socket
 * \brief Convert an address into a simple string for a particular
 *        address family.
 *
 * \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.
 *
 * \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[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.
 *
 * \note This function will not block.
 *
 * \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_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_SocketClose --                                             */ /**
 *
 * \ingroup Socket
 * \brief Destroy an existing socket.
 *
 * \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_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
 *
 * \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
 *
 * \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.
 *
 * \note This function may block if flags VMK_SOCKET_MSG_DONTWAIT is not
 *       set or is not a nonblocking socket (default).
 *
 * \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_SocketGetSockName --                                       */ /**
 *
 * \ingroup Socket
 * \brief Get the socket's local endpoint network address information.
 *
 * \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.
 *
 * \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_ */
/** @} */