nsapi_types.h

00001 /* nsapi.h - The network socket API
00002  * Copyright (c) 2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef NSAPI_TYPES_H
00018 #define NSAPI_TYPES_H
00019 
00020 #include <stdint.h>
00021 
00022 #ifdef __cplusplus
00023 extern "C" {
00024 #endif
00025 
00026 
00027 /** Enum of standardized error codes 
00028  *
00029  *  Valid error codes have negative values and may
00030  *  be returned by any network operation.
00031  *
00032  *  @enum nsapi_error_t
00033  */
00034 typedef enum nsapi_error {
00035     NSAPI_ERROR_WOULD_BLOCK   = -3001,     /*!< no data is not available but call is non-blocking */
00036     NSAPI_ERROR_UNSUPPORTED   = -3002,     /*!< unsupported functionality */
00037     NSAPI_ERROR_PARAMETER     = -3003,     /*!< invalid configuration */
00038     NSAPI_ERROR_NO_CONNECTION = -3004,     /*!< not connected to a network */
00039     NSAPI_ERROR_NO_SOCKET     = -3005,     /*!< socket not available for use */
00040     NSAPI_ERROR_NO_ADDRESS    = -3006,     /*!< IP address is not known */
00041     NSAPI_ERROR_NO_MEMORY     = -3007,     /*!< memory resource not available */
00042     NSAPI_ERROR_DNS_FAILURE   = -3008,     /*!< DNS failed to complete successfully */
00043     NSAPI_ERROR_DHCP_FAILURE  = -3009,     /*!< DHCP failed to complete successfully */
00044     NSAPI_ERROR_AUTH_FAILURE  = -3010,     /*!< connection to access point faield */
00045     NSAPI_ERROR_DEVICE_ERROR  = -3011,     /*!< failure interfacing with the network procesor */
00046 } nsapi_error_t;
00047 
00048 
00049 /** Maximum size of IP address representation
00050  */
00051 #define NSAPI_IP_SIZE NSAPI_IPv6_SIZE
00052 
00053 /** Maximum number of bytes for IP address
00054  */
00055 #define NSAPI_IP_BYTES NSAPI_IPv6_BYTES
00056 
00057 /** Maximum size of MAC address representation
00058  */
00059 #define NSAPI_MAC_SIZE 18
00060 
00061 /** Maximum number of bytes for MAC address
00062  */
00063 #define NSAPI_MAC_BYTES 6
00064 
00065 /** Size of IPv4 representation
00066  */
00067 #define NSAPI_IPv4_SIZE 16
00068 
00069 /** Number of bytes in IPv4 address
00070  */
00071 #define NSAPI_IPv4_BYTES 4
00072 
00073 /** Size of IPv6 representation
00074  */
00075 #define NSAPI_IPv6_SIZE 40
00076 
00077 /** Number of bytes in IPv6 address
00078  */
00079 #define NSAPI_IPv6_BYTES 16
00080 
00081 /** Enum of IP address versions
00082  *
00083  *  The IP version specifies the type of an IP address.
00084  *
00085  *  @enum nsapi_version_t
00086  */
00087 typedef enum nsapi_version {
00088     NSAPI_IPv4, /*!< Address is IPv4 */
00089     NSAPI_IPv6, /*!< Address is IPv6 */
00090 } nsapi_version_t;
00091 
00092 /** IP address structure for passing IP addresses by value
00093  */
00094 typedef struct nsapi_addr {
00095     /** IP version
00096      *  NSAPI_IPv4 or NSAPI_IPv6
00097      */
00098     nsapi_version_t version;
00099 
00100     /** IP address
00101      *  The raw bytes of the IP address stored in big-endian format
00102      */
00103     uint8_t bytes[NSAPI_IP_BYTES];
00104 } nsapi_addr_t;
00105 
00106 
00107 /** Opaque handle for network sockets
00108  */
00109 typedef void *nsapi_socket_t;
00110 
00111 
00112 /** Enum of socket protocols
00113  *
00114  *  The socket protocol specifies a particular protocol to
00115  *  be used with a newly created socket. 
00116  *
00117  *  @enum nsapi_protocol_t
00118  */
00119 typedef enum nsapi_protocol {
00120    NSAPI_TCP, /*!< Socket is of TCP type */
00121    NSAPI_UDP, /*!< Socket is of UDP type */
00122 } nsapi_protocol_t;
00123 
00124 /*  Enum of standardized stack option levels
00125  *
00126  *  @enum nsapi_level_t
00127  */
00128 typedef enum nsapi_level {
00129     NSAPI_STACK,  /*!< Stack option level */
00130     NSAPI_SOCKET, /*!< Socket option level */
00131 } nsapi_level_t;
00132 
00133 /*  Enum of standardized stack options
00134  *
00135  *  These options may not be supported on all stacks, in which
00136  *  case NSAPI_ERROR_UNSUPPORTED may be returned from setsockopt.
00137  *
00138  *  @enum nsapi_option_t
00139  */
00140 typedef enum nsapi_option {
00141     NSAPI_REUSEADDR, /*!< Allow bind to reuse local addresses */
00142     NSAPI_KEEPALIVE, /*!< Enables sending of keepalive messages */
00143     NSAPI_KEEPIDLE,  /*!< Sets timeout value to initiate keepalive */
00144     NSAPI_KEEPINTVL, /*!< Sets timeout value for keepalive */
00145     NSAPI_LINGER,    /*!< Keeps close from returning until queues empty */
00146     NSAPI_SNDBUF,    /*!< Sets send buffer size */
00147     NSAPI_RCVBUF,    /*!< Sets recv buffer size */
00148 } nsapi_option_t;
00149 
00150 
00151 /** nsapi_stack structure
00152  *
00153  *  Stack structure representing a specific instance of a stack.
00154  */
00155 typedef struct nsapi_stack {
00156     /** Network stack operation table
00157      *
00158      *  Provides access to the underlying api of the stack. This is not
00159      *  flattened into the nsapi_stack to allow allocation in read-only
00160      *  memory.
00161      */
00162     const struct nsapi_stack_api *stack_api;
00163 
00164     /** Opaque handle for network stacks
00165      */
00166     void *stack;
00167 
00168     // Internal nsapi buffer
00169     unsigned _stack_buffer[16];
00170 } nsapi_stack_t;
00171 
00172 /** nsapi_stack_api structure
00173  *
00174  *  Common api structure for network stack operations. A network stack
00175  *  can provide a nsapi_stack_api structure filled out with the
00176  *  appropriate implementation.
00177  *
00178  *  Unsupported operations can be left as null pointers.
00179  */
00180 typedef struct nsapi_stack_api
00181 {
00182     /** Get the local IP address
00183      *
00184      *  @param stack    Stack handle
00185      *  @return         Local IP Address or null address if not connected
00186      */
00187     nsapi_addr_t (*get_ip_address)(nsapi_stack_t *stack);
00188 
00189     /** Translates a hostname to an IP address
00190      *
00191      *  The hostname may be either a domain name or an IP address. If the
00192      *  hostname is an IP address, no network transactions will be performed.
00193      *  
00194      *  If no stack-specific DNS resolution is provided, the hostname
00195      *  will be resolve using a UDP socket on the stack. 
00196      *
00197      *  @param stack    Stack handle
00198      *  @param addr     Destination for the host IP address
00199      *  @param host     Hostname to resolve
00200      *  @return         0 on success, negative error code on failure
00201      */
00202     int (*gethostbyname)(nsapi_stack_t *stack, nsapi_addr_t *addr, const char *host);
00203 
00204     /*  Set stack-specific stack options
00205      *
00206      *  The setstackopt allow an application to pass stack-specific hints
00207      *  to the underlying stack. For unsupported options,
00208      *  NSAPI_ERROR_UNSUPPORTED is returned and the stack is unmodified.
00209      *
00210      *  @param stack    Stack handle
00211      *  @param level    Stack-specific protocol level
00212      *  @param optname  Stack-specific option identifier
00213      *  @param optval   Option value
00214      *  @param optlen   Length of the option value
00215      *  @return         0 on success, negative error code on failure
00216      */
00217     int (*setstackopt)(nsapi_stack_t *stack, int level, int optname, const void *optval, unsigned optlen);
00218 
00219     /*  Get stack-specific stack options
00220      *
00221      *  The getstackopt allow an application to retrieve stack-specific hints
00222      *  from the underlying stack. For unsupported options,
00223      *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
00224      *
00225      *  @param stack    Stack handle
00226      *  @param level    Stack-specific protocol level
00227      *  @param optname  Stack-specific option identifier
00228      *  @param optval   Destination for option value
00229      *  @param optlen   Length of the option value
00230      *  @return         0 on success, negative error code on failure
00231      */    
00232     int (*getstackopt)(nsapi_stack_t *stack, int level, int optname, void *optval, unsigned *optlen);
00233 
00234     /** Opens a socket
00235      *
00236      *  Creates a network socket and stores it in the specified handle.
00237      *  The handle must be passed to following calls on the socket.
00238      *
00239      *  A stack may have a finite number of sockets, in this case
00240      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00241      *
00242      *  @param stack    Stack context
00243      *  @param socket   Destination for the handle to a newly created socket
00244      *  @param proto    Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
00245      *  @return         0 on success, negative error code on failure
00246      */
00247     int (*socket_open)(nsapi_stack_t *stack, nsapi_socket_t *socket, nsapi_protocol_t proto);
00248 
00249     /** Close the socket
00250      *
00251      *  Closes any open connection and deallocates any memory associated
00252      *  with the socket.
00253      *
00254      *  @param stack    Stack handle
00255      *  @param socket   Socket handle
00256      *  @return         0 on success, negative error code on failure
00257      */
00258     int (*socket_close)(nsapi_stack_t *stack, nsapi_socket_t socket);
00259 
00260     /** Bind a specific address to a socket
00261      *
00262      *  Binding a socket specifies the address and port on which to recieve
00263      *  data. If the IP address is zeroed, only the port is bound.
00264      *
00265      *  @param stack    Stack handle
00266      *  @param socket   Socket handle
00267      *  @param addr     Local address to bind, may be null
00268      *  @param port     Local port to bind
00269      *  @return         0 on success, negative error code on failure.
00270      */
00271     int (*socket_bind)(nsapi_stack_t *stack, nsapi_socket_t socket, nsapi_addr_t addr, uint16_t port);
00272 
00273     /** Listen for connections on a TCP socket
00274      *
00275      *  Marks the socket as a passive socket that can be used to accept
00276      *  incoming connections.
00277      *
00278      *  @param stack    Stack handle
00279      *  @param socket   Socket handle
00280      *  @param backlog  Number of pending connections that can be queued
00281      *                  simultaneously
00282      *  @return         0 on success, negative error code on failure
00283      */
00284     int (*socket_listen)(nsapi_stack_t *stack, nsapi_socket_t socket, int backlog);
00285 
00286     /** Connects TCP socket to a remote host
00287      *
00288      *  Initiates a connection to a remote server specified by the
00289      *  indicated address.
00290      *
00291      *  @param stack    Stack handle
00292      *  @param socket   Socket handle
00293      *  @param addr     The address of the remote host
00294      *  @param port     The port of the remote host
00295      *  @return         0 on success, negative error code on failure
00296      */
00297     int (*socket_connect)(nsapi_stack_t *stack, nsapi_socket_t socket, nsapi_addr_t addr, uint16_t port);
00298 
00299     /** Accepts a connection on a TCP socket
00300      *
00301      *  The server socket must be bound and set to listen for connections.
00302      *  On a new connection, creates a network socket and stores it in the
00303      *  specified handle. The handle must be passed to following calls on
00304      *  the socket.
00305      *
00306      *  A stack may have a finite number of sockets, in this case
00307      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00308      *
00309      *  This call is non-blocking. If accept would block,
00310      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00311      *
00312      *  @param stack    Stack handle
00313      *  @param server   Socket handle to server to accept from
00314      *  @param socket   Destination for a handle to the newly created socket
00315      *  @param addr     Destination for the address of the remote host
00316      *  @param port     Destination for the port of the remote host
00317      *  @return         0 on success, negative error code on failure
00318      */
00319     int (*socket_accept)(nsapi_stack_t *stack, nsapi_socket_t server, nsapi_socket_t *socket, nsapi_addr_t *addr, uint16_t *port);
00320 
00321     /** Send data over a TCP socket
00322      *
00323      *  The socket must be connected to a remote host. Returns the number of
00324      *  bytes sent from the buffer.
00325      *
00326      *  This call is non-blocking. If send would block,
00327      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00328      *
00329      *  @param stack    Stack handle
00330      *  @param socket   Socket handle
00331      *  @param data     Buffer of data to send to the host
00332      *  @param size     Size of the buffer in bytes
00333      *  @return         Number of sent bytes on success, negative error
00334      *                  code on failure
00335      */
00336     int (*socket_send)(nsapi_stack_t *stack, nsapi_socket_t socket, const void *data, unsigned size);
00337 
00338     /** Receive data over a TCP socket
00339      *
00340      *  The socket must be connected to a remote host. Returns the number of
00341      *  bytes received into the buffer.
00342      *
00343      *  This call is non-blocking. If recv would block,
00344      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00345      *
00346      *  @param stack    Stack handle
00347      *  @param socket   Socket handle
00348      *  @param data     Destination buffer for data received from the host
00349      *  @param size     Size of the buffer in bytes
00350      *  @return         Number of received bytes on success, negative error
00351      *                  code on failure
00352      */
00353     int (*socket_recv)(nsapi_stack_t *stack, nsapi_socket_t socket, void *data, unsigned size);
00354 
00355     /** Send a packet over a UDP socket
00356      *
00357      *  Sends data to the specified address. Returns the number of bytes
00358      *  sent from the buffer.
00359      *
00360      *  This call is non-blocking. If sendto would block,
00361      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00362      *
00363      *  @param stack    Stack handle
00364      *  @param socket   Socket handle
00365      *  @param addr     The address of the remote host
00366      *  @param port     The port of the remote host
00367      *  @param data     Buffer of data to send to the host
00368      *  @param size     Size of the buffer in bytes
00369      *  @return         Number of sent bytes on success, negative error
00370      *                  code on failure
00371      */
00372     int (*socket_sendto)(nsapi_stack_t *stack, nsapi_socket_t socket, nsapi_addr_t addr, uint16_t port, const void *data, unsigned size);
00373 
00374     /** Receive a packet over a UDP socket
00375      *
00376      *  Receives data and stores the source address in address if address
00377      *  is not NULL. Returns the number of bytes received into the buffer.
00378      *
00379      *  This call is non-blocking. If recvfrom would block,
00380      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00381      *
00382      *  @param stack    Stack handle
00383      *  @param socket   Socket handle
00384      *  @param addr     Destination for the address of the remote host
00385      *  @param port     Destination for the port of the remote host
00386      *  @param data     Destination buffer for data received from the host
00387      *  @param size     Size of the buffer in bytes
00388      *  @return         Number of received bytes on success, negative error
00389      *                  code on failure
00390      */
00391     int (*socket_recvfrom)(nsapi_stack_t *stack, nsapi_socket_t socket, nsapi_addr_t *addr, uint16_t *port, void *buffer, unsigned size);
00392 
00393     /** Register a callback on state change of the socket
00394      *
00395      *  The specified callback will be called on state changes such as when
00396      *  the socket can recv/send/accept successfully and on when an error
00397      *  occurs. The callback may also be called spuriously without reason.
00398      *
00399      *  The callback may be called in an interrupt context and should not
00400      *  perform expensive operations such as recv/send calls.
00401      *
00402      *  @param stack    Stack handle
00403      *  @param socket   Socket handle
00404      *  @param callback Function to call on state change
00405      *  @param data     Argument to pass to callback
00406      */
00407     void (*socket_attach)(nsapi_stack_t *stack, nsapi_socket_t socket, void (*callback)(void *), void *data);
00408 
00409     /*  Set stack-specific socket options
00410      *
00411      *  The setsockopt allow an application to pass stack-specific hints
00412      *  to the underlying stack. For unsupported options,
00413      *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
00414      *
00415      *  @param stack    Stack handle
00416      *  @param socket   Socket handle
00417      *  @param level    Stack-specific protocol level
00418      *  @param optname  Stack-specific option identifier
00419      *  @param optval   Option value
00420      *  @param optlen   Length of the option value
00421      *  @return         0 on success, negative error code on failure
00422      */    
00423     int (*setsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level, int optname, const void *optval, unsigned optlen);
00424 
00425     /*  Get stack-specific socket options
00426      *
00427      *  The getstackopt allow an application to retrieve stack-specific hints
00428      *  from the underlying stack. For unsupported options,
00429      *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
00430      *
00431      *  @param stack    Stack handle
00432      *  @param socket   Socket handle
00433      *  @param level    Stack-specific protocol level
00434      *  @param optname  Stack-specific option identifier
00435      *  @param optval   Destination for option value
00436      *  @param optlen   Length of the option value
00437      *  @return         0 on success, negative error code on failure
00438      */    
00439     int (*getsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level, int optname, void *optval, unsigned *optlen);
00440 } nsapi_stack_api_t;
00441 
00442 
00443 #ifdef __cplusplus
00444 }
00445 #endif
00446 
00447 #endif