owner-nrf52sdk/nRF5_SDK_15.3.0/components/iot/socket/api/socket_api.h

/**
 * Copyright (c) 2015 - 2019, Nordic Semiconductor ASA
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form, except as embedded into a Nordic
 *    Semiconductor ASA integrated circuit in a product or a software update for
 *    such product, 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.
 *
 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
 *    contributors may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * 4. This software, with or without modification, must only be used with a
 *    Nordic Semiconductor ASA integrated circuit.
 *
 * 5. Any software provided in binary form under this license must not be reverse
 *    engineered, decompiled, modified and/or disassembled.
 *
 * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS 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.
 *
 */
/**@file socket_api.h
 *
 * @defgroup iot_socket BSD Socket interface
 * @ingroup iot_sdk_socket
 * @{
 * @brief Nordic socket interface for IoT.
 *
 * @details This module provides the socket interface for writing IoT applications. The API is
 *          designed to be compatible with the POSIX/BSD socket interface for the purpose of
 *          making porting easy. The socket options API has been extended to support configuring
 *          Nordic BLE stack, tuning of RF parameters as well as security options.
 */
#ifndef SOCKET_API_H__
#define SOCKET_API_H__

#include <stdint.h>

#include "sdk_common.h"
#include "iot_defines.h"
#include "errno.h"

#ifdef __cplusplus
extern "C" {
#endif

#if !defined(__GNUC__) || (__GNUC__ == 0)
typedef int32_t ssize_t;
#else
#include <sys/types.h>
#ifdef __SES_ARM
typedef int32_t ssize_t;
#endif
#endif

#ifndef htons
#define htons(x) HTONS(x)   /**< Convert byte order from host to network (short). */
#endif

#ifndef htonl
#define htonl(x) HTONL(x)   /**< Convert byte order from host to network (long). */
#endif

#ifndef ntohs
#define ntohs(x) NTOHS(x)   /**< Convert byte order from network to host (short). */
#endif

#ifndef ntohl
#define ntohl(x) NTOHL(x)   /**< Convert byte order from network to host (long). */
#endif

/**@defgroup socket_families Values for socket_family_t
 * @ingroup iot_socket
 * @{
 */
#define AF_INET             2   /**< IPv4 socket family.                 */
#define AF_INET6            10  /**< IPv6 socket family.                 */
#if defined(NRF52) || defined(NRF52_SERIES)
#define AF_NRF_CFG          39  /**< nRF configuration socket.*/
#endif
/**@} */

/**@defgroup socket_types Values for socket_type_t
 * @ingroup iot_socket
 * @{
 */
#define SOCK_STREAM         1        /**< TCP socket type. */
#define SOCK_DGRAM          2        /**< UDP socket type. */
/**@} */

/**@defgroup socket_protocols Values for socket_protocol_t
 * @ingroup iot_socket
 * @{
 */
#define IPPROTO_TCP         1       /**< Use TCP as transport protocol. */
#define IPPROTO_UDP         2       /**< Use UDP as transport protocol. */
/**@} */

/**@defgroup socket_send_recv_flags Socket send/recv flags
 * @ingroup iot_socket
 * @{
 */
#define MSG_DONTROUTE       0x01    /**< Send only to hosts on directly connected networks.                                */
#define MSG_DONTWAIT        0x02    /**< Enables non-blocking operation.                                                    */
#define MSG_OOB             0x04    /**< Sends out-of-band data on sockets that support this.                              */
#define MSG_PEEK            0x08    /**< Return data from the beginning of receive queue without removing data from the queue. */
#define MSG_WAITALL         0x10    /**< Request a blocking operation until the request is satisfied.                            */
/**@} */

#if defined(NRF52) || defined(NRF52_SERIES)
/**
 * @defgroup socket_option_levels Values for socket_opt_lvl_t
 * @ingroup iot_socket
 * @{
 */
#define SOL_SOCKET          1       /**< Standard socket options.                                             */
#define SOL_NRF_MEDIUM      2       /**< Nordic medium socket options. Use this to control medium parameters. */
/**@} */

/**@defgroup socket_medium_options Medium socket option level types
 * @ingroup iot_socket
 * @{
 */
#define MEDIUM_INIT_PARAMS  1       /**< Medium initialization parameters. */
/**@}
 */
#endif

/**@defgroup fcnt_commands fcntl commands
 * @ingroup iot_socket
 * @{
 */
#define F_SETFL             1       /**< Set flag. */
#define F_GETFL             2       /**< Get flag. */
/**@} */

/**@defgroup fcnt_flags fcntl flags
 * @ingroup iot_socket
 * @{
 */
#define O_NONBLOCK          0x01    /**< Use non-blocking I/O. */
/**@} */

/**
 * @brief Socket module size type.
 */
typedef uint32_t socklen_t;

/**
 * @brief Socket port type.
 */
typedef uint16_t in_port_t;

/**
 * @brief Structure specifying time interval.
 */
struct timeval
{
    uint32_t tv_sec;    /**< Time interval seconds. */
    uint32_t tv_usec;   /**< Time interval microseconds. */
};

/**
 * @brief Socket families.
 *
 * @details For a list of valid values, refer to @ref socket_families.
 */
typedef int socket_family_t;
typedef socket_family_t sa_family_t;

/**
 * @brief Socket types.
 *
 * @details For a list of valid values refer to @ref socket_types.
 */
typedef int socket_type_t;

/**
 * @brief Socket protocols.
 *
 * @details Use 0 if you do not want do specify socket protocol, which should be sufficient for most users.
 *          Other values are only provided for socket API compatibility, see @ref socket_protocols.
 */
typedef int socket_protocol_t;

/**
 * @if (IOT)
 * @brief Socket option levels.
 *
 * @details For a list of valid values, refer to @ref socket_option_levels.
 * @endif
 */
typedef int socket_opt_lvl_t;

/**
 * @brief Generic socket address.
 *
 * @details Only provided for API compatibility.
 */
struct sockaddr
{
    uint8_t         sa_len;
    socket_family_t sa_family;
    char            sa_data[];
};

/**
 * @brief IPv6 address.
 */
struct in6_addr
{
    uint8_t s6_addr[16];
};

/**
 * @brief IPv4 address.
 */
typedef uint32_t in_addr_t;

/**
 * @brief IPv4 address structure.
 */
struct in_addr
{
    in_addr_t s_addr;
};

/**
 * @brief Global IPv6 any-address.
 */
extern const struct in6_addr in6addr_any;

/**
 * @brief Global IPv4 any-address.
 */
extern const struct in_addr  inaddr_any;

/**
 * @brief Address record for IPv6 addresses.
 *
 * @details Contains the address and port of the host, as well as other socket options. All fields
 *          in this structure are compatible with the POSIX variant for API compatibility.
 */
struct sockaddr_in6
{
    uint8_t         sin6_len;               /**< Length of this data structure. */
    sa_family_t     sin6_family;            /**< Socket family. */
    in_port_t       sin6_port;              /**< Port, in network byte order. */

    uint32_t        sin6_flowinfo;          /**< IPv6 flow info parameters. Not used. */
    struct in6_addr sin6_addr;              /**< IPv6 address. */
    uint32_t        sin6_scope_id;          /**< IPv6 scope ID. Not used. */
};

/**
 * @brief Address record for IPv4 addresses.
 *
 * @details Contains the address and port of the host. All fields
 *          in this structure are compatible with the POSIX variant for API compatibility.
 */
struct sockaddr_in
{
    uint8_t         sin_len;               /**< Length of this data structure. */
    sa_family_t     sin_family;            /**< Socket family. */
    in_port_t       sin_port;              /**< Port, in network byte order. */

    struct in_addr  sin_addr;              /**< IPv4 address. */
};

typedef struct sockaddr     sockaddr_t;
typedef struct sockaddr_in6 sockaddr_in6_t;
typedef struct in6_addr     in6_addr_t;
typedef struct sockaddr_in  sockaddr_in_t;

/**
 * @brief Function for creating a socket.
 *
 * @details API to create a socket that can be used for network communication independently
 *          of lower protocol layers.
 *
 * @param[in] family    The protocol family of the network protocol to use. Currently, only
 *                      AF_INET6 is supported.
 * @param[in] type      The protocol type to use for this socket.
 * @param[in] protocol  The transport protocol to use for this socket.
 *
 * @return A non-negative socket descriptor on success, or -1 on error.
 */
int socket(socket_family_t family, socket_type_t type, socket_protocol_t protocol);

/**
 * @brief Function for closing a socket and freeing any resources held by it.
 *
 * @details If the socket is already closed, this function is a noop.
 *
 * @param[in] sock  The socket to close.
 *
 * @return 0 on success, or -1 on error.
 */
int close(int sock);

/**
 * @brief Function for controlling file descriptor options.
 *
 * @details Set or get file descriptor options or flags. For a list of supported commands, refer to @ref fcnt_commands.
 *          For a list of supported flags, refer to @ref fcnt_flags.
 *
 * @param[in] fd    The descriptor to set options on.
 * @param[in] cmd   The command class for options.
 * @param[in] flags The flags to set.
 */
int fcntl(int fd, int cmd, int flags);

/**
 * @brief Function for connecting to an endpoint with a given address.
 *
 * @details The socket handle must be a valid handle that has not yet been connected. Running
 *          connect on a connected handle will return an error.
 *
 * @param[in] sock          The socket to use for connection.
 * @param[in] p_servaddr    The address of the server to connect to. Currently, sockaddr_in6 is
 *                          the only supported type.
 * @param[in] addrlen       The size of the p_servaddr argument.
 *
 * @return 0 on success, or -1 on error.
 */
int connect(int sock, const void * p_servaddr, socklen_t addrlen);

/**
 * @brief Function for sending data through a socket.
 *
 * @details By default, this function will block unless the O_NONBLOCK
 *          socket option has been set, OR MSG_DONTWAIT is passed as a flag. In that case, the
 *          method will return immediately.
 *
 * @param[in] sock     The socket to write data to.
 * @param[in] p_buff   Buffer containing the data to send.
 * @param[in] nbytes   Size of data contained on p_buff.
 * @param[in] flags    Flags to control send behavior.
 *
 * @return The number of bytes that were sent on success, or -1 on error.
 */
ssize_t send(int sock, const void * p_buff, size_t nbytes, int flags);

/**
 * @brief Function for sending datagram through a socket.
 *
 * @details By default, this function will block if the lower layers are not able to process the
 *          packet, unless the O_NONBLOCK socket option has been set, OR MSG_DONTWAIT is passed as a flag.
 *          In that case, the method will return immediately.
 *
 * @param[in] sock          The socket to write data to.
 * @param[in] p_buff        Buffer containing the data to send.
 * @param[in] nbytes        Size of data contained in p_buff.
 * @param[in] flags         Flags to control send behavior.
 * @param[in] p_servaddr    The address of the server to send to. Currently, sockaddr_in6 is
 *                          the only supported type.
 * @param[in] addrlen       The size of the p_servaddr argument.
 *
 * @return The number of bytes that were sent on success, or -1 on error.
 */
ssize_t sendto(int          sock,
               const void * p_buff,
               size_t       nbytes,
               int          flags,
               const void * p_servaddr,
               socklen_t    addrlen);

/**
 * @brief Function for writing data to a socket. See \ref send() for details.
 *
 * @param[in] sock     The socket to write data to.
 * @param[in] p_buff   Buffer containing the data to send.
 * @param[in] nbytes   Size of data contained in p_buff.
 *
 * @return The number of bytes that were sent on success, or -1 on error.
 */
ssize_t write(int sock, const void * p_buff, size_t nbytes);

/**
 * @brief Function for receiving data on a socket.
 *
 * @details API for receiving data from a socket. By default, this function will block, unless the
 *          O_NONBLOCK socket option has been set, or MSG_DONTWAIT is passed as a flag.
 *
 * @param[in]  sock     The socket to receive data from.
 * @param[out] p_buff   Buffer to hold the data to be read.
 * @param[in]  nbytes   Number of bytes to read. Should not be larger than the size of p_buff.
 * @param[in]  flags    Flags to control receive behavior.
 *
 * @return The number of bytes that were read, or -1 on error.
 */
ssize_t recv(int sock, void * p_buff, size_t nbytes, int flags);

/**
 * @brief Function for receiving datagram on a socket.
 *
 * @details API for receiving data from a socket. By default, this function will block, unless the
 *          O_NONBLOCK socket option has been set, or MSG_DONTWAIT is passed as a flag.
 *
 * @param[in]    sock         The socket to receive data from.
 * @param[out]   p_buff       Buffer to hold the data to be read.
 * @param[in]    nbytes       Number of bytes to read. Should not be larger than the size of p_buff.
 * @param[in]    flags        Flags to control receive behavior.
 * @param[out]   p_cliaddr    Socket address that will be set to the client's address.
 * @param[inout] p_addrlen    The size of the p_cliaddr passed. Might be modified by the function.
 *
 * @return The number of bytes that were read, or -1 on error.
 */
ssize_t recvfrom(int         sock,
                 void      * p_buff,
                 size_t      nbytes,
                 int         flags,
                 void      * p_cliaddr,
                 socklen_t * p_addrlen);

/**
 * @brief Function for reading data from a socket. See \ref recv() for details.
 *
 * @param[in]  sock     The socket to receive data from.
 * @param[out] p_buff   Buffer to hold the data to be read.
 * @param[in]  nbytes   Number of bytes to read. Should not be larger than the size of p_buff.
 *
 * @return The number of bytes that were read, or -1 on error.
 */
ssize_t read(int sock, void * p_buff, size_t nbytes);

/**
 * @defgroup fd_set_api API for file descriptor set
 * @ingroup iot_socket
 * @details File descriptor sets are used as input to the select() function for doing I/O
 *          multiplexing. The maximum number of descriptors contained in a set is defined by
 *          FD_SETSIZE.
 *
 * @{
 */
#ifndef FD_ZERO

typedef uint32_t fd_set;
#define FD_ZERO(set)            (*(set) = 0)                   /**< Clear the entire set.                 */
#define FD_SET(fd, set)         (*(set) |= (1u << (fd)))       /**< Set a bit in the set.             */
#define FD_CLR(fd, set)         (*(set) &= ~(1u << (fd)))      /**< Clear a bit in the set.           */
#define FD_ISSET(fd, set)       (*(set) & (1u << (fd)))        /**< Check if a bit in the set is set. */
#define FD_SETSIZE              sizeof(fd_set)                 /**< The max size of a set.            */

#endif
/**@} */

/**
 * @brief Function for waiting for read, write, or exception events on a socket.
 *
 * @details Wait for a set of socket descriptors to be ready for reading, writing, or having
 *          exceptions. The set of socket descriptors is configured before calling this function.
 *          This function will block until any of the descriptors in the set has any of the required
 *          events. This function is mostly useful when using O_NONBLOCK or MSG_DONTWAIT options
 *          to enable async operation.
 *
 * @param[in]    nfds          The highest socket descriptor value contained in the sets.
 * @param[inout] p_readset     The set of descriptors for which to wait for read events. Set to NULL
 *                             if not used.
 * @param[inout] p_writeset    The set of descriptors for which to wait for write events. Set to NULL
 *                             if not used.
 * @param[inout] p_exceptset   The set of descriptors for which to wait for exception events. Set to
 *                             NULL if not used.
 * @param[in]    p_timeout     The timeout to use for select call. Set to NULL if waiting forever.
 *
 * @return The number of ready descriptors contained in the descriptor sets on success, or -1 on error.
 */
int select(int                    nfds,
           fd_set               * p_readset,
           fd_set               * p_writeset,
           fd_set               * p_exceptset,
           const struct timeval * p_timeout);

/**
 * @brief Function for setting socket options for a given socket.
 *
 * @details The options are grouped by level, and the option value should be the expected for the
 *          given option, and the lifetime must be longer than that of the socket.
 *
 * @param[in] sock      The socket for which to set the option.
 * @param[in] level     The level or group to which the option belongs.
 * @param[in] optname   The name of the socket option.
 * @param[in] p_optval  The value to be stored for this option.
 * @param[in] optlen    The size of p_optval.
 *
 * @return 0 on success, or -1 on error.
 */
int setsockopt(int              sock,
               socket_opt_lvl_t level,
               int              optname,
               const void     * p_optval,
               socklen_t        optlen);

/**
 * @brief Function for getting socket options for a given socket.
 *
 * @details The options are grouped by level, and the option value is the value described by the
 *          option name.
 *
 * @param[in]       sock      The socket for which to set the option.
 * @param[in]       level     The level or group to which the option belongs.
 * @param[in]       optname   The name of the socket option.
 * @param[out]      p_optval  Pointer to the storage for the option value.
 * @param[inout]    p_optlen  The size of p_optval. Can be modified to the actual size of p_optval.
 *
 * @return 0 on success, or -1 on error.
 */
int getsockopt(int              sock,
               socket_opt_lvl_t level,
               int              optname,
               void           * p_optval,
               socklen_t      * p_optlen);

/**
 * @brief Function for binding a socket to an address and port.
 *
 * @details The provided address must be supported by the socket protocol family.
 *
 * @param[in] sock      The socket descriptor to bind.
 * @param[in] p_myaddr  The address to bind this socket to.
 * @param[in] addrlen   The size of p_myaddr.
 *
 * @return 0 on success, or -1 on error.
 */
int bind(int sock, const void * p_myaddr, socklen_t addrlen);

/**
 * @brief Function for marking a socket as listenable.
 *
 * @details Once a socket is marked as listenable, it cannot be unmarked. It is important to
 *          consider the backlog parameter, as it will affect how much memory your application will
 *          use in the worst case.
 *
 * @param[in] sock      The socket descriptor on which to set the listening options.
 * @param[in] backlog   The max length of the queue of pending connections. A value of 0 means
 *                      infinite.
 *
 * @return 0 on success, or -1 on error.
 */
int listen(int sock, int backlog);

/**
 * @brief Function for waiting for the next client to connect.
 *
 * @details This function will block if there are no clients attempting to connect.
 *
 * @param[in]  sock         The socket descriptor to use for waiting on client connections.
 * @param[out] p_cliaddr    Socket address that will be set to the client's address.
 * @param[out] p_addrlen    The size of the p_cliaddr passed. Might be modified by the function.
 *
 * @return  A non-negative client descriptor on success, or -1 on error.
 */
int accept(int sock, void * p_cliaddr, socklen_t * p_addrlen);

/**
 * @brief Function for converting a human-readable IP address to a form usable by the socket API.
 *
 * @details This function will convert a string form of addresses and encode it into a byte array.
 *
 * @param[in]  af           Address family. Only AF_INET6 supported.
 * @param[in]  p_src        Null-terminated string containing the address to convert.
 * @param[out] p_dst        Pointer to a struct in6_addr where the address will be stored.
 *
 * @return 1 on success, 0 if src does not contain a valid address, -1 if af is not a valid address
 *         family.
 */
int inet_pton(socket_family_t af, const char * p_src, void * p_dst);

#ifdef __cplusplus
}
#endif

#endif //SOCKET_API_H__

/**@} */