NetworkStack.h

00001 
00002 /* NetworkStack
00003  * Copyright (c) 2015 ARM Limited
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef NETWORK_STACK_H
00019 #define NETWORK_STACK_H
00020 
00021 #include "nsapi_types.h"
00022 #include "netsocket/SocketAddress.h"
00023 #include "netsocket/NetworkInterface.h"
00024 #include "DNS.h"
00025 
00026 /** @file NetworkStack.h NetworkStack class */
00027 /** @addtogroup netsocket
00028  * @{ */
00029 
00030 // Predeclared classes
00031 class OnboardNetworkStack;
00032 
00033 /** NetworkStack class
00034  *
00035  *  Common interface that is shared between hardware that
00036  *  can connect to a network over IP. By implementing the
00037  *  NetworkStack, a network stack can be used as a target
00038  *  for instantiating network sockets.
00039  */
00040 class NetworkStack: public DNS {
00041 public:
00042     virtual ~NetworkStack() {};
00043 
00044     /** Get the local IP address
00045      *
00046      *  @param          address SocketAddress representation of the local IP address
00047      *  @retval         NSAPI_ERROR_OK on success
00048      *  @retval         NSAPI_ERROR_UNSUPPORTED if this feature is not supported
00049      *  @retval         NSAPI_ERROR_PARAMETER if the provided pointer is invalid
00050      *  @retval         NSAPI_ERROR_NO_ADDRESS if the address cannot be obtained from stack
00051      */
00052     virtual nsapi_error_t get_ip_address(SocketAddress *address);
00053 
00054     MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00055     virtual const char *get_ip_address();
00056 
00057     /** Get the IPv6 link local address
00058      *
00059      *  @param          address SocketAddress representation of the link local IPv6 address
00060      *  @retval         NSAPI_ERROR_OK on success
00061      *  @retval         NSAPI_ERROR_UNSUPPORTED if this feature is not supported
00062      *  @retval         NSAPI_ERROR_PARAMETER if the provided pointer is invalid
00063      */
00064     virtual nsapi_error_t get_ipv6_link_local_address(SocketAddress *address);
00065 
00066     /** Get the local IP address on interface name
00067      *
00068      *  @param          address SocketAddress representation of the link local IPv6 address
00069      *  @param          interface_name  Network interface_name
00070      *  @retval         NSAPI_ERROR_OK on success
00071      *  @retval         NSAPI_ERROR_UNSUPPORTED if this feature is not supported
00072      *  @retval         NSAPI_ERROR_PARAMETER if the provided pointer is invalid
00073      *  @retval         NSAPI_ERROR_NO_ADDRESS if the address cannot be obtained from stack
00074      */
00075     virtual nsapi_error_t get_ip_address_if(SocketAddress *address, const char *interface_name);
00076 
00077     MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00078     virtual const char *get_ip_address_if(const char *interface_name);
00079 
00080     /** Translates a hostname to an IP address with specific version
00081      *
00082      *  The hostname may be either a domain name or an IP address. If the
00083      *  hostname is an IP address, no network transactions will be performed.
00084      *
00085      *  If no stack-specific DNS resolution is provided, the hostname
00086      *  will be resolve using a UDP socket on the stack.
00087      *
00088      *  @param host     Hostname to resolve
00089      *  @param address  Pointer to a SocketAddress to store the result.
00090      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
00091      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
00092      *  @param interface_name  Network interface_name
00093      *  @retval         NSAPI_ERROR_OK on success
00094      *  @retval         NSAPI_ERROR_PARAMETER if invalid (null) name is provided
00095      *  @retval         NSAPI_ERROR_DNS_FAILURE if DNS resolution fails
00096      *  @retval         int other negative errors, see @ref nsapi_dns_query
00097      */
00098     virtual nsapi_error_t gethostbyname(const char *host,
00099                                         SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC , const char *interface_name = NULL);
00100 
00101     /** Hostname translation callback (asynchronous)
00102      *
00103      *  Callback will be called after DNS resolution completes or a failure occurs.
00104      *
00105      *  Callback should not take more than 10ms to execute, otherwise it might
00106      *  prevent underlying thread processing. A portable user of the callback
00107      *  should not make calls to network operations due to stack size limitations.
00108      *  The callback should not perform expensive operations such as socket recv/send
00109      *  calls or blocking operations.
00110      *
00111      *  @param status  NSAPI_ERROR_OK on success, negative error code on failure
00112      *  @param address On success, destination for the host SocketAddress
00113      */
00114     typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
00115 
00116     /** Translates a hostname to an IP address (asynchronous)
00117      *
00118      *  The hostname may be either a domain name or an IP address. If the
00119      *  hostname is an IP address, no network transactions will be performed.
00120      *
00121      *  If no stack-specific DNS resolution is provided, the hostname
00122      *  will be resolve using a UDP socket on the stack.
00123      *
00124      *  Call is non-blocking. Result of the DNS operation is returned by the callback.
00125      *  If this function returns failure, callback will not be called. In case result
00126      *  is success (IP address was found from DNS cache), callback will be called
00127      *  before function returns.
00128      *
00129      *  @param host     Hostname to resolve
00130      *  @param callback Callback that is called for result
00131      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
00132      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
00133      *  @param interface_name  Network interface_name
00134      *  @return         0 on immediate success,
00135      *                  negative error code on immediate failure or
00136      *                  a positive unique id that represents the hostname translation operation
00137      *                  and can be passed to cancel
00138      */
00139     virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version = NSAPI_UNSPEC ,
00140                                                        const char *interface_name = NULL);
00141 
00142     /** Cancels asynchronous hostname translation
00143      *
00144      *  When translation is cancelled, callback will not be called.
00145      *
00146      *  @param id       Unique id of the hostname translation operation
00147      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00148      */
00149     virtual nsapi_error_t gethostbyname_async_cancel(int id);
00150 
00151     /** Add a domain name server to list of servers to query
00152      *
00153      *  @param address  Destination for the host address
00154      *  @param interface_name  Network interface name
00155      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00156      */
00157     virtual nsapi_error_t add_dns_server(const SocketAddress &address, const char *interface_name = NULL);
00158 
00159     /** Get a domain name server from a list of servers to query
00160      *
00161      *  Returns a DNS server address for a index. If returns error no more
00162      *  DNS servers to read.
00163      *
00164      *  @param index    Index of the DNS server, starts from zero
00165      *  @param address  Destination for the host address
00166      *  @param interface_name  Network interface name
00167      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00168      */
00169     virtual nsapi_error_t get_dns_server(int index, SocketAddress *address, const char *interface_name = NULL);
00170 
00171     /*  Set stack options
00172      *
00173      *  setstackopt allows an application to pass stack-specific options
00174      *  to the underlying stack using stack-specific level and option names,
00175      *  or to request generic options using levels from nsapi_stack_level_t.
00176      *
00177      *  For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
00178      *  and the stack is unmodified.
00179      *
00180      *  @param level    Stack-specific protocol level or nsapi_stack_level_t
00181      *  @param optname  Level-specific option name
00182      *  @param optval   Option value
00183      *  @param optlen   Length of the option value
00184      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00185      */
00186     virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen);
00187 
00188     /*  Get stack options
00189      *
00190      *  getstackopt allows an application to retrieve stack-specific options
00191      *  to the underlying stack using stack-specific level and option names,
00192      *  or to request generic options using levels from nsapi_stack_level_t.
00193      *
00194      *  @param level    Stack-specific protocol level or nsapi_stack_level_t
00195      *  @param optname  Level-specific option name
00196      *  @param optval   Destination for option value
00197      *  @param optlen   Length of the option value
00198      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00199      */
00200     virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen);
00201 
00202     /** Dynamic downcast to a OnboardNetworkStack */
00203     virtual OnboardNetworkStack *onboardNetworkStack()
00204     {
00205         return 0;
00206     }
00207 
00208 protected:
00209     friend class InternetSocket;
00210     friend class InternetDatagramSocket;
00211     friend class TCPSocket;
00212     friend class TCPServer;
00213 
00214     /** Opens a socket
00215      *
00216      *  Creates a network socket and stores it in the specified handle.
00217      *  The handle must be passed to following calls on the socket.
00218      *
00219      *  A stack may have a finite number of sockets, in this case
00220      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00221      *
00222      *  @param handle   Destination for the handle to a newly created socket
00223      *  @param proto    Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
00224      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00225      */
00226     virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0;
00227 
00228     /** Close the socket
00229      *
00230      *  Closes any open connection and deallocates any memory associated
00231      *  with the socket.
00232      *
00233      *  @param handle   Socket handle
00234      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00235      */
00236     virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0;
00237 
00238     /** Bind a specific address to a socket
00239      *
00240      *  Binding a socket specifies the address and port on which to receive
00241      *  data. If the IP address is zeroed, only the port is bound.
00242      *
00243      *  @param handle   Socket handle
00244      *  @param address  Local address to bind
00245      *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
00246      */
00247     virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0;
00248 
00249     /** Listen for connections on a TCP socket
00250      *
00251      *  Marks the socket as a passive socket that can be used to accept
00252      *  incoming connections.
00253      *
00254      *  @param handle   Socket handle
00255      *  @param backlog  Number of pending connections that can be queued
00256      *                  simultaneously
00257      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00258      */
00259     virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0;
00260 
00261     /** Connects TCP socket to a remote host
00262      *
00263      *  Initiates a connection to a remote server specified by the
00264      *  indicated address.
00265      *
00266      *  @param handle   Socket handle
00267      *  @param address  The SocketAddress of the remote host
00268      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00269      */
00270     virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0;
00271 
00272     /** Accepts a connection on a TCP socket
00273      *
00274      *  The server socket must be bound and set to listen for connections.
00275      *  On a new connection, creates a network socket and stores it in the
00276      *  specified handle. The handle must be passed to following calls on
00277      *  the socket.
00278      *
00279      *  A stack may have a finite number of sockets, in this case
00280      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00281      *
00282      *  This call is non-blocking. If accept would block,
00283      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00284      *
00285      *  @param server   Socket handle to server to accept from
00286      *  @param handle   Destination for a handle to the newly created socket
00287      *  @param address  Destination for the remote address or NULL
00288      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00289      */
00290     virtual nsapi_error_t socket_accept(nsapi_socket_t server,
00291                                         nsapi_socket_t *handle, SocketAddress *address = 0) = 0;
00292 
00293     /** Send data over a TCP socket
00294      *
00295      *  The socket must be connected to a remote host. Returns the number of
00296      *  bytes sent from the buffer.
00297      *
00298      *  This call is non-blocking. If send would block,
00299      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00300      *
00301      *  @param handle   Socket handle
00302      *  @param data     Buffer of data to send to the host
00303      *  @param size     Size of the buffer in bytes
00304      *  @return         Number of sent bytes on success, negative error
00305      *                  code on failure
00306      */
00307     virtual nsapi_size_or_error_t socket_send(nsapi_socket_t handle,
00308                                               const void *data, nsapi_size_t size) = 0;
00309 
00310     /** Receive data over a TCP socket
00311      *
00312      *  The socket must be connected to a remote host. Returns the number of
00313      *  bytes received into the buffer.
00314      *
00315      *  This call is non-blocking. If recv would block,
00316      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00317      *
00318      *  @param handle   Socket handle
00319      *  @param data     Destination buffer for data received from the host
00320      *  @param size     Size of the buffer in bytes
00321      *  @return         Number of received bytes on success, negative error
00322      *                  code on failure
00323      */
00324     virtual nsapi_size_or_error_t socket_recv(nsapi_socket_t handle,
00325                                               void *data, nsapi_size_t size) = 0;
00326 
00327     /** Send a packet over a UDP socket
00328      *
00329      *  Sends data to the specified address. Returns the number of bytes
00330      *  sent from the buffer.
00331      *
00332      *  This call is non-blocking. If sendto would block,
00333      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00334      *
00335      *  @param handle   Socket handle
00336      *  @param address  The SocketAddress of the remote host
00337      *  @param data     Buffer of data to send to the host
00338      *  @param size     Size of the buffer in bytes
00339      *  @return         Number of sent bytes on success, negative error
00340      *                  code on failure
00341      */
00342     virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address,
00343                                                 const void *data, nsapi_size_t size) = 0;
00344 
00345     /** Receive a packet over a UDP socket
00346      *
00347      *  Receives data and stores the source address in address if address
00348      *  is not NULL. Returns the number of bytes received into the buffer.
00349      *
00350      *  This call is non-blocking. If recvfrom would block,
00351      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00352      *
00353      *  @param handle   Socket handle
00354      *  @param address  Destination for the source address or NULL
00355      *  @param buffer   Destination buffer for data received from the host
00356      *  @param size     Size of the buffer in bytes
00357      *  @return         Number of received bytes on success, negative error
00358      *                  code on failure
00359      */
00360     virtual nsapi_size_or_error_t socket_recvfrom(nsapi_socket_t handle, SocketAddress *address,
00361                                                   void *buffer, nsapi_size_t size) = 0;
00362 
00363     /** Register a callback on state change of the socket
00364      *
00365      *  The specified callback will be called on state changes such as when
00366      *  the socket can recv/send/accept successfully and on when an error
00367      *  occurs. The callback may also be called spuriously without reason.
00368      *
00369      *  The callback may be called in an interrupt context and should not
00370      *  perform expensive operations such as recv/send calls.
00371      *
00372      *  @param handle   Socket handle
00373      *  @param callback Function to call on state change
00374      *  @param data     Argument to pass to callback
00375      */
00376     virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0;
00377 
00378     /**  Set stack-specific socket options.
00379      *
00380      *  The setsockopt allow an application to pass stack-specific hints
00381      *  to the underlying stack. For unsupported options,
00382      *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
00383      *
00384      *  @param handle   Socket handle.
00385      *  @param level    Stack-specific protocol level.
00386      *  @param optname  Stack-specific option identifier.
00387      *  @param optval   Option value.
00388      *  @param optlen   Length of the option value.
00389      *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
00390      */
00391     virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
00392                                      int optname, const void *optval, unsigned optlen);
00393 
00394     /**  Get stack-specific socket options.
00395      *
00396      *  The getstackopt allow an application to retrieve stack-specific hints
00397      *  from the underlying stack. For unsupported options,
00398      *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
00399      *
00400      *  @param handle   Socket handle.
00401      *  @param level    Stack-specific protocol level.
00402      *  @param optname  Stack-specific option identifier.
00403      *  @param optval   Destination for option value.
00404      *  @param optlen   Length of the option value.
00405      *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
00406      */
00407     virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
00408                                      int optname, void *optval, unsigned *optlen);
00409 
00410 private:
00411 
00412     /** Call in callback
00413       *
00414       *  Callback is used to call the call in method of the network stack.
00415       */
00416     typedef mbed::Callback<nsapi_error_t (int delay_ms, mbed::Callback<void()> user_cb)> call_in_callback_cb_t;
00417 
00418     /** Get a call in callback
00419      *
00420      *  Get a call in callback from the network stack context.
00421      *
00422      *  Callback should not take more than 10ms to execute, otherwise it might
00423      *  prevent underlying thread processing. A portable user of the callback
00424      *  should not make calls to network operations due to stack size limitations.
00425      *  The callback should not perform expensive operations such as socket recv/send
00426      *  calls or blocking operations.
00427      *
00428      *  @return         Call in callback
00429      */
00430     virtual call_in_callback_cb_t get_call_in_callback();
00431 
00432     /** Call a callback after a delay
00433      *
00434      *  Call a callback from the network stack context after a delay. If function
00435      *  returns error callback will not be called.
00436      *
00437      *  @param delay    Delay in milliseconds
00438      *  @param func     Callback to be called
00439      *  @return         NSAPI_ERROR_OK on success, negative error code on failure
00440      */
00441     virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
00442 };
00443 
00444 /** Convert a raw nsapi_stack_t object into a C++ NetworkStack object
00445  *
00446  *  @param stack    Reference to an object that can be converted to a stack
00447  *                  - A raw nsapi_stack_t object
00448  *                  - A reference to a network stack
00449  *                  - A reference to a network interface
00450  *  @return         Reference to the underlying network stack
00451  */
00452 NetworkStack *nsapi_create_stack(nsapi_stack_t *stack);
00453 NetworkStack *nsapi_create_stack(NetworkStack *stack);
00454 
00455 template <typename IF>
00456 NetworkStack *nsapi_create_stack(IF *iface)
00457 {
00458     return nsapi_create_stack(static_cast<NetworkInterface *>(iface)->get_stack());
00459 }
00460 
00461 
00462 #endif
00463 
00464 /** @} */