/** * 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 #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 #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__ /**@} */