Base class for IP Based Networking Libraries

Dependencies:   DnsQuery

Dependents:   TempTower BSDInterfaceTests HelloBSDInterface ESP8266InterfaceTests ... more

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers NetworkStack.h Source File

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