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 /features/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 /features/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_UNKNOWN = 0xFF, /*!< unknown/unsupported security in scan results */
133 
134 /** Size of 2 char network interface name from driver
135  */
136 #define NSAPI_INTERFACE_PREFIX_SIZE 2
137 
138 /** Maximum size of network interface name
139  */
140 #define NSAPI_INTERFACE_NAME_MAX_SIZE 6
141 
142 /** Maximum size of IP address representation
143  */
144 #define NSAPI_IP_SIZE NSAPI_IPv6_SIZE
145 
146 /** Maximum number of bytes for IP address
147  */
148 #define NSAPI_IP_BYTES NSAPI_IPv6_BYTES
149 
150 /** Maximum size of MAC address representation
151  */
152 #define NSAPI_MAC_SIZE 18
153 
154 /** Maximum number of bytes for MAC address
155  */
156 #define NSAPI_MAC_BYTES 6
157 
158 /** Size of IPv4 representation
159  */
160 #define NSAPI_IPv4_SIZE 16
161 
162 /** Number of bytes in IPv4 address
163  */
164 #define NSAPI_IPv4_BYTES 4
165 
166 /** Size of IPv6 representation
167  */
168 #define NSAPI_IPv6_SIZE 40
169 
170 /** Number of bytes in IPv6 address
171  */
172 #define NSAPI_IPv6_BYTES 16
173 
174 /** Enum of IP address versions
175  *
176  * The IP version specifies the type of an IP address.
177  *
178  * @enum nsapi_version
179  */
180 typedef enum nsapi_version {
181  NSAPI_UNSPEC, /*!< Address is unspecified */
182  NSAPI_IPv4, /*!< Address is IPv4 */
183  NSAPI_IPv6, /*!< Address is IPv6 */
184 } nsapi_version_t;
185 
186 /** IP address structure for passing IP addresses by value
187  */
188 typedef struct nsapi_addr {
189  /** IP version
190  * - NSAPI_IPv4
191  * - NSAPI_IPv6
192  * - NSAPI_UNSPEC
193  */
194  nsapi_version_t version;
195 
196  /** IP address
197  * The raw bytes of the IP address stored in big-endian format
198  */
200 } nsapi_addr_t;
201 
202 
203 /** Opaque handle for network sockets
204  */
205 typedef void *nsapi_socket_t;
206 
207 
208 /** Enum of socket protocols
209  *
210  * The socket protocol specifies a particular protocol to
211  * be used with a newly created socket.
212  *
213  * @enum nsapi_protocol
214  */
215 typedef enum nsapi_protocol {
216  NSAPI_TCP, /*!< Socket is of TCP type */
217  NSAPI_UDP, /*!< Socket is of UDP type */
218  NSAPI_ICMP, /*!< Socket is of ICMP type */
219 } nsapi_protocol_t;
220 
221 /** Enum of standardized stack option levels
222  * for use with NetworkStack::setstackopt and getstackopt.
223  *
224  * @enum nsapi_stack_level
225  */
226 typedef enum nsapi_stack_level {
227  NSAPI_STACK = 5000, /*!< Stack option level - see nsapi_stack_option_t for options */
228 } nsapi_stack_level_t;
229 
230 /** Enum of standardized stack option names for level NSAPI_STACK
231  * of NetworkStack::setstackopt and getstackopt.
232  *
233  * These options may not be supported on all stacks, in which
234  * case NSAPI_ERROR_UNSUPPORTED may be returned.
235  *
236  * @enum nsapi_stack_option
237  */
238 typedef enum nsapi_stack_option {
239  NSAPI_IPV4_MRU, /*!< Sets/gets size of largest IPv4 fragmented datagram to reassemble */
240  NSAPI_IPV6_MRU, /*!< Sets/gets size of largest IPv6 fragmented datagram to reassemble */
241 } nsapi_stack_option_t;
242 
243 /** Enum of standardized socket option levels
244  * for use with Socket::setsockopt and getsockopt.
245  *
246  * @enum nsapi_socket_level
247  */
248 typedef enum nsapi_socket_level {
249  NSAPI_SOCKET = 7000, /*!< Socket option level - see nsapi_socket_option_t for options */
250 } nsapi_socket_level_t;
251 
252 /** Enum of standardized socket option names for level NSAPI_SOCKET
253  * of Socket::setsockopt and getsockopt.
254  *
255  * These options may not be supported on all stacks, in which
256  * case NSAPI_ERROR_UNSUPPORTED may be returned.
257  *
258  * @enum nsapi_socket_option
259  */
260 typedef enum nsapi_socket_option {
261  NSAPI_REUSEADDR, /*!< Allow bind to reuse local addresses */
262  NSAPI_KEEPALIVE, /*!< Enables sending of keepalive messages */
263  NSAPI_KEEPIDLE, /*!< Sets timeout value to initiate keepalive */
264  NSAPI_KEEPINTVL, /*!< Sets timeout value for keepalive */
265  NSAPI_LINGER, /*!< Keeps close from returning until queues empty */
266  NSAPI_SNDBUF, /*!< Sets send buffer size */
267  NSAPI_RCVBUF, /*!< Sets recv buffer size */
268  NSAPI_ADD_MEMBERSHIP, /*!< Add membership to multicast address */
269  NSAPI_DROP_MEMBERSHIP, /*!< Drop membership to multicast address */
270  NSAPI_BIND_TO_DEVICE, /*!< Bind socket network interface name*/
271  NSAPI_LATENCY, /*!< Read estimated latency to destination */
272  NSAPI_STAGGER, /*!< Read estimated stagger value to destination */
273 } nsapi_socket_option_t;
274 
275 typedef enum nsapi_tlssocket_level {
276  NSAPI_TLSSOCKET_LEVEL = 7099, /*!< TLSSocket option level - see nsapi_tlssocket_option_t for options*/
277 } nsapi_tlssocket_level_t;
278 
280  NSAPI_TLSSOCKET_SET_HOSTNAME, /*!< Set host name */
281  NSAPI_TLSSOCKET_SET_CACERT, /*!< Set server CA certificate */
282  NSAPI_TLSSOCKET_SET_CLCERT, /*!< Set client certificate */
283  NSAPI_TLSSOCKET_SET_CLKEY, /*!< Set client key */
284  NSAPI_TLSSOCKET_ENABLE /*!< Enable TLSSocket */
285 } nsapi_tlssocket_option_t;
286 
287 /** Supported IP protocol versions of IP stack
288  *
289  * @enum nsapi_ip_stack
290  */
291 typedef enum nsapi_ip_stack {
292  DEFAULT_STACK = 0,
293  IPV4_STACK,
294  IPV6_STACK,
295  IPV4V6_STACK
296 } nsapi_ip_stack_t;
297 
298 /* Backwards compatibility - previously didn't distinguish stack and socket options */
299 typedef nsapi_socket_level_t nsapi_level_t;
300 typedef nsapi_socket_option_t nsapi_option_t;
301 
302 /** nsapi_wifi_ap structure
303  *
304  * Structure representing a WiFi Access Point
305  */
306 typedef struct nsapi_wifi_ap {
307  char ssid[33]; /* 32 is what 802.11 defines as longest possible name; +1 for the \0 */
308  uint8_t bssid[6];
309  nsapi_security_t security;
310  int8_t rssi;
311  uint8_t channel;
313 
314 
315 /** nsapi_stack structure
316  *
317  * Stack structure representing a specific instance of a stack.
318  */
319 typedef struct nsapi_stack {
320  /** Network stack operation table
321  *
322  * Provides access to the underlying api of the stack. This is not
323  * flattened into the nsapi_stack to allow allocation in read-only
324  * memory.
325  */
326  const struct nsapi_stack_api *stack_api;
327 
328  /** Opaque handle for network stacks
329  */
330  void *stack;
331 
332  // Internal nsapi buffer
333  unsigned _stack_buffer[16];
334 } nsapi_stack_t;
335 
336 /** nsapi_ip_mreq structure
337  */
338 typedef struct nsapi_ip_mreq {
339  nsapi_addr_t imr_multiaddr; /* IP multicast address of group */
340  nsapi_addr_t imr_interface; /* local IP address of interface */
342 
343 /** nsapi_latency_req structure
344  */
345 typedef struct nsapi_latency_req {
346  uint8_t addr[16]; /* [IN] Destination address to estimate latency */
347  uint32_t latency; /* [OUT] Latency value */
349 
350 /** nsapi_stagger_req structure
351  */
352 typedef struct nsapi_stagger_req {
353  uint8_t addr[16]; /* [IN] Destination address to estimate stagger */
354  uint16_t data_amount; /* [IN] Amount of data to be sent in kilobytes */
355  uint16_t stagger_min; /* [OUT] Minimum stagger value in seconds */
356  uint16_t stagger_max; /* [OUT] Maximum stagger value in seconds */
357  uint16_t stagger_rand; /* [OUT] Randomized stagger value in seconds */
359 
360 /** nsapi_stack_api structure
361  *
362  * Common api structure for network stack operations. A network stack
363  * can provide a nsapi_stack_api structure filled out with the
364  * appropriate implementation.
365  *
366  * Unsupported operations can be left as null pointers.
367  */
368 typedef struct nsapi_stack_api {
369  /** Get the local IP address
370  *
371  * @param stack Stack handle
372  * @return Local IP Address or null address if not connected
373  */
374  nsapi_addr_t (*get_ip_address)(nsapi_stack_t *stack);
375 
376  /** Translates a hostname to an IP address
377  *
378  * The hostname may be either a domain name or an IP address. If the
379  * hostname is an IP address, no network transactions will be performed.
380  *
381  * If no stack-specific DNS resolution is provided, the hostname
382  * will be resolve using a UDP socket on the stack.
383  *
384  * @param stack Stack handle
385  * @param addr Destination for the host IP address
386  * @param host Hostname to resolve
387  * @param version Address family
388  * @return 0 on success, negative error code on failure
389  */
390  nsapi_error_t (*gethostbyname)(nsapi_stack_t *stack, const char *host, nsapi_addr_t *addr, nsapi_version_t version);
391 
392  /** Add a domain name server to list of servers to query
393  *
394  * @param addr Destination for the host address
395  * @return 0 on success, negative error code on failure
396  */
397  nsapi_error_t (*add_dns_server)(nsapi_stack_t *stack, nsapi_addr_t addr);
398 
399  /** Set stack-specific stack options
400  *
401  * The setstackopt allow an application to pass stack-specific hints
402  * to the underlying stack. For unsupported options,
403  * NSAPI_ERROR_UNSUPPORTED is returned and the stack is unmodified.
404  *
405  * @param stack Stack handle
406  * @param level Stack-specific protocol level
407  * @param optname Stack-specific option identifier
408  * @param optval Option value
409  * @param optlen Length of the option value
410  * @return 0 on success, negative error code on failure
411  */
412  nsapi_error_t (*setstackopt)(nsapi_stack_t *stack, int level,
413  int optname, const void *optval, unsigned optlen);
414 
415  /** Get stack-specific stack options
416  *
417  * The getstackopt allow an application to retrieve stack-specific hints
418  * from the underlying stack. For unsupported options,
419  * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
420  *
421  * @param stack Stack handle
422  * @param level Stack-specific protocol level
423  * @param optname Stack-specific option identifier
424  * @param optval Destination for option value
425  * @param optlen Length of the option value
426  * @return 0 on success, negative error code on failure
427  */
428  nsapi_error_t (*getstackopt)(nsapi_stack_t *stack, int level,
429  int optname, void *optval, unsigned *optlen);
430 
431  /** Opens a socket
432  *
433  * Creates a network socket and stores it in the specified handle.
434  * The handle must be passed to following calls on the socket.
435  *
436  * A stack may have a finite number of sockets, in this case
437  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
438  *
439  * @param stack Stack context
440  * @param socket Destination for the handle to a newly created socket
441  * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
442  * @return 0 on success, negative error code on failure
443  */
444  nsapi_error_t (*socket_open)(nsapi_stack_t *stack, nsapi_socket_t *socket,
445  nsapi_protocol_t proto);
446 
447  /** Close the socket
448  *
449  * Closes any open connection and deallocates any memory associated
450  * with the socket.
451  *
452  * @param stack Stack handle
453  * @param socket Socket handle
454  * @return 0 on success, negative error code on failure
455  */
456  nsapi_error_t (*socket_close)(nsapi_stack_t *stack, nsapi_socket_t socket);
457 
458  /** Bind a specific address to a socket
459  *
460  * Binding a socket specifies the address and port on which to receive
461  * data. If the IP address is zeroed, only the port is bound.
462  *
463  * @param stack Stack handle
464  * @param socket Socket handle
465  * @param addr Local address to bind, may be null
466  * @param port Local port to bind
467  * @return 0 on success, negative error code on failure.
468  */
469  nsapi_error_t (*socket_bind)(nsapi_stack_t *stack, nsapi_socket_t socket,
470  nsapi_addr_t addr, uint16_t port);
471 
472  /** Listen for connections on a TCP socket
473  *
474  * Marks the socket as a passive socket that can be used to accept
475  * incoming connections.
476  *
477  * @param stack Stack handle
478  * @param socket Socket handle
479  * @param backlog Number of pending connections that can be queued
480  * simultaneously
481  * @return 0 on success, negative error code on failure
482  */
483  nsapi_error_t (*socket_listen)(nsapi_stack_t *stack, nsapi_socket_t socket, int backlog);
484 
485  /** Connects TCP socket to a remote host
486  *
487  * Initiates a connection to a remote server specified by the
488  * indicated address.
489  *
490  * @param stack Stack handle
491  * @param socket Socket handle
492  * @param addr The address of the remote host
493  * @param port The port of the remote host
494  * @return 0 on success, negative error code on failure
495  */
496  nsapi_error_t (*socket_connect)(nsapi_stack_t *stack, nsapi_socket_t socket,
497  nsapi_addr_t addr, uint16_t port);
498 
499  /** Accepts a connection on a TCP socket
500  *
501  * The server socket must be bound and set to listen for connections.
502  * On a new connection, creates a network socket and stores it in the
503  * specified handle. The handle must be passed to following calls on
504  * the socket.
505  *
506  * A stack may have a finite number of sockets, in this case
507  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
508  *
509  * This call is non-blocking. If accept would block,
510  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
511  *
512  * @param stack Stack handle
513  * @param server Socket handle to server to accept from
514  * @param socket Destination for a handle to the newly created socket
515  * @param addr Destination for the address of the remote host
516  * @param port Destination for the port of the remote host
517  * @return 0 on success, negative error code on failure
518  */
519  nsapi_error_t (*socket_accept)(nsapi_stack_t *stack, nsapi_socket_t server,
520  nsapi_socket_t *socket, nsapi_addr_t *addr, uint16_t *port);
521 
522  /** Send data over a TCP socket
523  *
524  * The socket must be connected to a remote host. Returns the number of
525  * bytes sent from the buffer.
526  *
527  * This call is non-blocking. If send would block,
528  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
529  *
530  * @param stack Stack handle
531  * @param socket Socket handle
532  * @param data Buffer of data to send to the host
533  * @param size Size of the buffer in bytes
534  * @return Number of sent bytes on success, negative error
535  * code on failure
536  */
537  nsapi_size_or_error_t (*socket_send)(nsapi_stack_t *stack, nsapi_socket_t socket,
538  const void *data, nsapi_size_t size);
539 
540  /** Receive data over a TCP socket
541  *
542  * The socket must be connected to a remote host. Returns the number of
543  * bytes received into the buffer.
544  *
545  * This call is non-blocking. If recv would block,
546  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
547  *
548  * @param stack Stack handle
549  * @param socket Socket handle
550  * @param data Destination buffer for data received from the host
551  * @param size Size of the buffer in bytes
552  * @return Number of received bytes on success, negative error
553  * code on failure
554  */
555  nsapi_size_or_error_t (*socket_recv)(nsapi_stack_t *stack, nsapi_socket_t socket,
556  void *data, nsapi_size_t size);
557 
558  /** Send a packet over a UDP socket
559  *
560  * Sends data to the specified address. Returns the number of bytes
561  * sent from the buffer.
562  *
563  * This call is non-blocking. If sendto would block,
564  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
565  *
566  * @param stack Stack handle
567  * @param socket Socket handle
568  * @param addr The address of the remote host
569  * @param port The port of the remote host
570  * @param data Buffer of data to send to the host
571  * @param size Size of the buffer in bytes
572  * @return Number of sent bytes on success, negative error
573  * code on failure
574  */
575  nsapi_size_or_error_t (*socket_sendto)(nsapi_stack_t *stack, nsapi_socket_t socket,
576  nsapi_addr_t addr, uint16_t port, const void *data, nsapi_size_t size);
577 
578  /** Receive a packet over a UDP socket
579  *
580  * Receives data and stores the source address in address if address
581  * is not NULL. Returns the number of bytes received into the buffer.
582  *
583  * This call is non-blocking. If recvfrom would block,
584  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
585  *
586  * @param stack Stack handle
587  * @param socket Socket handle
588  * @param addr Destination for the address of the remote host
589  * @param port Destination for the port of the remote host
590  * @param data Destination buffer for data received from the host
591  * @param size Size of the buffer in bytes
592  * @return Number of received bytes on success, negative error
593  * code on failure
594  */
595  nsapi_size_or_error_t (*socket_recvfrom)(nsapi_stack_t *stack, nsapi_socket_t socket,
596  nsapi_addr_t *addr, uint16_t *port, void *buffer, nsapi_size_t size);
597 
598  /** Register a callback on state change of the socket
599  *
600  * The specified callback will be called on state changes such as when
601  * the socket can recv/send/accept successfully and on when an error
602  * occurs. The callback may also be called spuriously without reason.
603  *
604  * The callback may be called in an interrupt context and should not
605  * perform expensive operations such as recv/send calls.
606  *
607  * @param stack Stack handle
608  * @param socket Socket handle
609  * @param callback Function to call on state change
610  * @param data Argument to pass to callback
611  */
612  void (*socket_attach)(nsapi_stack_t *stack, nsapi_socket_t socket,
613  void (*callback)(void *), void *data);
614 
615  /** Set stack-specific socket options
616  *
617  * The setsockopt allow an application to pass stack-specific hints
618  * to the underlying stack. For unsupported options,
619  * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
620  *
621  * @param stack Stack handle
622  * @param socket Socket handle
623  * @param level Stack-specific protocol level
624  * @param optname Stack-specific option identifier
625  * @param optval Option value
626  * @param optlen Length of the option value
627  * @return 0 on success, negative error code on failure
628  */
629  nsapi_error_t (*setsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level,
630  int optname, const void *optval, unsigned optlen);
631 
632  /** Get stack-specific socket options
633  *
634  * The getstackopt allow an application to retrieve stack-specific hints
635  * from the underlying stack. For unsupported options,
636  * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
637  *
638  * @param stack Stack handle
639  * @param socket Socket handle
640  * @param level Stack-specific protocol level
641  * @param optname Stack-specific option identifier
642  * @param optval Destination for option value
643  * @param optlen Length of the option value
644  * @return 0 on success, negative error code on failure
645  */
646  nsapi_error_t (*getsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level,
647  int optname, void *optval, unsigned *optlen);
649 
650 
651 #ifdef __cplusplus
652 }
653 #endif
654 
655 #endif
656 
657 /** @}*/
nsapi_stack structure
Definition: nsapi_types.h:319
nsapi_stack_option
Enum of standardized stack option names for level NSAPI_STACK of NetworkStack::setstackopt and getsta...
Definition: nsapi_types.h:238
nsapi_latency_req structure
Definition: nsapi_types.h:345
const struct nsapi_stack_api * stack_api
Network stack operation table.
Definition: nsapi_types.h:326
void * nsapi_socket_t
Opaque handle for network sockets.
Definition: nsapi_types.h:205
void * stack
Opaque handle for network stacks.
Definition: nsapi_types.h:330
nsapi_security
Enum of encryption types.
Definition: nsapi_types.h:120
nsapi_stack_api structure
Definition: nsapi_types.h:368
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:226
nsapi_ip_stack
Supported IP protocol versions of IP stack.
Definition: nsapi_types.h:291
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:148
nsapi_socket_level
Enum of standardized socket option levels for use with Socket::setsockopt and getsockopt.
Definition: nsapi_types.h:248
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:306
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:199
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=0)
Create a callback class with type inferred from the arguments.
Definition: Callback.h:709
nsapi_version_t version
IP version.
Definition: nsapi_types.h:194
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:352
IP address structure for passing IP addresses by value.
Definition: nsapi_types.h:188
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:275
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:279
struct nsapi_stack nsapi_stack_t
nsapi_stack structure
nsapi_ip_mreq structure
Definition: nsapi_types.h:338
nsapi_protocol
Enum of socket protocols.
Definition: nsapi_types.h:215
nsapi_socket_option
Enum of standardized socket option names for level NSAPI_SOCKET of Socket::setsockopt and getsockopt...
Definition: nsapi_types.h:260
nsapi_version
Enum of IP address versions.
Definition: nsapi_types.h:180
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.