ON Semiconductor / mbed-os

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   mbed-TFT-example-NCS36510 mbed-Accelerometer-example-NCS36510 mbed-Accelerometer-example-NCS36510

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/socket_api.h@0:098463de4c5d, 2017-01-25 (annotated)

Committer:
group-onsemi
Date:
Wed Jan 25 20:34:15 2017 +0000
Revision:
0:098463de4c5d
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
group-onsemi 0:098463de4c5d 1 /*
group-onsemi 0:098463de4c5d 2 * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
group-onsemi 0:098463de4c5d 3 *
group-onsemi 0:098463de4c5d 4 * SPDX-License-Identifier: LicenseRef-PBL
group-onsemi 0:098463de4c5d 5 *
group-onsemi 0:098463de4c5d 6 * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
group-onsemi 0:098463de4c5d 7 * You may obtain a copy of the License at
group-onsemi 0:098463de4c5d 8 *
group-onsemi 0:098463de4c5d 9 * https://www.mbed.com/licenses/PBL-1.0
group-onsemi 0:098463de4c5d 10 *
group-onsemi 0:098463de4c5d 11 * See the License for the specific language governing permissions and limitations under the License.
group-onsemi 0:098463de4c5d 12 *
group-onsemi 0:098463de4c5d 13 */
group-onsemi 0:098463de4c5d 14 #ifndef _NS_SOCKET_API_H
group-onsemi 0:098463de4c5d 15 #define _NS_SOCKET_API_H
group-onsemi 0:098463de4c5d 16
group-onsemi 0:098463de4c5d 17 #ifdef __cplusplus
group-onsemi 0:098463de4c5d 18 extern "C" {
group-onsemi 0:098463de4c5d 19 #endif
group-onsemi 0:098463de4c5d 20 /**
group-onsemi 0:098463de4c5d 21 * \file socket_api.h
group-onsemi 0:098463de4c5d 22 * \brief 6LoWPAN Library Socket API
group-onsemi 0:098463de4c5d 23 *
group-onsemi 0:098463de4c5d 24 * \section socket-com Common socket API
group-onsemi 0:098463de4c5d 25 * - socket_open(), A function to open a socket.
group-onsemi 0:098463de4c5d 26 * - socket_close(), A function to close a socket.
group-onsemi 0:098463de4c5d 27 *
group-onsemi 0:098463de4c5d 28 * \section socket-read Socket read API at callback
group-onsemi 0:098463de4c5d 29 * - socket_read(), A function to read received data buffer from a socket.
group-onsemi 0:098463de4c5d 30 * - socket_recvmsg(), A function to read received data buffer from a socket to Posix defined message structure
group-onsemi 0:098463de4c5d 31 * - socket_read_session_address(), A function to read session info for a TCP event.
group-onsemi 0:098463de4c5d 32 *
group-onsemi 0:098463de4c5d 33 * \section socket-tx Socket TX API
group-onsemi 0:098463de4c5d 34 * - socket_send(), A function to write data buffer to a socket.
group-onsemi 0:098463de4c5d 35 * - socket_sendto(), A function to write data to a specific destination in the socket.
group-onsemi 0:098463de4c5d 36 * - socket_senmsg(), A function which support socket_send and socket_sendto functionality which supports ancillary data
group-onsemi 0:098463de4c5d 37 *
group-onsemi 0:098463de4c5d 38 * \section sock-connect TCP socket connection handle
group-onsemi 0:098463de4c5d 39 * - socket_listen(), A function to set the socket to listening mode.
group-onsemi 0:098463de4c5d 40 * - socket_connect(), A function to connect to a remote peer.
group-onsemi 0:098463de4c5d 41 * - socket_shutdown(), A function to shut down a connection.
group-onsemi 0:098463de4c5d 42 *
group-onsemi 0:098463de4c5d 43 * Sockets are a common abstraction model for network communication and are used in most operating systems.
group-onsemi 0:098463de4c5d 44 * 6LoWPAN Library API follows BSD socket API conventions closely with some extensions necessitated
group-onsemi 0:098463de4c5d 45 * by the event-based scheduling model.
group-onsemi 0:098463de4c5d 46 *
group-onsemi 0:098463de4c5d 47 * Library supports the following socket types:
group-onsemi 0:098463de4c5d 48 * | Socket name | Socket description |
group-onsemi 0:098463de4c5d 49 * | :------------: | :----------------------------: |
group-onsemi 0:098463de4c5d 50 * | SOCKET_UDP | UDP socket type |
group-onsemi 0:098463de4c5d 51 * | SOCKET_TCP | TCP socket type |
group-onsemi 0:098463de4c5d 52 * | SOCKET_ICMP | ICMP raw socket type |
group-onsemi 0:098463de4c5d 53 *
group-onsemi 0:098463de4c5d 54 * \section socket-raw ICMP RAW socket instruction
group-onsemi 0:098463de4c5d 55 * An ICMP raw socket can be created with the function socket_open() and the
group-onsemi 0:098463de4c5d 56 * identifier 0xffff. When using ICMP sockets, the minimum packet length is 4
group-onsemi 0:098463de4c5d 57 * bytes which is the 4 bytes of ICMP header. The first byte is for type, second
group-onsemi 0:098463de4c5d 58 * for code and last two are for the checksum that must always be set to zero.
group-onsemi 0:098463de4c5d 59 * The stack will calculate the checksum automatically before transmitting the packet.
group-onsemi 0:098463de4c5d 60 * THe header is followed by the payload if there is any.
group-onsemi 0:098463de4c5d 61 * NOTE: While it is perfectly legal to send an ICMP packet without payload,
group-onsemi 0:098463de4c5d 62 * some packet sniffing softwares might regard such packets as malformed.
group-onsemi 0:098463de4c5d 63 * In such a case, a dummy payload can be attached by providing a socket_sendto()
group-onsemi 0:098463de4c5d 64 * function with a pointer to your desired data buffer.
group-onsemi 0:098463de4c5d 65 * Moreover, the current implementation of the stack allows only certain ICMP types, for example
group-onsemi 0:098463de4c5d 66 * ICMP echo, reply, destination unreachable, router advertisement, router solicitation.
group-onsemi 0:098463de4c5d 67 * It will drop any other unimplemented types. For example, Private experimentation type (200) will
group-onsemi 0:098463de4c5d 68 * be dropped by default.
group-onsemi 0:098463de4c5d 69
group-onsemi 0:098463de4c5d 70 * | ICMP Type | ICMP Code | Checksum | Payload | Notes |
group-onsemi 0:098463de4c5d 71 * | :-------: | :----------: | :-------: | :--------: | :--------------:|
group-onsemi 0:098463de4c5d 72 * | 1 | 1 | 2 | n bytes | Length in bytes |
group-onsemi 0:098463de4c5d 73 * | 0xXX | 0xXX | 0x00 0x00 | n bytes | Transmit |
group-onsemi 0:098463de4c5d 74 * | 0xXX | 0xXX | 0xXX 0xXX | n bytes | Receive |
group-onsemi 0:098463de4c5d 75 *
group-onsemi 0:098463de4c5d 76 * ICMP echo request with 4 bytes of payload (ping6).
group-onsemi 0:098463de4c5d 77 *
group-onsemi 0:098463de4c5d 78 * | ICMP Type | ICMP Code | Checksum | Payload |
group-onsemi 0:098463de4c5d 79 * | :-------: | :----------: | :-------: | :-----------------: |
group-onsemi 0:098463de4c5d 80 * | 0x80 | 0x00 | 0x00 0x00 | 0x00 0x01 0x02 0x03 |
group-onsemi 0:098463de4c5d 81 *
group-onsemi 0:098463de4c5d 82 * ICMP echo response for the message above.
group-onsemi 0:098463de4c5d 83 *
group-onsemi 0:098463de4c5d 84 * | ICMP Type | ICMP Code | Checksum | Payload |
group-onsemi 0:098463de4c5d 85 * | :-------: | :----------: | :-------: | :-----------------: |
group-onsemi 0:098463de4c5d 86 * | 0x81 | 0x00 | 0xXX 0xXX | 0x00 0x01 0x02 0x03 |
group-onsemi 0:098463de4c5d 87 *
group-onsemi 0:098463de4c5d 88 * \section socket-receive Socket receiving
group-onsemi 0:098463de4c5d 89 * When there is data to read from the socket, a receive callback function is called with the event type parameter set to SOCKET_DATA.
group-onsemi 0:098463de4c5d 90 * The application must read the received data with socket_read() or socket_recvmsg() during the callback because the stack will release the data
group-onsemi 0:098463de4c5d 91 * when returning from the receive callback.
group-onsemi 0:098463de4c5d 92 *
group-onsemi 0:098463de4c5d 93 * Socket event has event_type and socket_id fields. The receive callback function must be defined when socket is opened using socket_open() API.
group-onsemi 0:098463de4c5d 94 *
group-onsemi 0:098463de4c5d 95 * All supported socket event types are listed here:
group-onsemi 0:098463de4c5d 96 *
group-onsemi 0:098463de4c5d 97 * | Event Type | Value | Description |
group-onsemi 0:098463de4c5d 98 * | :------------------------: | :---: | :-----------------------------------------------------------------: |
group-onsemi 0:098463de4c5d 99 * | SOCKET_EVENT_MASK | 0xF0 | NC Socket event mask. |
group-onsemi 0:098463de4c5d 100 * | SOCKET_DATA | 0x00 | Data received, read data length available in d_len field. |
group-onsemi 0:098463de4c5d 101 * | SOCKET_BIND_DONE | 0x10 | TCP connection ready. |
group-onsemi 0:098463de4c5d 102 * | SOCKET_TX_FAIL | 0x50 | Socket data send failed. |
group-onsemi 0:098463de4c5d 103 * | SOCKET_CONNECT_CLOSED | 0x60 | TCP connection closed. |
group-onsemi 0:098463de4c5d 104 * | SOCKET_CONNECTION_RESET | 0x70 | TCP connection reset. |
group-onsemi 0:098463de4c5d 105 * | SOCKET_NO_ROUTER | 0x80 | No route available to destination. |
group-onsemi 0:098463de4c5d 106 * | SOCKET_TX_DONE | 0x90 | Last socket TX process done, in TCP, whole TCP process is ready. |
group-onsemi 0:098463de4c5d 107 * | SOCKET_NO_RAM | 0xA0 | No RAM available. |
group-onsemi 0:098463de4c5d 108 *
group-onsemi 0:098463de4c5d 109 *
group-onsemi 0:098463de4c5d 110 * \section socket-tcp How to use TCP sockets:
group-onsemi 0:098463de4c5d 111 *
group-onsemi 0:098463de4c5d 112 * | API | Socket Type | Description |
group-onsemi 0:098463de4c5d 113 * | :---------------------------: | :-----------: | :------------------------------------------------------------: |
group-onsemi 0:098463de4c5d 114 * | socket_open() | Server/Client | Open socket to specific or dynamic port number. |
group-onsemi 0:098463de4c5d 115 * | socket_shutdown() | Client | Shut down opened TCP connection. |
group-onsemi 0:098463de4c5d 116 * | socket_listen() | Server | Set server port to listen state. |
group-onsemi 0:098463de4c5d 117 * | socket_connect() | Client | Connect client socket to specific destination. |
group-onsemi 0:098463de4c5d 118 * | socket_close() | Server/Client | Closes the TCP Socket. |
group-onsemi 0:098463de4c5d 119 * | socket_send() | Client | Send data to session based destination. |
group-onsemi 0:098463de4c5d 120 * | socket_sendto() | Server/Client | Send data to specific destination. |
group-onsemi 0:098463de4c5d 121 * | socket_read_session_address() | Server/Client | Read socket TCP session address and port information. |
group-onsemi 0:098463de4c5d 122 *
group-onsemi 0:098463de4c5d 123 * When the TCP socket is opened it is in closed state. It must be set either to listen or to connect state before it can be used to receive or transmit data.
group-onsemi 0:098463de4c5d 124 *
group-onsemi 0:098463de4c5d 125 * A socket can be set to listen mode with the socket_listen() function. After the call, the socket can accept an incoming connection from a remote host.
group-onsemi 0:098463de4c5d 126 * The listen mode closes the connection automatically after server timeout or when the client or application closes the connection manually by socket_shutdown() function.
group-onsemi 0:098463de4c5d 127 *
group-onsemi 0:098463de4c5d 128 * A TCP socket can be connected to a remote host with socket_connect() with correct arguments. After the function call, a (non-blocking) application must wait for the socket event to confirm the successful state change of the socket.
group-onsemi 0:098463de4c5d 129 * After the successful state change, data can be sent using socket_send() by client and socket_send() by server.
group-onsemi 0:098463de4c5d 130 * The connection can be shut down with socket_shutdown() function or by server timeout.
group-onsemi 0:098463de4c5d 131 *
group-onsemi 0:098463de4c5d 132 * \section socket-udpicmp How to use UDP and RAW socket:
group-onsemi 0:098463de4c5d 133 *
group-onsemi 0:098463de4c5d 134 * A UDP socket is ready to receive and send data immediately after a successful call of socket_open() and a NET_READY event is received.
group-onsemi 0:098463de4c5d 135 * Data can be transmitted with the socket_sendto() function. An ICMP socket works with same function call.
group-onsemi 0:098463de4c5d 136 *
group-onsemi 0:098463de4c5d 137 */
group-onsemi 0:098463de4c5d 138
group-onsemi 0:098463de4c5d 139 #include "ns_address.h"
group-onsemi 0:098463de4c5d 140
group-onsemi 0:098463de4c5d 141 /** \name Protocol IDs used with sockets. */
group-onsemi 0:098463de4c5d 142 ///@{
group-onsemi 0:098463de4c5d 143 /** UDP socket type. */
group-onsemi 0:098463de4c5d 144 #define SOCKET_UDP 17
group-onsemi 0:098463de4c5d 145 /** Normal TCP socket type. */
group-onsemi 0:098463de4c5d 146 #define SOCKET_TCP 6
group-onsemi 0:098463de4c5d 147 /** ICMPv6 raw socket type */
group-onsemi 0:098463de4c5d 148 #define SOCKET_ICMP 32
group-onsemi 0:098463de4c5d 149 /** Raw IPv6 socket type (socket_open identifier is IPv6 protocol number) */
group-onsemi 0:098463de4c5d 150 #define SOCKET_RAW 2
group-onsemi 0:098463de4c5d 151 /** REMOVED Feature in this release socket open return error Local Sockets for Tun interface functionality to APP-APP trough any BUS */
group-onsemi 0:098463de4c5d 152 #define SOCKET_LOCAL 1
group-onsemi 0:098463de4c5d 153 ///@}
group-onsemi 0:098463de4c5d 154
group-onsemi 0:098463de4c5d 155 /** ICMP socket instruction
group-onsemi 0:098463de4c5d 156 *
group-onsemi 0:098463de4c5d 157 * ICMP header is comprised of 4 bytes. The first byte is for type, second for code and
group-onsemi 0:098463de4c5d 158 * the last two are for checksum that must always be zero.
group-onsemi 0:098463de4c5d 159 * The stack will calculate the checksum automatically when sending the packet.
group-onsemi 0:098463de4c5d 160 * The payload comes after the header and it can be of any length. It can also be set to 0.
group-onsemi 0:098463de4c5d 161 *
group-onsemi 0:098463de4c5d 162 * This applies for reading and sending.
group-onsemi 0:098463de4c5d 163 *
group-onsemi 0:098463de4c5d 164 * ICMP TYPE ICMP Code ICMP Checksum (2 bytes) Payload n bytes
group-onsemi 0:098463de4c5d 165 * -------- -------- -------- -------- -------- -------- ....... -------
group-onsemi 0:098463de4c5d 166 * 0xXX 0xXX 0x00 0x00 0xXX 0xXX ...... 0xXX
group-onsemi 0:098463de4c5d 167 *
group-onsemi 0:098463de4c5d 168 * Example data flow for ping:
group-onsemi 0:098463de4c5d 169 *
group-onsemi 0:098463de4c5d 170 * ICMP echo request with 4-bytes payload (Ping6).
group-onsemi 0:098463de4c5d 171 * 0x80, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03
group-onsemi 0:098463de4c5d 172 *
group-onsemi 0:098463de4c5d 173 * ICMP echo response for the message above.
group-onsemi 0:098463de4c5d 174 * 0x81, 0x00, 0xXX, 0xXX, 0x00, 0x01, 0x02, 0x03
group-onsemi 0:098463de4c5d 175 */
group-onsemi 0:098463de4c5d 176
group-onsemi 0:098463de4c5d 177 /*!
group-onsemi 0:098463de4c5d 178 * \struct socket_callback_t
group-onsemi 0:098463de4c5d 179 * \brief Socket Callback function structure type.
group-onsemi 0:098463de4c5d 180 */
group-onsemi 0:098463de4c5d 181
group-onsemi 0:098463de4c5d 182 typedef struct socket_callback_t {
group-onsemi 0:098463de4c5d 183 uint8_t event_type; /**< Socket Callback Event check list below */
group-onsemi 0:098463de4c5d 184 int8_t socket_id; /**< Socket id queue which socket cause call back */
group-onsemi 0:098463de4c5d 185 int8_t interface_id; /**< Network Interface ID where Packet came */
group-onsemi 0:098463de4c5d 186 uint16_t d_len; /**< Data length if event type is SOCKET_DATA */
group-onsemi 0:098463de4c5d 187 uint8_t LINK_LQI; /**< LINK LQI info if interface cuold give */
group-onsemi 0:098463de4c5d 188 } socket_callback_t;
group-onsemi 0:098463de4c5d 189
group-onsemi 0:098463de4c5d 190 /*!
group-onsemi 0:098463de4c5d 191 * \struct ns_msghdr_t
group-onsemi 0:098463de4c5d 192 * \brief Normal IP socket message structure for socket_recvmsg() and socket_sendmsg().
group-onsemi 0:098463de4c5d 193 */
group-onsemi 0:098463de4c5d 194
group-onsemi 0:098463de4c5d 195 typedef struct ns_msghdr {
group-onsemi 0:098463de4c5d 196 void *msg_name; /**< Optional address send use for destination and receive it will be source. MUST be ns_address_t */
group-onsemi 0:098463de4c5d 197 uint_fast16_t msg_namelen; /**< Length of optional address use sizeof(ns_address_t) when msg_name is defined */
group-onsemi 0:098463de4c5d 198 ns_iovec_t *msg_iov; /**< Message data vector list */
group-onsemi 0:098463de4c5d 199 uint_fast16_t msg_iovlen; /**< Data vector count in msg_iov */
group-onsemi 0:098463de4c5d 200 void *msg_control; /**< Ancillary data list of ns_cmsghdr_t pointer */
group-onsemi 0:098463de4c5d 201 uint_fast16_t msg_controllen; /**< Ancillary data length */
group-onsemi 0:098463de4c5d 202 int flags; /**< Flags for received messages */
group-onsemi 0:098463de4c5d 203 } ns_msghdr_t;
group-onsemi 0:098463de4c5d 204
group-onsemi 0:098463de4c5d 205 /*!
group-onsemi 0:098463de4c5d 206 * \struct ns_cmsghdr_t
group-onsemi 0:098463de4c5d 207 * \brief Control messages.
group-onsemi 0:098463de4c5d 208 */
group-onsemi 0:098463de4c5d 209 typedef struct ns_cmsghdr {
group-onsemi 0:098463de4c5d 210 uint16_t cmsg_len; /**< Ancillary data control messages length including cmsghdr */
group-onsemi 0:098463de4c5d 211 uint8_t cmsg_level; /**< Originating protocol level should be SOCKET_IPPROTO_IPV6 */
group-onsemi 0:098463de4c5d 212 uint8_t cmsg_type; /**< Protocol Specific types for example SOCKET_IPV6_PKTINFO, */
group-onsemi 0:098463de4c5d 213 } ns_cmsghdr_t;
group-onsemi 0:098463de4c5d 214
group-onsemi 0:098463de4c5d 215
group-onsemi 0:098463de4c5d 216 /** \name socket_recvmsg() message error flags.
group-onsemi 0:098463de4c5d 217 * \anchor MSG_HEADER_FLAGS
group-onsemi 0:098463de4c5d 218 */
group-onsemi 0:098463de4c5d 219 ///@{
group-onsemi 0:098463de4c5d 220 /** In msg_flags, indicates that given data buffer was smaller than received datagram. Can also be passed as an flag parameter to recvmsg. */
group-onsemi 0:098463de4c5d 221 #define NS_MSG_TRUNC 1
group-onsemi 0:098463de4c5d 222 /** Indicates that given ancillary data buffer was smaller than enabled at socket msg->msg_controllen define proper writed data lengths. */
group-onsemi 0:098463de4c5d 223 #define NS_MSG_CTRUNC 2
group-onsemi 0:098463de4c5d 224 ///@}
group-onsemi 0:098463de4c5d 225 /*!
group-onsemi 0:098463de4c5d 226 * \struct ns_in6_pktinfo_t
group-onsemi 0:098463de4c5d 227 * \brief IPv6 packet info which is used for socket_recvmsg() socket_sendmsg().
group-onsemi 0:098463de4c5d 228 */
group-onsemi 0:098463de4c5d 229 typedef struct ns_in6_pktinfo {
group-onsemi 0:098463de4c5d 230 uint8_t ipi6_addr[16]; /**< src/dst IPv6 address */
group-onsemi 0:098463de4c5d 231 int8_t ipi6_ifindex; /**< send/recv interface index */
group-onsemi 0:098463de4c5d 232 } ns_in6_pktinfo_t;
group-onsemi 0:098463de4c5d 233
group-onsemi 0:098463de4c5d 234 #define CMSG_HEADER_ALIGN sizeof(long)
group-onsemi 0:098463de4c5d 235
group-onsemi 0:098463de4c5d 236 #define CMSG_DATA_ALIGN CMSG_HEADER_ALIGN
group-onsemi 0:098463de4c5d 237
group-onsemi 0:098463de4c5d 238 #ifndef NS_ALIGN_SIZE
group-onsemi 0:098463de4c5d 239 #define NS_ALIGN_SIZE(length, aligment_base) \
group-onsemi 0:098463de4c5d 240 ((length + (aligment_base -1 )) & ~(aligment_base -1))
group-onsemi 0:098463de4c5d 241 #endif
group-onsemi 0:098463de4c5d 242
group-onsemi 0:098463de4c5d 243 /**
group-onsemi 0:098463de4c5d 244 * \brief Parse first control message header from message ancillary data.
group-onsemi 0:098463de4c5d 245 *
group-onsemi 0:098463de4c5d 246 * \param msgh Pointer for socket message.
group-onsemi 0:098463de4c5d 247 *
group-onsemi 0:098463de4c5d 248 * \return Pointer to first control message header , Could be NULL when control_message is undefined.
group-onsemi 0:098463de4c5d 249 */
group-onsemi 0:098463de4c5d 250 #define NS_CMSG_FIRSTHDR(msgh) \
group-onsemi 0:098463de4c5d 251 ((msgh)->msg_controllen >= sizeof(struct ns_cmsghdr) ? \
group-onsemi 0:098463de4c5d 252 (struct ns_cmsghdr *)(msgh)->msg_control : \
group-onsemi 0:098463de4c5d 253 (struct ns_cmsghdr *)NULL )
group-onsemi 0:098463de4c5d 254 /**
group-onsemi 0:098463de4c5d 255 * \brief Parse next control message from message by current control message header.
group-onsemi 0:098463de4c5d 256 *
group-onsemi 0:098463de4c5d 257 * \param msgh Pointer for socket message.
group-onsemi 0:098463de4c5d 258 * \param cmsg Pointer for last parsed control message
group-onsemi 0:098463de4c5d 259 *
group-onsemi 0:098463de4c5d 260 * \return Pointer to Next control message header , Could be NULL when no more control messages data.
group-onsemi 0:098463de4c5d 261 */
group-onsemi 0:098463de4c5d 262
group-onsemi 0:098463de4c5d 263 ns_cmsghdr_t *NS_CMSG_NXTHDR(const ns_msghdr_t *msgh, const ns_cmsghdr_t *cmsg);
group-onsemi 0:098463de4c5d 264
group-onsemi 0:098463de4c5d 265 /**
group-onsemi 0:098463de4c5d 266 * \brief Get Data pointer from control message header.
group-onsemi 0:098463de4c5d 267 *
group-onsemi 0:098463de4c5d 268 * \param cmsg Pointer (ns_cmsghdr_t) for last parsed control message
group-onsemi 0:098463de4c5d 269 *
group-onsemi 0:098463de4c5d 270 * \return Data pointer.
group-onsemi 0:098463de4c5d 271 */
group-onsemi 0:098463de4c5d 272 #define NS_CMSG_DATA(cmsg) \
group-onsemi 0:098463de4c5d 273 ((uint8_t *)(cmsg) + NS_ALIGN_SIZE(sizeof(ns_cmsghdr_t), CMSG_DATA_ALIGN))
group-onsemi 0:098463de4c5d 274
group-onsemi 0:098463de4c5d 275 /**
group-onsemi 0:098463de4c5d 276 * \brief Returns the total space required for a cmsg header plus the specified data, allowing for all padding
group-onsemi 0:098463de4c5d 277 *
group-onsemi 0:098463de4c5d 278 * \param length size of the ancillary data
group-onsemi 0:098463de4c5d 279 *
group-onsemi 0:098463de4c5d 280 * For example, the space required for a SOCKET_IPV6_PKTINFO is NS_CMSG_SPACE(sizeof(ns_in6_pktinfo))
group-onsemi 0:098463de4c5d 281 *
group-onsemi 0:098463de4c5d 282 * \return Total size of CMSG header, data and trailing padding.
group-onsemi 0:098463de4c5d 283 */
group-onsemi 0:098463de4c5d 284 #define NS_CMSG_SPACE(length) \
group-onsemi 0:098463de4c5d 285 (NS_ALIGN_SIZE(sizeof(ns_cmsghdr_t), CMSG_DATA_ALIGN) + NS_ALIGN_SIZE(length, CMSG_HEADER_ALIGN))
group-onsemi 0:098463de4c5d 286
group-onsemi 0:098463de4c5d 287 /**
group-onsemi 0:098463de4c5d 288 * \brief Calculate length to store in cmsg_len with taking into account any necessary alignment.
group-onsemi 0:098463de4c5d 289 *
group-onsemi 0:098463de4c5d 290 * \param length size of the ancillary data
group-onsemi 0:098463de4c5d 291 *
group-onsemi 0:098463de4c5d 292 * For example, cmsg_len for a SOCKET_IPV6_PKTINFO is NS_CMSG_LEN(sizeof(ns_in6_pktinfo))
group-onsemi 0:098463de4c5d 293 *
group-onsemi 0:098463de4c5d 294 * \return Size of CMSG header plus data, without trailing padding.
group-onsemi 0:098463de4c5d 295 */
group-onsemi 0:098463de4c5d 296 #define NS_CMSG_LEN(length) \
group-onsemi 0:098463de4c5d 297 (NS_ALIGN_SIZE(sizeof(ns_cmsghdr_t), CMSG_DATA_ALIGN) + length)
group-onsemi 0:098463de4c5d 298
group-onsemi 0:098463de4c5d 299
group-onsemi 0:098463de4c5d 300 /** IPv6 wildcard address IN_ANY */
group-onsemi 0:098463de4c5d 301 extern const uint8_t ns_in6addr_any[16];
group-onsemi 0:098463de4c5d 302
group-onsemi 0:098463de4c5d 303 /**
group-onsemi 0:098463de4c5d 304 * \brief Create and initialize a socket for communication.
group-onsemi 0:098463de4c5d 305 *
group-onsemi 0:098463de4c5d 306 * \param protocol Defines the protocol to use.
group-onsemi 0:098463de4c5d 307 * \param identifier The socket port. 0 indicates that port is not specified and it will be selected automatically when using the socket.
group-onsemi 0:098463de4c5d 308 * \param passed_fptr A function pointer to a function that is called whenever a data frame is received to this socket.
group-onsemi 0:098463de4c5d 309 *
group-onsemi 0:098463de4c5d 310 * \return 0 or greater on success; Return value is the socket ID.
group-onsemi 0:098463de4c5d 311 * \return -1 on failure.
group-onsemi 0:098463de4c5d 312 * \return -2 on port reserved.
group-onsemi 0:098463de4c5d 313 */
group-onsemi 0:098463de4c5d 314 int8_t socket_open(uint8_t protocol, uint16_t identifier, void (*passed_fptr)(void *));
group-onsemi 0:098463de4c5d 315
group-onsemi 0:098463de4c5d 316 /**
group-onsemi 0:098463de4c5d 317 * \brief A function to close a socket.
group-onsemi 0:098463de4c5d 318 *
group-onsemi 0:098463de4c5d 319 * \param socket ID of the socket to be closed.
group-onsemi 0:098463de4c5d 320 *
group-onsemi 0:098463de4c5d 321 * \return 0 socket closed.
group-onsemi 0:098463de4c5d 322 * \return -1 socket not closed.
group-onsemi 0:098463de4c5d 323 */
group-onsemi 0:098463de4c5d 324 int8_t socket_close(int8_t socket);
group-onsemi 0:098463de4c5d 325
group-onsemi 0:098463de4c5d 326 /**
group-onsemi 0:098463de4c5d 327 * \brief A function to set a socket to listening mode.
group-onsemi 0:098463de4c5d 328 *
group-onsemi 0:098463de4c5d 329 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 330 * \param backlog The pending connections queue size. (Not yet implemented).
group-onsemi 0:098463de4c5d 331 * \return 0 on success.
group-onsemi 0:098463de4c5d 332 * \return -1 on failure.
group-onsemi 0:098463de4c5d 333 */
group-onsemi 0:098463de4c5d 334 int8_t socket_listen(int8_t socket, uint8_t backlog);
group-onsemi 0:098463de4c5d 335
group-onsemi 0:098463de4c5d 336 /**
group-onsemi 0:098463de4c5d 337 * \brief A function to accept a new connection on an socket.
group-onsemi 0:098463de4c5d 338 *
group-onsemi 0:098463de4c5d 339 * NOT YET IMPLEMENTED - PLACEHOLDER FOR FUTURE TCP CHANGES
group-onsemi 0:098463de4c5d 340 *
group-onsemi 0:098463de4c5d 341 * \param socket_id The socket ID of the listening socket.
group-onsemi 0:098463de4c5d 342 * \param addr Either NULL pointer or pointer to structure where the remote address of the connecting host is copied.
group-onsemi 0:098463de4c5d 343 * \param passed_fptr A function pointer to a function that is called whenever a data frame is received to the new socket.
group-onsemi 0:098463de4c5d 344 * \return 0 or greater on success; return value is the new socket ID.
group-onsemi 0:098463de4c5d 345 * \return -1 on failure.
group-onsemi 0:098463de4c5d 346 */
group-onsemi 0:098463de4c5d 347 int8_t socket_accept(int8_t socket_id, ns_address_t *addr, void (*passed_fptr)(void *));
group-onsemi 0:098463de4c5d 348
group-onsemi 0:098463de4c5d 349 /**
group-onsemi 0:098463de4c5d 350 * \brief A function to connect to remote peer (TCP).
group-onsemi 0:098463de4c5d 351 *
group-onsemi 0:098463de4c5d 352 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 353 * \param address The address of a remote peer.
group-onsemi 0:098463de4c5d 354 * \deprecated \param randomly_take_src_number Ignored - random local port is always chosen if not yet bound
group-onsemi 0:098463de4c5d 355 *
group-onsemi 0:098463de4c5d 356 * \return 0 on success.
group-onsemi 0:098463de4c5d 357 * \return -1 in case of an invalid socket ID or parameter.
group-onsemi 0:098463de4c5d 358 * \return -2 if memory allocation fails.
group-onsemi 0:098463de4c5d 359 * \return -3 if the socket is in listening state.
group-onsemi 0:098463de4c5d 360 * \return -4 if the socket is already connected.
group-onsemi 0:098463de4c5d 361 * \return -5 connect is not supported on this type of socket.
group-onsemi 0:098463de4c5d 362 * \return -6 if the TCP session state is wrong.
group-onsemi 0:098463de4c5d 363 * \return -7 if the source address selection fails.
group-onsemi 0:098463de4c5d 364 */
group-onsemi 0:098463de4c5d 365 int8_t socket_connect(int8_t socket, ns_address_t *address, uint8_t randomly_take_src_number);
group-onsemi 0:098463de4c5d 366
group-onsemi 0:098463de4c5d 367 /**
group-onsemi 0:098463de4c5d 368 * \brief Bind socket to address.
group-onsemi 0:098463de4c5d 369 *
group-onsemi 0:098463de4c5d 370 * Used by the application to bind a socket to a port and/or an address. Binding can
group-onsemi 0:098463de4c5d 371 * be done only once. The port or address cannot be changed after binding.
group-onsemi 0:098463de4c5d 372 *
group-onsemi 0:098463de4c5d 373 * \param socket Socket ID of the socket to bind.
group-onsemi 0:098463de4c5d 374 * \param address Address structure containing the port and address to bind.
group-onsemi 0:098463de4c5d 375 *
group-onsemi 0:098463de4c5d 376 * \return 0 on success.
group-onsemi 0:098463de4c5d 377 * \return -1 if the given address is NULL.
group-onsemi 0:098463de4c5d 378 * \return -2 if the port is already bound to another socket.
group-onsemi 0:098463de4c5d 379 * \return -3 if address is not us.
group-onsemi 0:098463de4c5d 380 * \return -4 if the socket is already bound.
group-onsemi 0:098463de4c5d 381 * \return -5 bind is not supported on this type of socket.
group-onsemi 0:098463de4c5d 382 *
group-onsemi 0:098463de4c5d 383 */
group-onsemi 0:098463de4c5d 384 int8_t socket_bind(int8_t socket, const ns_address_t *address);
group-onsemi 0:098463de4c5d 385
group-onsemi 0:098463de4c5d 386 /**
group-onsemi 0:098463de4c5d 387 * \brief Bind a local address to a socket based on the destination address and
group-onsemi 0:098463de4c5d 388 * the address selection preferences.
group-onsemi 0:098463de4c5d 389 * Binding happens to the same address that socket_connect() would bind to.
group-onsemi 0:098463de4c5d 390 * Reference: RFC5014 IPv6 Socket API for Source Address Selection.
group-onsemi 0:098463de4c5d 391 *
group-onsemi 0:098463de4c5d 392 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 393 * \param dst_address The destination address to which the socket wants to communicate.
group-onsemi 0:098463de4c5d 394 *
group-onsemi 0:098463de4c5d 395 * \return 0 on success.
group-onsemi 0:098463de4c5d 396 * \return -1 if the given address is NULL or socket ID is invalid.
group-onsemi 0:098463de4c5d 397 * \return -2 if the memory allocation failed.
group-onsemi 0:098463de4c5d 398 * \return -3 if the socket is already bound to address.
group-onsemi 0:098463de4c5d 399 * \return -4 if the interface cannot be found.
group-onsemi 0:098463de4c5d 400 * \return -5 if the source address selection fails.
group-onsemi 0:098463de4c5d 401 * \return -6 bind2addrsel is not supported on this type of socket.
group-onsemi 0:098463de4c5d 402 */
group-onsemi 0:098463de4c5d 403 int8_t socket_bind2addrsel(int8_t socket, const ns_address_t *dst_address);
group-onsemi 0:098463de4c5d 404
group-onsemi 0:098463de4c5d 405 /**
group-onsemi 0:098463de4c5d 406 * Options for the socket_shutdown() parameter 'how'.
group-onsemi 0:098463de4c5d 407 */
group-onsemi 0:098463de4c5d 408 #define SOCKET_SHUT_RD 0 ///< Disables further receive operations.
group-onsemi 0:098463de4c5d 409 #define SOCKET_SHUT_WR 1 ///< Disables further send operations.
group-onsemi 0:098463de4c5d 410 #define SOCKET_SHUT_RDWR 2 ///< Disables further send and receive operations.
group-onsemi 0:098463de4c5d 411
group-onsemi 0:098463de4c5d 412 /**
group-onsemi 0:098463de4c5d 413 * \brief A function to shut down a connection.
group-onsemi 0:098463de4c5d 414 *
group-onsemi 0:098463de4c5d 415 * \param socket The ID of the socket to be shut down.
group-onsemi 0:098463de4c5d 416 * \param how How socket is to be shut down, one of SOCKET_SHUT_XX.
group-onsemi 0:098463de4c5d 417 *
group-onsemi 0:098463de4c5d 418 * \return 0 on success.
group-onsemi 0:098463de4c5d 419 * \return -1 if the given socket ID is not found, if the socket type is wrong or TCP layer returns a failure.
group-onsemi 0:098463de4c5d 420 * \return -2 if no active TCP session was found.
group-onsemi 0:098463de4c5d 421 */
group-onsemi 0:098463de4c5d 422 int8_t socket_shutdown(int8_t socket, uint8_t how);
group-onsemi 0:098463de4c5d 423
group-onsemi 0:098463de4c5d 424 /**
group-onsemi 0:098463de4c5d 425 * \brief Send data via a connected TCP socket by client.
group-onsemi 0:098463de4c5d 426 *
group-onsemi 0:098463de4c5d 427 * Note: The socket connection must be ready before using this function.
group-onsemi 0:098463de4c5d 428 * The stack uses automatically the address of the remote connected host as the destination address for the packet.
group-onsemi 0:098463de4c5d 429 *
group-onsemi 0:098463de4c5d 430 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 431 * \param buffer A pointer to data.
group-onsemi 0:098463de4c5d 432 * \param length Data length.
group-onsemi 0:098463de4c5d 433 *
group-onsemi 0:098463de4c5d 434 * \return 0 done
group-onsemi 0:098463de4c5d 435 * \return -1 Invalid socket ID.
group-onsemi 0:098463de4c5d 436 * \return -2 Socket memory allocation fail.
group-onsemi 0:098463de4c5d 437 * \return -3 TCP state not established or address scope not defined .
group-onsemi 0:098463de4c5d 438 * \return -4 Socket TX process busy or unknown interface.
group-onsemi 0:098463de4c5d 439 * \return -5 Socket not connected
group-onsemi 0:098463de4c5d 440 * \return -6 Packet too short (ICMP raw socket error).
group-onsemi 0:098463de4c5d 441 */
group-onsemi 0:098463de4c5d 442 int8_t socket_send(int8_t socket, uint8_t *buffer, uint16_t length);
group-onsemi 0:098463de4c5d 443
group-onsemi 0:098463de4c5d 444 /**
group-onsemi 0:098463de4c5d 445 * \brief A function to read received data buffer from a socket.
group-onsemi 0:098463de4c5d 446 *
group-onsemi 0:098463de4c5d 447 * Used by the application to get data from a socket. This method must be called once
group-onsemi 0:098463de4c5d 448 * from a socket callback when handling event SOCKET_DATA. If the received data does not fit
group-onsemi 0:098463de4c5d 449 * in the buffer provided the excess data bytes are discarded.
group-onsemi 0:098463de4c5d 450 *
group-onsemi 0:098463de4c5d 451 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 452 * \param src_addr A pointer to a structure where the sender's address is stored.
group-onsemi 0:098463de4c5d 453 * \param buffer A pointer to an array where the read data is written to.
group-onsemi 0:098463de4c5d 454 * \param length The maximum length of the allocated buffer.
group-onsemi 0:098463de4c5d 455 *
group-onsemi 0:098463de4c5d 456 * \return greater than 0 indicates the length of the data copied to buffer.
group-onsemi 0:098463de4c5d 457 * \return 0 if no data is available to read.
group-onsemi 0:098463de4c5d 458 * \return -1 invalid input parameters.
group-onsemi 0:098463de4c5d 459 */
group-onsemi 0:098463de4c5d 460 int16_t socket_read(int8_t socket, ns_address_t *src_addr, uint8_t *buffer, uint16_t length);
group-onsemi 0:098463de4c5d 461
group-onsemi 0:098463de4c5d 462 /**
group-onsemi 0:098463de4c5d 463 * \brief A function to read received message with ancillary data from a socket.
group-onsemi 0:098463de4c5d 464 *
group-onsemi 0:098463de4c5d 465 * Used by the application to get data from a socket. This method must be called once
group-onsemi 0:098463de4c5d 466 * from a socket callback when handling event SOCKET_DATA. If the received data does not fit
group-onsemi 0:098463de4c5d 467 * in the buffer provided the excess data bytes are discarded.
group-onsemi 0:098463de4c5d 468 *
group-onsemi 0:098463de4c5d 469 * Ancillary data must request by socket_setsockopt().
group-onsemi 0:098463de4c5d 470 *
group-onsemi 0:098463de4c5d 471 * msg->msg_controllen is updated to indicate actual length of ancillary data output
group-onsemi 0:098463de4c5d 472 *
group-onsemi 0:098463de4c5d 473 * The returned length is normally the length of data actually written to the buffer; if
group-onsemi 0:098463de4c5d 474 * NS_MSG_TRUNC is set in flags, then for non-stream sockets, the actual datagram length is
group-onsemi 0:098463de4c5d 475 * returned instead, which may be larger than the buffer size.
group-onsemi 0:098463de4c5d 476 *
group-onsemi 0:098463de4c5d 477 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 478 * \param msg A pointer to a structure where messages is stored with or without ancillary data
group-onsemi 0:098463de4c5d 479 * \param flags A flags for message read.
group-onsemi 0:098463de4c5d 480 *
group-onsemi 0:098463de4c5d 481 * \return greater than 0 indicates the length of the data.
group-onsemi 0:098463de4c5d 482 * \return 0 if no data is available to read.
group-onsemi 0:098463de4c5d 483 * \return -1 invalid input parameters.
group-onsemi 0:098463de4c5d 484 */
group-onsemi 0:098463de4c5d 485 int16_t socket_recvmsg(int8_t socket, ns_msghdr_t *msg, int flags);
group-onsemi 0:098463de4c5d 486
group-onsemi 0:098463de4c5d 487 /**
group-onsemi 0:098463de4c5d 488 * \brief A function to send UDP, TCP or raw ICMP data via the socket.
group-onsemi 0:098463de4c5d 489 *
group-onsemi 0:098463de4c5d 490 * Used by the application to send data.
group-onsemi 0:098463de4c5d 491 *
group-onsemi 0:098463de4c5d 492 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 493 * \param address A pointer to the destination address information.
group-onsemi 0:098463de4c5d 494 * \param buffer A pointer to data to be sent.
group-onsemi 0:098463de4c5d 495 * \param length Length of the data to be sent.
group-onsemi 0:098463de4c5d 496 *
group-onsemi 0:098463de4c5d 497 * \return 0 on success.
group-onsemi 0:098463de4c5d 498 * \return -1 Invalid socket ID.
group-onsemi 0:098463de4c5d 499 * \return -2 Socket memory allocation fail.
group-onsemi 0:098463de4c5d 500 * \return -3 TCP state not established or address scope not defined .
group-onsemi 0:098463de4c5d 501 * \return -4 Socket TX process busy or unknown interface.
group-onsemi 0:098463de4c5d 502 * \return -5 Socket not connected
group-onsemi 0:098463de4c5d 503 * \return -6 Packet too short (ICMP raw socket error).
group-onsemi 0:098463de4c5d 504 */
group-onsemi 0:098463de4c5d 505 int8_t socket_sendto(int8_t socket, ns_address_t *address, uint8_t *buffer, uint16_t length);
group-onsemi 0:098463de4c5d 506
group-onsemi 0:098463de4c5d 507 /**
group-onsemi 0:098463de4c5d 508 * \brief A function to send UDP, TCP or raw ICMP data via the socket with or without ancillary data or destination address.
group-onsemi 0:098463de4c5d 509 *
group-onsemi 0:098463de4c5d 510 * Used by the application to send data message header support also vector list socket_send() and socket_sendto() use this functionality internally.
group-onsemi 0:098463de4c5d 511 *
group-onsemi 0:098463de4c5d 512 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 513 * \param msg A pointer to the Message header which include address, payload and ancillary data.
group-onsemi 0:098463de4c5d 514 * \param flags A flags for message send for future usage (not supported yet)
group-onsemi 0:098463de4c5d 515 *
group-onsemi 0:098463de4c5d 516 * Messages destination address is defined by msg->msg_name which must be ns_address_t. If msg->msg_nme is NULL socket select connected address
group-onsemi 0:098463de4c5d 517 *
group-onsemi 0:098463de4c5d 518 * Messages payload and length is defined msg->msg_iov and msg->msg_iovlen. API support to send multiple data vector.
group-onsemi 0:098463de4c5d 519 *
group-onsemi 0:098463de4c5d 520 * Supported ancillary data for send defined by msg->msg_control and msg->msg_controllen.
group-onsemi 0:098463de4c5d 521 *
group-onsemi 0:098463de4c5d 522 * msg->flags and flags is ignored
group-onsemi 0:098463de4c5d 523 *
group-onsemi 0:098463de4c5d 524 * \return 0 on success.
group-onsemi 0:098463de4c5d 525 * \return -1 Invalid socket ID or message structure.
group-onsemi 0:098463de4c5d 526 * \return -2 Socket memory allocation fail.
group-onsemi 0:098463de4c5d 527 * \return -3 TCP state not established or address scope not defined .
group-onsemi 0:098463de4c5d 528 * \return -4 Socket TX process busy or unknown interface.
group-onsemi 0:098463de4c5d 529 * \return -5 Socket not connected
group-onsemi 0:098463de4c5d 530 * \return -6 Packet too short (ICMP raw socket error).
group-onsemi 0:098463de4c5d 531 */
group-onsemi 0:098463de4c5d 532 int8_t socket_sendmsg(int8_t socket, const ns_msghdr_t *msg, int flags);
group-onsemi 0:098463de4c5d 533
group-onsemi 0:098463de4c5d 534 /**
group-onsemi 0:098463de4c5d 535 * \brief A function to read session info for TCP event.
group-onsemi 0:098463de4c5d 536 *
group-onsemi 0:098463de4c5d 537 *
group-onsemi 0:098463de4c5d 538 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 539 * \param address A pointer to the address structure where the session address information is read to.
group-onsemi 0:098463de4c5d 540 *
group-onsemi 0:098463de4c5d 541 * \return 0 on success.
group-onsemi 0:098463de4c5d 542 * \return -1 if no socket is found or TCP is not compiled into this project.
group-onsemi 0:098463de4c5d 543 * \return -2 if no session information is found.
group-onsemi 0:098463de4c5d 544 *
group-onsemi 0:098463de4c5d 545 * Note: This function should be called only at socket callback when the socket event is SOCKET_BIND_DONE or SOCKET_TX_DONE.
group-onsemi 0:098463de4c5d 546 * The following sections introduce those functions.
group-onsemi 0:098463de4c5d 547 */
group-onsemi 0:098463de4c5d 548 int8_t socket_read_session_address(int8_t socket, ns_address_t *address);
group-onsemi 0:098463de4c5d 549
group-onsemi 0:098463de4c5d 550
group-onsemi 0:098463de4c5d 551 /** \name Flags for SOCKET_IPV6_ADDR_PREFERENCES - opposites 16 bits apart. */
group-onsemi 0:098463de4c5d 552 ///@{
group-onsemi 0:098463de4c5d 553 #define SOCKET_IPV6_PREFER_SRC_TMP 0x00000001 /**< Prefer temporary address (RFC 4941); default. */
group-onsemi 0:098463de4c5d 554 #define SOCKET_IPV6_PREFER_SRC_PUBLIC 0x00010000 /**< Prefer public address (RFC 4941). */
group-onsemi 0:098463de4c5d 555 #define SOCKET_IPV6_PREFER_SRC_6LOWPAN_SHORT 0x00000100 /**< Prefer 6LoWPAN short address. */
group-onsemi 0:098463de4c5d 556 #define SOCKET_IPV6_PREFER_SRC_6LOWPAN_LONG 0x01000000 /**< Prefer 6LoWPAN long address. */
group-onsemi 0:098463de4c5d 557 ///@}
group-onsemi 0:098463de4c5d 558
group-onsemi 0:098463de4c5d 559 /** \name Options for SOCKET_IPV6_ADDRESS_SELECT. */
group-onsemi 0:098463de4c5d 560 ///@{
group-onsemi 0:098463de4c5d 561 #define SOCKET_SRC_ADDRESS_MODE_PRIMARY 0 /**< Default value always. */
group-onsemi 0:098463de4c5d 562 #define SOCKET_SRC_ADDRESS_MODE_SECONDARY 1 /**< This mode typically selects the secondary address. */
group-onsemi 0:098463de4c5d 563 ///@}
group-onsemi 0:098463de4c5d 564
group-onsemi 0:098463de4c5d 565 /** \name Protocol levels used for socket_setsockopt. */
group-onsemi 0:098463de4c5d 566 ///@{
group-onsemi 0:098463de4c5d 567 #define SOCKET_IPPROTO_IPV6 41 /**< IPv6. */
group-onsemi 0:098463de4c5d 568 ///@}
group-onsemi 0:098463de4c5d 569
group-onsemi 0:098463de4c5d 570 /** \name Option names for protocol level SOCKET_IPPROTO_IPV6.
group-onsemi 0:098463de4c5d 571 * \anchor OPTNAMES_IPV6
group-onsemi 0:098463de4c5d 572 */
group-onsemi 0:098463de4c5d 573 ///@{
group-onsemi 0:098463de4c5d 574 /** Specify traffic class for outgoing packets, as int16_t (RFC 3542 S6.5 says int); valid values 0-255, or -1 for system default. */
group-onsemi 0:098463de4c5d 575 #define SOCKET_IPV6_TCLASS 1
group-onsemi 0:098463de4c5d 576 /** Specify hop limit for outgoing unicast packets, as int16_t (RFC 3493 S5.1 says int); valid values 0-255, or -1 for system default. */
group-onsemi 0:098463de4c5d 577 #define SOCKET_IPV6_UNICAST_HOPS 2
group-onsemi 0:098463de4c5d 578 /** Specify hop limit for outgoing multicast packets, as int16_t (RFC 3493 S5.2 says int); valid values 0-255, or -1 for system default. */
group-onsemi 0:098463de4c5d 579 #define SOCKET_IPV6_MULTICAST_HOPS 3
group-onsemi 0:098463de4c5d 580 /** Specify source address preferences, as uint32_t - see RFC 5014; valid values combinations of SOCKET_IPV6_PREFER_xxx flags. */
group-onsemi 0:098463de4c5d 581 #define SOCKET_IPV6_ADDR_PREFERENCES 4
group-onsemi 0:098463de4c5d 582 /** Specify PMTU preference, as int8_t (RFC 3542 S11.1 says int); valid values -1 (PMTUD for unicast, default), 0 (PMTUD always), 1 (PMTUD off). */
group-onsemi 0:098463de4c5d 583 #define SOCKET_IPV6_USE_MIN_MTU 5
group-onsemi 0:098463de4c5d 584 /** Specify not to fragment datagrams, as int8_t (RFC 3542 S11.2 says int); valid values 0 (fragment to path MTU, default), 1 (no fragmentation, TX fails if bigger than outgoing interface MTU). */
group-onsemi 0:098463de4c5d 585 #define SOCKET_IPV6_DONTFRAG 6
group-onsemi 0:098463de4c5d 586 /** Specify flow label for outgoing packets, as int32_t; valid values 0-0xfffff, or -1 for system default, or -2 to always autogenerate */
group-onsemi 0:098463de4c5d 587 #define SOCKET_IPV6_FLOW_LABEL 7
group-onsemi 0:098463de4c5d 588 /** Hop limit control for socket_sendmsg() and indicate for hop limit socket_recmsg(), as int16_t; valid values 0-255, -1 for default for outgoing packet */
group-onsemi 0:098463de4c5d 589 #define SOCKET_IPV6_HOPLIMIT 8
group-onsemi 0:098463de4c5d 590 /** Specify control messages packet info for send and receive as ns_in6_pktinfo_t socket_sendmsg() it define source address and outgoing interface. socket_recvmsg() it define messages destination address and arrival interface. Reference at RFC3542*/
group-onsemi 0:098463de4c5d 591 #define SOCKET_IPV6_PKTINFO 9
group-onsemi 0:098463de4c5d 592
group-onsemi 0:098463de4c5d 593 /** Specify socket_recvmsg() ancillary data request state for Packet info (destination address and interface id), as bool; valid values true write enabled, false write disabled */
group-onsemi 0:098463de4c5d 594 #define SOCKET_IPV6_RECVPKTINFO 10
group-onsemi 0:098463de4c5d 595 /** Specify socket_recvmsg() ancillary data request state for receive messages hop-limit, as bool; valid values true write enabled, false information write disabled */
group-onsemi 0:098463de4c5d 596 #define SOCKET_IPV6_RECVHOPLIMIT 11
group-onsemi 0:098463de4c5d 597 /** Specify socket_recvmsg() ancillary data request state for receive messages traffic class, as bool; valid values true write enabled, false information write disabled */
group-onsemi 0:098463de4c5d 598 #define SOCKET_IPV6_RECVTCLASS 12
group-onsemi 0:098463de4c5d 599
group-onsemi 0:098463de4c5d 600 #define SOCKET_BROADCAST_PAN 0xfc /**< Internal use - transmit with IEEE 802.15.4 broadcast PAN ID */
group-onsemi 0:098463de4c5d 601 #define SOCKET_LINK_LAYER_SECURITY 0xfd /**< Not standard enable or disable socket security at link layer (For 802.15.4). */
group-onsemi 0:098463de4c5d 602 #define SOCKET_INTERFACE_SELECT 0xfe /**< Not standard socket interface ID. */
group-onsemi 0:098463de4c5d 603 #define SOCKET_IPV6_ADDRESS_SELECT 0xff /**< Deprecated - use SOCKET_IPV6_ADDR_PREFERENCES instead. */
group-onsemi 0:098463de4c5d 604
group-onsemi 0:098463de4c5d 605 /** Socket options summary
group-onsemi 0:098463de4c5d 606 *
group-onsemi 0:098463de4c5d 607 * | opt_name / cmsg_type | Data type | set/getsockopt | sendmsg | recvmsg |
group-onsemi 0:098463de4c5d 608 * | :--------------------------: | :--------------: | :-------------: | :-----: | :-------------------------------: |
group-onsemi 0:098463de4c5d 609 * | SOCKET_IPV6_TCLASS | int16_t | Yes | Yes | If enabled with RECVTCLASS |
group-onsemi 0:098463de4c5d 610 * | SOCKET_IPV6_UNICAST_HOPS | int16_t | Yes | No | No |
group-onsemi 0:098463de4c5d 611 * | SOCKET_IPV6_MULTICAST_HOPS | int16_t | Yes | No | No |
group-onsemi 0:098463de4c5d 612 * | SOCKET_IPV6_ADDR_PREFERENCES | int | Yes | No | No |
group-onsemi 0:098463de4c5d 613 * | SOCKET_IPV6_USE_MIN_MTU | int8_t | Yes | Yes | No |
group-onsemi 0:098463de4c5d 614 * | SOCKET_IPV6_DONTFRAG | int8_t | Yes | Yes | No |
group-onsemi 0:098463de4c5d 615 * | SOCKET_IPV6_FLOW_LABEL | int32_t | Yes | No | No |
group-onsemi 0:098463de4c5d 616 * | SOCKET_IPV6_HOPLIMIT | int16_t | No | Yes | If enabled with RECVHOPLIMIT |
group-onsemi 0:098463de4c5d 617 * | SOCKET_IPV6_PKTINFO | ns_in6_pktinfo_t | No | Yes | If enabled with RECVPKTINFO |
group-onsemi 0:098463de4c5d 618 * | SOCKET_IPV6_RECVPKTINFO | bool | Yes | No | No |
group-onsemi 0:098463de4c5d 619 * | SOCKET_IPV6_RECVHOPLIMIT | bool | Yes | No | No |
group-onsemi 0:098463de4c5d 620 * | SOCKET_IPV6_RECVTCLASS | bool | Yes | No | No |
group-onsemi 0:098463de4c5d 621 * | SOCKET_BROADCAST_PAN | int8_t | Yes | No | No |
group-onsemi 0:098463de4c5d 622 * | SOCKET_LINK_LAYER_SECURITY | int8_t | Yes | No | No |
group-onsemi 0:098463de4c5d 623 * | SOCKET_INTERFACE_SELECT | int8_t | Yes | No | No |
group-onsemi 0:098463de4c5d 624 *
group-onsemi 0:098463de4c5d 625 *
group-onsemi 0:098463de4c5d 626 */
group-onsemi 0:098463de4c5d 627
group-onsemi 0:098463de4c5d 628 ///@}
group-onsemi 0:098463de4c5d 629
group-onsemi 0:098463de4c5d 630 /**
group-onsemi 0:098463de4c5d 631 * \brief Set an option for a socket
group-onsemi 0:098463de4c5d 632 *
group-onsemi 0:098463de4c5d 633 * Used to specify miscellaneous options for a socket. Supported levels and
group-onsemi 0:098463de4c5d 634 * names defined above.
group-onsemi 0:098463de4c5d 635 *
group-onsemi 0:098463de4c5d 636 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 637 * \param level The protocol level.
group-onsemi 0:098463de4c5d 638 * \param opt_name The option name (interpretation depends on level). See \ref OPTNAMES_IPV6.
group-onsemi 0:098463de4c5d 639 * \param opt_value A pointer to value for the specified option.
group-onsemi 0:098463de4c5d 640 * \param opt_len Size of the data pointed to by the value.
group-onsemi 0:098463de4c5d 641 *
group-onsemi 0:098463de4c5d 642 * \return 0 on success.
group-onsemi 0:098463de4c5d 643 * \return -1 invalid socket ID.
group-onsemi 0:098463de4c5d 644 * \return -2 invalid/unsupported option.
group-onsemi 0:098463de4c5d 645 * \return -3 invalid option value.
group-onsemi 0:098463de4c5d 646 */
group-onsemi 0:098463de4c5d 647 int8_t socket_setsockopt(int8_t socket, uint8_t level, uint8_t opt_name, const void *opt_value, uint16_t opt_len);
group-onsemi 0:098463de4c5d 648
group-onsemi 0:098463de4c5d 649 /**
group-onsemi 0:098463de4c5d 650 * \brief Get an option for a socket.
group-onsemi 0:098463de4c5d 651 *
group-onsemi 0:098463de4c5d 652 * Used to read miscellaneous options for a socket. Supported levels and
group-onsemi 0:098463de4c5d 653 * names defined above. If the buffer is smaller than the option, the output
group-onsemi 0:098463de4c5d 654 * is silently truncated; otherwise opt_len is modified to indicate the actual
group-onsemi 0:098463de4c5d 655 * length.
group-onsemi 0:098463de4c5d 656 *
group-onsemi 0:098463de4c5d 657 * \param socket The socket ID.
group-onsemi 0:098463de4c5d 658 * \param level The protocol level.
group-onsemi 0:098463de4c5d 659 * \param opt_name The option name (interpretation depends on level). See \ref OPTNAMES_IPV6.
group-onsemi 0:098463de4c5d 660 * \param opt_value A pointer to output buffer.
group-onsemi 0:098463de4c5d 661 * \param opt_len A pointer to length of output buffer; updated on exit.
group-onsemi 0:098463de4c5d 662 *
group-onsemi 0:098463de4c5d 663 * \return 0 on success.
group-onsemi 0:098463de4c5d 664 * \return -1 invalid socket ID.
group-onsemi 0:098463de4c5d 665 * \return -2 invalid/unsupported option.
group-onsemi 0:098463de4c5d 666 */
group-onsemi 0:098463de4c5d 667 int8_t socket_getsockopt(int8_t socket, uint8_t level, uint8_t opt_name, void *opt_value, uint16_t *opt_len);
group-onsemi 0:098463de4c5d 668
group-onsemi 0:098463de4c5d 669 #ifdef __cplusplus
group-onsemi 0:098463de4c5d 670 }
group-onsemi 0:098463de4c5d 671 #endif
group-onsemi 0:098463de4c5d 672 #endif /*_NS_SOCKET_H*/