Mistake on this page?
Report an issue in GitHub or email us
nsapi_types.h
1 
2 /** \addtogroup netsocket */
3 /** @{*/
4 /* nsapi.h - The network socket API
5  * Copyright (c) 2015 ARM Limited
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 
21 #ifndef NSAPI_TYPES_H
22 #define NSAPI_TYPES_H
23 
24 #include <stdint.h>
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 
31 /*
32  * The Type of Service provides an indication of the abstract
33  * parameters of the quality of service desired. These parameters are
34  * to be used to guide the selection of the actual service parameters
35  * when transmitting a datagram through a particular network. Several
36  * networks offer service precedence, which somehow treats high
37  * precedence traffic as more important than other traffic (generally
38  * by accepting only traffic above a certain precedence at time of high
39  * load). The major choice is a three way tradeoff between low-delay,
40  * high-reliability, and high-throughput.
41  * The use of the Delay, Throughput, and Reliability indications may
42  * increase the cost (in some sense) of the service. In many networks
43  * better performance for one of these parameters is coupled with worse
44  * performance on another. Except for very unusual cases at most two
45  * of these three indications should be set.
46  */
47 #define NSAPI_IPTOS_TOS_MASK 0x1E
48 #define NSAPI_IPTOS_TOS(tos) ((tos) & IPTOS_TOS_MASK)
49 #define NSAPI_IPTOS_LOWDELAY 0x10
50 #define NSAPI_IPTOS_THROUGHPUT 0x08
51 #define NSAPI_IPTOS_RELIABILITY 0x04
52 #define NSAPI_IPTOS_LOWCOST 0x02
53 #define NSAPI_IPTOS_MINCOST IPTOS_LOWCOST
54 
55 /*
56  * The Network Control precedence designation is intended to be used
57  * within a network only. The actual use and control of that
58  * designation is up to each network. The Internetwork Control
59  * designation is intended for use by gateway control originators only.
60  * If the actual use of these precedence designations is of concern to
61  * a particular network, it is the responsibility of that network to
62  * control the access to, and use of, those precedence designations.
63  */
64 #define NSAPI_IPTOS_PREC_MASK 0xe0
65 #define NSAPI_IPTOS_PREC(tos) ((tos) & IPTOS_PREC_MASK)
66 #define NSAPI_IPTOS_PREC_NETCONTROL 0xe0
67 #define NSAPI_IPTOS_PREC_INTERNETCONTROL 0xc0
68 #define NSAPI_IPTOS_PREC_CRITIC_ECP 0xa0
69 #define NSAPI_IPTOS_PREC_FLASHOVERRIDE 0x80
70 #define NSAPI_IPTOS_PREC_FLASH 0x60
71 #define NSAPI_IPTOS_PREC_IMMEDIATE 0x40
72 #define NSAPI_IPTOS_PREC_PRIORITY 0x20
73 #define NSAPI_IPTOS_PREC_ROUTINE 0x00
74 
75 /** Enum of standardized error codes
76  *
77  * Valid error codes have negative values and may
78  * be returned by any network operation.
79  *
80  * @enum nsapi_error
81  */
83  NSAPI_ERROR_OK = 0, /*!< no error */
84  NSAPI_ERROR_WOULD_BLOCK = -3001, /*!< no data is not available but call is non-blocking */
85  NSAPI_ERROR_UNSUPPORTED = -3002, /*!< unsupported functionality */
86  NSAPI_ERROR_PARAMETER = -3003, /*!< invalid configuration */
87  NSAPI_ERROR_NO_CONNECTION = -3004, /*!< not connected to a network */
88  NSAPI_ERROR_NO_SOCKET = -3005, /*!< socket not available for use */
89  NSAPI_ERROR_NO_ADDRESS = -3006, /*!< IP address is not known */
90  NSAPI_ERROR_NO_MEMORY = -3007, /*!< memory resource not available */
91  NSAPI_ERROR_NO_SSID = -3008, /*!< ssid not found */
92  NSAPI_ERROR_DNS_FAILURE = -3009, /*!< DNS failed to complete successfully */
93  NSAPI_ERROR_DHCP_FAILURE = -3010, /*!< DHCP failed to complete successfully */
94  NSAPI_ERROR_AUTH_FAILURE = -3011, /*!< connection to access point failed */
95  NSAPI_ERROR_DEVICE_ERROR = -3012, /*!< failure interfacing with the network processor */
96  NSAPI_ERROR_IN_PROGRESS = -3013, /*!< operation (eg connect) in progress */
97  NSAPI_ERROR_ALREADY = -3014, /*!< operation (eg connect) already in progress */
98  NSAPI_ERROR_IS_CONNECTED = -3015, /*!< socket is already connected */
99  NSAPI_ERROR_CONNECTION_LOST = -3016, /*!< connection lost */
100  NSAPI_ERROR_CONNECTION_TIMEOUT = -3017, /*!< connection timed out */
101  NSAPI_ERROR_ADDRESS_IN_USE = -3018, /*!< Address already in use */
102  NSAPI_ERROR_TIMEOUT = -3019, /*!< operation timed out */
103  NSAPI_ERROR_BUSY = -3020, /*!< device is busy and cannot accept new operation */
104 };
105 
106 
107 /** Enum of connection status types
108  *
109  * Valid error codes have negative values.
110  *
111  * @enum nsapi_connection_status
112  */
114  NSAPI_STATUS_LOCAL_UP = 0, /*!< local IP address set */
115  NSAPI_STATUS_GLOBAL_UP = 1, /*!< global IP address set */
116  NSAPI_STATUS_DISCONNECTED = 2, /*!< no connection to network */
117  NSAPI_STATUS_CONNECTING = 3, /*!< connecting to network */
118  NSAPI_STATUS_ERROR_UNSUPPORTED = NSAPI_ERROR_UNSUPPORTED
119 } nsapi_connection_status_t;
120 
121 
122 /** Enum of event types
123  *
124  * Event callbacks are accompanied with an event-dependent parameter passed as an intptr_t.
125  *
126  * @enum nsapi_event
127  */
128 typedef enum nsapi_event {
129  NSAPI_EVENT_CONNECTION_STATUS_CHANGE = 0, /*!< network connection status has changed, the parameter = new status (nsapi_connection_status_t) */
130  NSAPI_EVENT_CELLULAR_STATUS_BASE = 0x1000, /*!< Cellular modem status has changed, See the enum values from enum cellular_connection_status_t in /connectivity/cellular/framework/common/CellularCommon.h */
131  NSAPI_EVENT_CELLULAR_STATUS_END = 0x1FFF /*!< cellular modem status has changed, See the enum values from enum cellular_connection_status_t in /connectivity/cellular/framework/common/CellularCommon.h */
132 } nsapi_event_t;
133 
134 
135 /** Type used to represent error codes
136  *
137  * This is a separate type from enum nsapi_error to avoid breaking
138  * compatibility in type-sensitive overloads
139  */
140 typedef signed int nsapi_error_t;
141 
142 /** Type used to represent the size of data passed through sockets
143  */
144 typedef unsigned int nsapi_size_t;
145 
146 /** Type used to represent either a size or error passed through sockets
147  *
148  * A valid nsapi_size_or_error_t is either a non-negative size or a
149  * negative error code from the nsapi_error_t
150  */
151 typedef signed int nsapi_size_or_error_t;
152 
153 /** Type used to represent either a value or error
154  *
155  * A valid nsapi_value_or_error_t is either a non-negative value or a
156  * negative error code from the nsapi_error_t
157  */
158 typedef signed int nsapi_value_or_error_t;
159 
160 /** Enum of encryption types
161  *
162  * The security type specifies a particular security to use when
163  * connected to a WiFi network
164  */
165 typedef enum nsapi_security {
166  NSAPI_SECURITY_NONE = 0x0, /*!< open access point */
167  NSAPI_SECURITY_WEP = 0x1, /*!< phrase conforms to WEP */
168  NSAPI_SECURITY_WPA = 0x2, /*!< phrase conforms to WPA */
169  NSAPI_SECURITY_WPA2 = 0x3, /*!< phrase conforms to WPA2 */
170  NSAPI_SECURITY_WPA_WPA2 = 0x4, /*!< phrase conforms to WPA/WPA2 */
171  NSAPI_SECURITY_PAP = 0x5, /*!< phrase conforms to PPP authentication context */
172  NSAPI_SECURITY_CHAP = 0x6, /*!< phrase conforms to PPP authentication context */
173  NSAPI_SECURITY_EAP_TLS = 0x7, /*!< phrase conforms to EAP-TLS */
174  NSAPI_SECURITY_PEAP = 0x8, /*!< phrase conforms to PEAP */
175  NSAPI_SECURITY_WPA2_ENT = 0x9, /*!< phrase conforms to WPA2-AES and WPA-TKIP with enterprise security */
176  NSAPI_SECURITY_WPA3 = 0xA, /*!< phrase conforms to WPA3 */
177  NSAPI_SECURITY_WPA3_WPA2 = 0xB, /*!< phrase conforms to WPA3_WPA2 */
178  NSAPI_SECURITY_UNKNOWN = 0xFF, /*!< unknown/unsupported security in scan results */
180 
181 /** Size of 2 char network interface name from driver
182  */
183 #define NSAPI_INTERFACE_PREFIX_SIZE 2
184 
185 /** Maximum size of network interface name
186  */
187 #define NSAPI_INTERFACE_NAME_MAX_SIZE 6
188 
189 /** Maximum size of IP address representation
190  */
191 #define NSAPI_IP_SIZE NSAPI_IPv6_SIZE
192 
193 /** Maximum number of bytes for IP address
194  */
195 #define NSAPI_IP_BYTES NSAPI_IPv6_BYTES
196 
197 /** Maximum size of MAC address representation
198  */
199 #define NSAPI_MAC_SIZE 18
200 
201 /** Maximum number of bytes for MAC address
202  */
203 #define NSAPI_MAC_BYTES 6
204 
205 /** Size of IPv4 representation
206  */
207 #define NSAPI_IPv4_SIZE 16
208 
209 /** Number of bytes in IPv4 address
210  */
211 #define NSAPI_IPv4_BYTES 4
212 
213 /** Size of IPv6 representation
214  */
215 #define NSAPI_IPv6_SIZE 40
216 
217 /** Number of bytes in IPv6 address
218  */
219 #define NSAPI_IPv6_BYTES 16
220 
221 /** Enum of IP address versions
222  *
223  * The IP version specifies the type of an IP address.
224  *
225  * @enum nsapi_version
226  */
227 typedef enum nsapi_version {
228  NSAPI_UNSPEC, /*!< Address is unspecified */
229  NSAPI_IPv4, /*!< Address is IPv4 */
230  NSAPI_IPv6, /*!< Address is IPv6 */
231 } nsapi_version_t;
232 
233 /** IP address structure for passing IP addresses by value
234  */
235 typedef struct nsapi_addr {
236  /** IP version
237  * - NSAPI_IPv4
238  * - NSAPI_IPv6
239  * - NSAPI_UNSPEC
240  */
241  nsapi_version_t version;
242 
243  /** IP address
244  * The raw bytes of the IP address stored in big-endian format
245  */
247 } nsapi_addr_t;
248 
249 
250 /** Opaque handle for network sockets
251  */
252 typedef void *nsapi_socket_t;
253 
254 
255 /** Enum of socket protocols
256  *
257  * The socket protocol specifies a particular protocol to
258  * be used with a newly created socket.
259  *
260  * @enum nsapi_protocol
261  */
262 typedef enum nsapi_protocol {
263  NSAPI_TCP, /*!< Socket is of TCP type */
264  NSAPI_UDP, /*!< Socket is of UDP type */
265  NSAPI_ICMP, /*!< Socket is of ICMP type */
266 } nsapi_protocol_t;
267 
268 /** Enum of standardized stack option levels
269  * for use with NetworkStack::setstackopt and getstackopt.
270  *
271  * @enum nsapi_stack_level
272  */
273 typedef enum nsapi_stack_level {
274  NSAPI_STACK = 5000, /*!< Stack option level - see nsapi_stack_option_t for options */
275 } nsapi_stack_level_t;
276 
277 /** Enum of standardized stack option names for level NSAPI_STACK
278  * of NetworkStack::setstackopt and getstackopt.
279  *
280  * These options may not be supported on all stacks, in which
281  * case NSAPI_ERROR_UNSUPPORTED may be returned.
282  *
283  * @enum nsapi_stack_option
284  */
285 typedef enum nsapi_stack_option {
286  NSAPI_IPV4_MRU, /*!< Sets/gets size of largest IPv4 fragmented datagram to reassemble */
287  NSAPI_IPV6_MRU, /*!< Sets/gets size of largest IPv6 fragmented datagram to reassemble */
288 } nsapi_stack_option_t;
289 
290 /** Enum of standardized socket option levels
291  * for use with Socket::setsockopt and getsockopt.
292  *
293  * @enum nsapi_socket_level
294  */
295 typedef enum nsapi_socket_level {
296  NSAPI_SOCKET = 7000, /*!< Socket option level - see nsapi_socket_option_t for options */
297 } nsapi_socket_level_t;
298 
299 /** Enum of standardized socket option names for level NSAPI_SOCKET
300  * of Socket::setsockopt and getsockopt.
301  *
302  * These options may not be supported on all stacks, in which
303  * case NSAPI_ERROR_UNSUPPORTED may be returned.
304  *
305  * @enum nsapi_socket_option
306  */
307 typedef enum nsapi_socket_option {
308  NSAPI_REUSEADDR, /*!< Allow bind to reuse local addresses */
309  NSAPI_KEEPALIVE, /*!< Enables sending of keepalive messages */
310  NSAPI_KEEPIDLE, /*!< Sets timeout value to initiate keepalive */
311  NSAPI_KEEPINTVL, /*!< Sets timeout value for keepalive */
312  NSAPI_LINGER, /*!< Keeps close from returning until queues empty */
313  NSAPI_SNDBUF, /*!< Sets send buffer size */
314  NSAPI_RCVBUF, /*!< Sets recv buffer size */
315  NSAPI_ADD_MEMBERSHIP, /*!< Add membership to multicast address */
316  NSAPI_DROP_MEMBERSHIP, /*!< Drop membership to multicast address */
317  NSAPI_BIND_TO_DEVICE, /*!< Bind socket network interface name*/
318  NSAPI_LATENCY, /*!< Read estimated latency to destination */
319  NSAPI_STAGGER, /*!< Read estimated stagger value to destination */
320  NSAPI_IPTOS, /*!< Set IP type of service to set specific precedence */
321 } nsapi_socket_option_t;
322 
323 typedef enum nsapi_tlssocket_level {
324  NSAPI_TLSSOCKET_LEVEL = 7099, /*!< TLSSocket option level - see nsapi_tlssocket_option_t for options*/
325 } nsapi_tlssocket_level_t;
326 
328  NSAPI_TLSSOCKET_SET_HOSTNAME, /*!< Set host name */
329  NSAPI_TLSSOCKET_SET_CACERT, /*!< Set server CA certificate */
330  NSAPI_TLSSOCKET_SET_CLCERT, /*!< Set client certificate */
331  NSAPI_TLSSOCKET_SET_CLKEY, /*!< Set client key */
332  NSAPI_TLSSOCKET_ENABLE /*!< Enable TLSSocket */
333 } nsapi_tlssocket_option_t;
334 
335 /** Supported IP protocol versions of IP stack
336  *
337  * @enum nsapi_ip_stack
338  */
339 typedef enum nsapi_ip_stack {
340  DEFAULT_STACK = 0,
341  IPV4_STACK,
342  IPV6_STACK,
343  IPV4V6_STACK
344 } nsapi_ip_stack_t;
345 
346 /* Backwards compatibility - previously didn't distinguish stack and socket options */
347 typedef nsapi_socket_level_t nsapi_level_t;
348 typedef nsapi_socket_option_t nsapi_option_t;
349 
350 /** nsapi_wifi_ap structure
351  *
352  * Structure representing a WiFi Access Point
353  */
354 typedef struct nsapi_wifi_ap {
355  char ssid[33]; /* 32 is what 802.11 defines as longest possible name; +1 for the \0 */
356  uint8_t bssid[6];
357  nsapi_security_t security;
358  int8_t rssi;
359  uint8_t channel;
361 
362 
363 /** nsapi_stack structure
364  *
365  * Stack structure representing a specific instance of a stack.
366  */
367 typedef struct nsapi_stack {
368  /** Network stack operation table
369  *
370  * Provides access to the underlying api of the stack. This is not
371  * flattened into the nsapi_stack to allow allocation in read-only
372  * memory.
373  */
374  const struct nsapi_stack_api *stack_api;
375 
376  /** Opaque handle for network stacks
377  */
378  void *stack;
379 
380  // Internal nsapi buffer
381  unsigned _stack_buffer[16];
382 } nsapi_stack_t;
383 
384 /** nsapi_ip_mreq structure
385  */
386 typedef struct nsapi_ip_mreq {
387  nsapi_addr_t imr_multiaddr; /* IP multicast address of group */
388  nsapi_addr_t imr_interface; /* local IP address of interface */
390 
391 /** nsapi_latency_req structure
392  */
393 typedef struct nsapi_latency_req {
394  uint8_t addr[16]; /* [IN] Destination address to estimate latency */
395  uint32_t latency; /* [OUT] Latency value */
397 
398 /** nsapi_stagger_req structure
399  */
400 typedef struct nsapi_stagger_req {
401  uint8_t addr[16]; /* [IN] Destination address to estimate stagger */
402  uint16_t data_amount; /* [IN] Amount of data to be sent in kilobytes */
403  uint16_t stagger_min; /* [OUT] Minimum stagger value in seconds */
404  uint16_t stagger_max; /* [OUT] Maximum stagger value in seconds */
405  uint16_t stagger_rand; /* [OUT] Randomized stagger value in seconds */
407 
408 /** nsapi_stack_api structure
409  *
410  * Common api structure for network stack operations. A network stack
411  * can provide a nsapi_stack_api structure filled out with the
412  * appropriate implementation.
413  *
414  * Unsupported operations can be left as null pointers.
415  */
416 typedef struct nsapi_stack_api {
417  /** Get the local IP address
418  *
419  * @param stack Stack handle
420  * @return Local IP Address or null address if not connected
421  */
422  nsapi_addr_t (*get_ip_address)(nsapi_stack_t *stack);
423 
424  /** Translates a hostname to an IP address
425  *
426  * The hostname may be either a domain name or an IP address. If the
427  * hostname is an IP address, no network transactions will be performed.
428  *
429  * If no stack-specific DNS resolution is provided, the hostname
430  * will be resolve using a UDP socket on the stack.
431  *
432  * @param stack Stack handle
433  * @param addr Destination for the host IP address
434  * @param host Hostname to resolve
435  * @param version Address family
436  * @return 0 on success, negative error code on failure
437  */
438  nsapi_error_t (*gethostbyname)(nsapi_stack_t *stack, const char *host, nsapi_addr_t *addr, nsapi_version_t version);
439 
440  /** Add a domain name server to list of servers to query
441  *
442  * @param addr Destination for the host address
443  * @return 0 on success, negative error code on failure
444  */
445  nsapi_error_t (*add_dns_server)(nsapi_stack_t *stack, nsapi_addr_t addr);
446 
447  /** Set stack-specific stack options
448  *
449  * The setstackopt allow an application to pass stack-specific hints
450  * to the underlying stack. For unsupported options,
451  * NSAPI_ERROR_UNSUPPORTED is returned and the stack is unmodified.
452  *
453  * @param stack Stack handle
454  * @param level Stack-specific protocol level
455  * @param optname Stack-specific option identifier
456  * @param optval Option value
457  * @param optlen Length of the option value
458  * @return 0 on success, negative error code on failure
459  */
460  nsapi_error_t (*setstackopt)(nsapi_stack_t *stack, int level,
461  int optname, const void *optval, unsigned optlen);
462 
463  /** Get stack-specific stack options
464  *
465  * The getstackopt allow an application to retrieve stack-specific hints
466  * from the underlying stack. For unsupported options,
467  * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
468  *
469  * @param stack Stack handle
470  * @param level Stack-specific protocol level
471  * @param optname Stack-specific option identifier
472  * @param optval Destination for option value
473  * @param optlen Length of the option value
474  * @return 0 on success, negative error code on failure
475  */
476  nsapi_error_t (*getstackopt)(nsapi_stack_t *stack, int level,
477  int optname, void *optval, unsigned *optlen);
478 
479  /** Opens a socket
480  *
481  * Creates a network socket and stores it in the specified handle.
482  * The handle must be passed to following calls on the socket.
483  *
484  * A stack may have a finite number of sockets, in this case
485  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
486  *
487  * @param stack Stack context
488  * @param socket Destination for the handle to a newly created socket
489  * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
490  * @return 0 on success, negative error code on failure
491  */
492  nsapi_error_t (*socket_open)(nsapi_stack_t *stack, nsapi_socket_t *socket,
493  nsapi_protocol_t proto);
494 
495  /** Close the socket
496  *
497  * Closes any open connection and deallocates any memory associated
498  * with the socket.
499  *
500  * @param stack Stack handle
501  * @param socket Socket handle
502  * @return 0 on success, negative error code on failure
503  */
504  nsapi_error_t (*socket_close)(nsapi_stack_t *stack, nsapi_socket_t socket);
505 
506  /** Bind a specific address to a socket
507  *
508  * Binding a socket specifies the address and port on which to receive
509  * data. If the IP address is zeroed, only the port is bound.
510  *
511  * @param stack Stack handle
512  * @param socket Socket handle
513  * @param addr Local address to bind, may be null
514  * @param port Local port to bind
515  * @return 0 on success, negative error code on failure.
516  */
517  nsapi_error_t (*socket_bind)(nsapi_stack_t *stack, nsapi_socket_t socket,
518  nsapi_addr_t addr, uint16_t port);
519 
520  /** Listen for connections on a TCP socket
521  *
522  * Marks the socket as a passive socket that can be used to accept
523  * incoming connections.
524  *
525  * @param stack Stack handle
526  * @param socket Socket handle
527  * @param backlog Number of pending connections that can be queued
528  * simultaneously
529  * @return 0 on success, negative error code on failure
530  */
531  nsapi_error_t (*socket_listen)(nsapi_stack_t *stack, nsapi_socket_t socket, int backlog);
532 
533  /** Connects TCP socket to a remote host
534  *
535  * Initiates a connection to a remote server specified by the
536  * indicated address.
537  *
538  * @param stack Stack handle
539  * @param socket Socket handle
540  * @param addr The address of the remote host
541  * @param port The port of the remote host
542  * @return 0 on success, negative error code on failure
543  */
544  nsapi_error_t (*socket_connect)(nsapi_stack_t *stack, nsapi_socket_t socket,
545  nsapi_addr_t addr, uint16_t port);
546 
547  /** Accepts a connection on a TCP socket
548  *
549  * The server socket must be bound and set to listen for connections.
550  * On a new connection, creates a network socket and stores it in the
551  * specified handle. The handle must be passed to following calls on
552  * the socket.
553  *
554  * A stack may have a finite number of sockets, in this case
555  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
556  *
557  * This call is non-blocking. If accept would block,
558  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
559  *
560  * @param stack Stack handle
561  * @param server Socket handle to server to accept from
562  * @param socket Destination for a handle to the newly created socket
563  * @param addr Destination for the address of the remote host
564  * @param port Destination for the port of the remote host
565  * @return 0 on success, negative error code on failure
566  */
567  nsapi_error_t (*socket_accept)(nsapi_stack_t *stack, nsapi_socket_t server,
568  nsapi_socket_t *socket, nsapi_addr_t *addr, uint16_t *port);
569 
570  /** Send data over a TCP socket
571  *
572  * The socket must be connected to a remote host. Returns the number of
573  * bytes sent from the buffer.
574  *
575  * This call is non-blocking. If send would block,
576  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
577  *
578  * @param stack Stack handle
579  * @param socket Socket handle
580  * @param data Buffer of data to send to the host
581  * @param size Size of the buffer in bytes
582  * @return Number of sent bytes on success, negative error
583  * code on failure
584  */
585  nsapi_size_or_error_t (*socket_send)(nsapi_stack_t *stack, nsapi_socket_t socket,
586  const void *data, nsapi_size_t size);
587 
588  /** Receive data over a TCP socket
589  *
590  * The socket must be connected to a remote host. Returns the number of
591  * bytes received into the buffer.
592  *
593  * This call is non-blocking. If recv would block,
594  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
595  *
596  * @param stack Stack handle
597  * @param socket Socket handle
598  * @param data Destination buffer for data received from the host
599  * @param size Size of the buffer in bytes
600  * @return Number of received bytes on success, negative error
601  * code on failure
602  */
603  nsapi_size_or_error_t (*socket_recv)(nsapi_stack_t *stack, nsapi_socket_t socket,
604  void *data, nsapi_size_t size);
605 
606  /** Send a packet over a UDP socket
607  *
608  * Sends data to the specified address. Returns the number of bytes
609  * sent from the buffer.
610  *
611  * This call is non-blocking. If sendto would block,
612  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
613  *
614  * @param stack Stack handle
615  * @param socket Socket handle
616  * @param addr The address of the remote host
617  * @param port The port of the remote host
618  * @param data Buffer of data to send to the host
619  * @param size Size of the buffer in bytes
620  * @return Number of sent bytes on success, negative error
621  * code on failure
622  */
623  nsapi_size_or_error_t (*socket_sendto)(nsapi_stack_t *stack, nsapi_socket_t socket,
624  nsapi_addr_t addr, uint16_t port, const void *data, nsapi_size_t size);
625 
626  /** Receive a packet over a UDP socket
627  *
628  * Receives data and stores the source address in address if address
629  * is not NULL. Returns the number of bytes received into the buffer.
630  *
631  * This call is non-blocking. If recvfrom would block,
632  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
633  *
634  * @param stack Stack handle
635  * @param socket Socket handle
636  * @param addr Destination for the address of the remote host
637  * @param port Destination for the port of the remote host
638  * @param data Destination buffer for data received from the host
639  * @param size Size of the buffer in bytes
640  * @return Number of received bytes on success, negative error
641  * code on failure
642  */
643  nsapi_size_or_error_t (*socket_recvfrom)(nsapi_stack_t *stack, nsapi_socket_t socket,
644  nsapi_addr_t *addr, uint16_t *port, void *buffer, nsapi_size_t size);
645 
646  /** Register a callback on state change of the socket
647  *
648  * The specified callback will be called on state changes such as when
649  * the socket can recv/send/accept successfully and on when an error
650  * occurs. The callback may also be called spuriously without reason.
651  *
652  * The callback may be called in an interrupt context and should not
653  * perform expensive operations such as recv/send calls.
654  *
655  * @param stack Stack handle
656  * @param socket Socket handle
657  * @param callback Function to call on state change
658  * @param data Argument to pass to callback
659  */
660  void (*socket_attach)(nsapi_stack_t *stack, nsapi_socket_t socket,
661  void (*callback)(void *), void *data);
662 
663  /** Set stack-specific socket options
664  *
665  * The setsockopt allow an application to pass stack-specific hints
666  * to the underlying stack. For unsupported options,
667  * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
668  *
669  * @param stack Stack handle
670  * @param socket Socket handle
671  * @param level Stack-specific protocol level
672  * @param optname Stack-specific option identifier
673  * @param optval Option value
674  * @param optlen Length of the option value
675  * @return 0 on success, negative error code on failure
676  */
677  nsapi_error_t (*setsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level,
678  int optname, const void *optval, unsigned optlen);
679 
680  /** Get stack-specific socket options
681  *
682  * The getstackopt allow an application to retrieve stack-specific hints
683  * from the underlying stack. For unsupported options,
684  * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
685  *
686  * @param stack Stack handle
687  * @param socket Socket handle
688  * @param level Stack-specific protocol level
689  * @param optname Stack-specific option identifier
690  * @param optval Destination for option value
691  * @param optlen Length of the option value
692  * @return 0 on success, negative error code on failure
693  */
694  nsapi_error_t (*getsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level,
695  int optname, void *optval, unsigned *optlen);
697 
698 
699 #ifdef __cplusplus
700 }
701 #endif
702 
703 #endif
704 
705 /** @}*/
nsapi_stack structure
Definition: nsapi_types.h:367
nsapi_stack_option
Enum of standardized stack option names for level NSAPI_STACK of NetworkStack::setstackopt and getsta...
Definition: nsapi_types.h:285
nsapi_latency_req structure
Definition: nsapi_types.h:393
const struct nsapi_stack_api * stack_api
Network stack operation table.
Definition: nsapi_types.h:374
void * nsapi_socket_t
Opaque handle for network sockets.
Definition: nsapi_types.h:252
void * stack
Opaque handle for network stacks.
Definition: nsapi_types.h:378
nsapi_security
Enum of encryption types.
Definition: nsapi_types.h:165
nsapi_stack_api structure
Definition: nsapi_types.h:416
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:140
struct nsapi_stack_api nsapi_stack_api_t
nsapi_stack_api structure
nsapi_stack_level
Enum of standardized stack option levels for use with NetworkStack::setstackopt and getstackopt...
Definition: nsapi_types.h:273
nsapi_ip_stack
Supported IP protocol versions of IP stack.
Definition: nsapi_types.h:339
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:151
#define NSAPI_IP_BYTES
Maximum number of bytes for IP address.
Definition: nsapi_types.h:195
nsapi_socket_level
Enum of standardized socket option levels for use with Socket::setsockopt and getsockopt.
Definition: nsapi_types.h:295
struct nsapi_stagger_req nsapi_stagger_req_t
nsapi_stagger_req structure
signed int nsapi_value_or_error_t
Type used to represent either a value or error.
Definition: nsapi_types.h:158
struct nsapi_addr nsapi_addr_t
IP address structure for passing IP addresses by value.
nsapi_wifi_ap structure
Definition: nsapi_types.h:354
nsapi_event
Enum of event types.
Definition: nsapi_types.h:128
struct nsapi_wifi_ap nsapi_wifi_ap_t
nsapi_wifi_ap structure
uint8_t bytes[16]
IP address The raw bytes of the IP address stored in big-endian format.
Definition: nsapi_types.h:246
nsapi_version_t version
IP version.
Definition: nsapi_types.h:241
nsapi_connection_status
Enum of connection status types.
Definition: nsapi_types.h:113
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:144
nsapi_stagger_req structure
Definition: nsapi_types.h:400
IP address structure for passing IP addresses by value.
Definition: nsapi_types.h:235
struct nsapi_latency_req nsapi_latency_req_t
nsapi_latency_req structure
enum nsapi_security nsapi_security_t
Enum of encryption types.
nsapi_tlssocket_level
Definition: nsapi_types.h:323
struct nsapi_ip_mreq nsapi_ip_mreq_t
nsapi_ip_mreq structure
nsapi_error
Enum of standardized error codes.
Definition: nsapi_types.h:82
nsapi_tlssocket_option
Definition: nsapi_types.h:327
struct nsapi_stack nsapi_stack_t
nsapi_stack structure
nsapi_ip_mreq structure
Definition: nsapi_types.h:386
nsapi_protocol
Enum of socket protocols.
Definition: nsapi_types.h:262
nsapi_socket_option
Enum of standardized socket option names for level NSAPI_SOCKET of Socket::setsockopt and getsockopt...
Definition: nsapi_types.h:307
nsapi_version
Enum of IP address versions.
Definition: nsapi_types.h:227
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.