NetworkStack.h

00001 /* NetworkStack
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 NETWORK_INTERFACE_H
00018 #define NETWORK_INTERFACE_H
00019 
00020 #include "mbed.h"
00021 #include "SocketAddress.h"
00022 
00023 
00024 /** Enum of standardized error codes 
00025  *
00026  *  Valid error codes have negative values and may
00027  *  be returned by any network operation.
00028  *
00029  *  @enum nsapi_error_t
00030  */
00031 enum nsapi_error_t {
00032     NSAPI_ERROR_WOULD_BLOCK   = -3001,     /*!< no data is not available but call is non-blocking */
00033     NSAPI_ERROR_UNSUPPORTED   = -3002,     /*!< unsupported functionality */
00034     NSAPI_ERROR_PARAMETER     = -3003,     /*!< invalid configuration */
00035     NSAPI_ERROR_NO_CONNECTION = -3004,     /*!< not connected to a network */
00036     NSAPI_ERROR_NO_SOCKET     = -3005,     /*!< socket not available for use */
00037     NSAPI_ERROR_NO_ADDRESS    = -3006,     /*!< IP address is not known */
00038     NSAPI_ERROR_NO_MEMORY     = -3007,     /*!< memory resource not available */
00039     NSAPI_ERROR_DNS_FAILURE   = -3008,     /*!< DNS failed to complete successfully */
00040     NSAPI_ERROR_DHCP_FAILURE  = -3009,     /*!< DHCP failed to complete successfully */
00041     NSAPI_ERROR_AUTH_FAILURE  = -3010,     /*!< connection to access point faield */
00042     NSAPI_ERROR_DEVICE_ERROR  = -3011,     /*!< failure interfacing with the network procesor */
00043 };
00044 
00045 /** Enum of socket protocols
00046  *
00047  *  The socket protocol specifies a particular protocol to
00048  *  be used with a newly created socket. 
00049  *
00050  *  @enum nsapi_protocol_t
00051  */
00052 enum nsapi_protocol_t {
00053    NSAPI_TCP, /*!< Socket is of TCP type */
00054    NSAPI_UDP, /*!< Socket is of UDP type */
00055    NSAPI_TLS  /*!< Socket is of TCP Secure type */
00056 };
00057 
00058 /*  Enum of standardized stack option levels
00059  *
00060  *  @enum nsapi_level_t
00061  */
00062 enum nsapi_level_t {
00063     NSAPI_STACK,  /*!< Stack option level */
00064     NSAPI_SOCKET, /*!< Socket option level */
00065 };
00066 
00067 /*  Enum of standardized stack options
00068  *
00069  *  These options may not be supported on all stacks, in which
00070  *  case NSAPI_ERROR_UNSUPPORTED may be returned from setsockopt.
00071  *
00072  *  @enum nsapi_option_t
00073  */
00074 enum nsapi_option_t {
00075     NSAPI_REUSEADDR, /*!< Allow bind to reuse local addresses */
00076     NSAPI_KEEPALIVE, /*!< Enables sending of keepalive messages */
00077     NSAPI_LINGER,    /*!< Keeps close from returning until queues empty */
00078     NSAPI_SNDBUF,    /*!< Sets send buffer size */
00079     NSAPI_RCVBUF,    /*!< Sets recv buffer size */
00080 };
00081 
00082 
00083 /** NetworkStack class
00084  *
00085  *  Common interface that is shared between hardware that
00086  *  can connect to a network over IP. By implementing the
00087  *  NetworkStack, a network stack can be used as a target
00088  *  for instantiating network sockets.
00089  */
00090 class NetworkStack
00091 {
00092 public:
00093     virtual ~NetworkStack() {};
00094 
00095     /** Get the local IP address
00096      *
00097      *  @return         Null-terminated representation of the local IP address
00098      *                  or null if not yet connected
00099      */
00100     virtual const char *get_ip_address() = 0;
00101 
00102     /** Translates a hostname to an IP address
00103      *
00104      *  The hostname may be either a domain name or an IP address. If the
00105      *  hostname is an IP address, no network transactions will be performed.
00106      *  
00107      *  If no stack-specific DNS resolution is provided, the hostname
00108      *  will be resolve using a UDP socket on the stack. 
00109      *
00110      *  @param address  Destination for the host SocketAddress
00111      *  @param host     Hostname to resolve
00112      *  @return         0 on success, negative error code on failure
00113      */
00114     virtual int gethostbyname(SocketAddress *address, const char *host);
00115 
00116     /*  Set stack-specific stack options
00117      *
00118      *  The setstackopt allow an application to pass stack-specific hints
00119      *  to the underlying stack. For unsupported options,
00120      *  NSAPI_ERROR_UNSUPPORTED is returned and the stack is unmodified.
00121      *
00122      *  @param level    Stack-specific protocol level
00123      *  @param optname  Stack-specific option identifier
00124      *  @param optval   Option value
00125      *  @param optlen   Length of the option value
00126      *  @return         0 on success, negative error code on failure
00127      */    
00128     virtual int setstackopt(int level, int optname, const void *optval, unsigned optlen);
00129 
00130     /*  Get stack-specific stack options
00131      *
00132      *  The getstackopt allow an application to retrieve stack-specific hints
00133      *  from the underlying stack. For unsupported options,
00134      *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
00135      *
00136      *  @param level    Stack-specific protocol level
00137      *  @param optname  Stack-specific option identifier
00138      *  @param optval   Destination for option value
00139      *  @param optlen   Length of the option value
00140      *  @return         0 on success, negative error code on failure
00141      */    
00142     virtual int getstackopt(int level, int optname, void *optval, unsigned *optlen);
00143 
00144 protected:
00145     friend class Socket;
00146     friend class UDPSocket;
00147     friend class TCPSocket;
00148     friend class TCPServer;
00149 
00150     /** Opens a socket
00151      *
00152      *  Creates a network socket and stores it in the specified handle.
00153      *  The handle must be passed to following calls on the socket.
00154      *
00155      *  A stack may have a finite number of sockets, in this case
00156      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00157      *
00158      *  @param handle   Destination for the handle to a newly created socket
00159      *  @param proto    Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
00160      *  @return         0 on success, negative error code on failure
00161      */
00162     virtual int socket_open(void **handle, nsapi_protocol_t proto) = 0;
00163 
00164     /** Close the socket
00165      *
00166      *  Closes any open connection and deallocates any memory associated
00167      *  with the socket.
00168      *
00169      *  @param handle   Socket handle
00170      *  @return         0 on success, negative error code on failure
00171      */
00172     virtual int socket_close(void *handle) = 0;
00173 
00174     /** Bind a specific address to a socket
00175      *
00176      *  Binding a socket specifies the address and port on which to recieve
00177      *  data. If the IP address is zeroed, only the port is bound.
00178      *
00179      *  @param handle   Socket handle
00180      *  @param address  Local address to bind
00181      *  @return         0 on success, negative error code on failure.
00182      */
00183     virtual int socket_bind(void *handle, const SocketAddress &address) = 0;
00184 
00185     /** Listen for connections on a TCP socket
00186      *
00187      *  Marks the socket as a passive socket that can be used to accept
00188      *  incoming connections.
00189      *
00190      *  @param handle   Socket handle
00191      *  @param backlog  Number of pending connections that can be queued
00192      *                  simultaneously
00193      *  @return         0 on success, negative error code on failure
00194      */
00195     virtual int socket_listen(void *handle, int backlog) = 0;
00196 
00197     /** Connects TCP socket to a remote host
00198      *
00199      *  Initiates a connection to a remote server specified by the
00200      *  indicated address.
00201      *
00202      *  @param handle   Socket handle
00203      *  @param address  The SocketAddress of the remote host
00204      *  @return         0 on success, negative error code on failure
00205      */
00206     virtual int socket_connect(void *handle, const SocketAddress &address) = 0;
00207 
00208     /** Accepts a connection on a TCP socket
00209      *
00210      *  The server socket must be bound and set to listen for connections.
00211      *  On a new connection, creates a network socket and stores it in the
00212      *  specified handle. The handle must be passed to following calls on
00213      *  the socket.
00214      *
00215      *  A stack may have a finite number of sockets, in this case
00216      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00217      *
00218      *  This call is non-blocking. If accept would block,
00219      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00220      *
00221      *  @param handle   Destination for a handle to the newly created sockey
00222      *  @param server   Socket handle to server to accept from
00223      *  @return         0 on success, negative error code on failure
00224      */
00225     virtual int socket_accept(void **handle, void *server) = 0;
00226 
00227     /** Send data over a TCP socket
00228      *
00229      *  The socket must be connected to a remote host. Returns the number of
00230      *  bytes sent from the buffer.
00231      *
00232      *  This call is non-blocking. If send would block,
00233      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00234      *
00235      *  @param handle   Socket handle
00236      *  @param data     Buffer of data to send to the host
00237      *  @param size     Size of the buffer in bytes
00238      *  @return         Number of sent bytes on success, negative error
00239      *                  code on failure
00240      */
00241     virtual int socket_send(void *handle, const void *data, unsigned size) = 0;
00242 
00243     /** Receive data over a TCP socket
00244      *
00245      *  The socket must be connected to a remote host. Returns the number of
00246      *  bytes received into the buffer.
00247      *
00248      *  This call is non-blocking. If recv would block,
00249      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00250      *
00251      *  @param handle   Socket handle
00252      *  @param data     Destination buffer for data received from the host
00253      *  @param size     Size of the buffer in bytes
00254      *  @return         Number of received bytes on success, negative error
00255      *                  code on failure
00256      */
00257     virtual int socket_recv(void *handle, void *data, unsigned size) = 0;
00258 
00259     /** Send a packet over a UDP socket
00260      *
00261      *  Sends data to the specified address. Returns the number of bytes
00262      *  sent from the buffer.
00263      *
00264      *  This call is non-blocking. If sendto would block,
00265      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00266      *
00267      *  @param handle   Socket handle
00268      *  @param address  The SocketAddress of the remote host
00269      *  @param data     Buffer of data to send to the host
00270      *  @param size     Size of the buffer in bytes
00271      *  @return         Number of sent bytes on success, negative error
00272      *                  code on failure
00273      */
00274     virtual int socket_sendto(void *handle, const SocketAddress &address, const void *data, unsigned size) = 0;
00275 
00276     /** Receive a packet over a UDP socket
00277      *
00278      *  Receives data and stores the source address in address if address
00279      *  is not NULL. Returns the number of bytes received into the buffer.
00280      *
00281      *  This call is non-blocking. If recvfrom would block,
00282      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00283      *
00284      *  @param handle   Socket handle
00285      *  @param address  Destination for the source address or NULL
00286      *  @param data     Destination buffer for data received from the host
00287      *  @param size     Size of the buffer in bytes
00288      *  @return         Number of received bytes on success, negative error
00289      *                  code on failure
00290      */
00291     virtual int socket_recvfrom(void *handle, SocketAddress *address, void *buffer, unsigned size) = 0;
00292 
00293     /** Register a callback on state change of the socket
00294      *
00295      *  The specified callback will be called on state changes such as when
00296      *  the socket can recv/send/accept successfully and on when an error
00297      *  occurs. The callback may also be called spuriously without reason.
00298      *
00299      *  The callback may be called in an interrupt context and should not
00300      *  perform expensive operations such as recv/send calls.
00301      *
00302      *  @param handle   Socket handle
00303      *  @param callback Function to call on state change
00304      *  @param data     Argument to pass to callback
00305      */
00306     virtual void socket_attach(void *handle, void (*callback)(void *), void *data) = 0;
00307 
00308     /*  Set stack-specific socket options
00309      *
00310      *  The setsockopt allow an application to pass stack-specific hints
00311      *  to the underlying stack. For unsupported options,
00312      *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
00313      *
00314      *  @param handle   Socket handle
00315      *  @param level    Stack-specific protocol level
00316      *  @param optname  Stack-specific option identifier
00317      *  @param optval   Option value
00318      *  @param optlen   Length of the option value
00319      *  @return         0 on success, negative error code on failure
00320      */    
00321     virtual int setsockopt(void *handle, int level, int optname, const void *optval, unsigned optlen);
00322 
00323     /*  Get stack-specific socket options
00324      *
00325      *  The getstackopt allow an application to retrieve stack-specific hints
00326      *  from the underlying stack. For unsupported options,
00327      *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
00328      *
00329      *  @param handle   Socket handle
00330      *  @param level    Stack-specific protocol level
00331      *  @param optname  Stack-specific option identifier
00332      *  @param optval   Destination for option value
00333      *  @param optlen   Length of the option value
00334      *  @return         0 on success, negative error code on failure
00335      */    
00336     virtual int getsockopt(void *handle, int level, int optname, void *optval, unsigned *optlen);
00337 };
00338 
00339 #endif