diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/socket/api/socket_api.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/socket/api/socket_api.h | 593 |
1 files changed, 593 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/socket/api/socket_api.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/socket/api/socket_api.h new file mode 100644 index 0000000..37e50d4 --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/socket/api/socket_api.h @@ -0,0 +1,593 @@ +/** + * Copyright (c) 2015 - 2018, 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__ + +/**@} */ |