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