emac_TestNetworkStack.h

00001 /*
00002  * Copyright (c) 2018, ARM Limited, All Rights Reserved
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License"); you may
00006  * 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, WITHOUT
00013  * 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 #if MBED_CONF_APP_TEST_WIFI || MBED_CONF_APP_TEST_ETHERNET
00019 
00020 #ifndef EMAC_TEST_NETWORK_STACK_H
00021 #define EMAC_TEST_NETWORK_STACK_H
00022 
00023 #include "netsocket/nsapi_types.h"
00024 #include "netsocket/EMAC.h"
00025 #include "netsocket/OnboardNetworkStack.h"
00026 
00027 #include "emac_TestMemoryManager.h"
00028 
00029 class EmacTestNetworkStack : public OnboardNetworkStack, private mbed::NonCopyable<EmacTestNetworkStack> {
00030 public:
00031 
00032     static EmacTestNetworkStack &get_instance();
00033 
00034     EmacTestNetworkStack();
00035     virtual ~EmacTestNetworkStack() {}
00036 
00037     class Interface : public OnboardNetworkStack::Interface {
00038     public:
00039 
00040         static Interface &get_instance();
00041 
00042         /** Connect the interface to the network
00043          *
00044          * Sets up a connection on specified network interface, using DHCP or provided network details. If the @a dhcp is set to
00045          * true all the remaining parameters are ignored.
00046          *
00047          * @param    dhcp       true if the network details should be acquired using DHCP
00048          * @param    ip         IP address to be used for the interface as "W:X:Y:Z" or NULL
00049          * @param    netmask    Net mask to be used for the interface as "W:X:Y:Z" or NULL
00050          * @param    gw         Gateway address to be used for the interface as "W:X:Y:Z" or NULL
00051          * @param    stack      Allow manual selection of IPv4 and/or IPv6.
00052          * @param    blocking   Specify whether bringup blocks for connection completion.
00053          * @return              NSAPI_ERROR_OK on success, or error code
00054          */
00055         virtual nsapi_error_t bringup(bool dhcp, const char *ip,
00056                                       const char *netmask, const char *gw,
00057                                       nsapi_ip_stack_t stack = DEFAULT_STACK,
00058                                       bool blocking = true
00059                                       );
00060 
00061         /** Disconnect interface from the network
00062          *
00063          * After this call the network interface is inactive, to use it again user needs to call @a mbed_ipstack_bringup again.
00064          *
00065          * @return    NSAPI_ERROR_OK on success, or error code
00066          */
00067         virtual nsapi_error_t bringdown();
00068 
00069         /** Register callback for status reporting
00070          *
00071          *  The specified status callback function will be called on status changes
00072          *  on the network. The parameters on the callback are the event type and
00073          *  event-type dependent reason parameter.
00074          *
00075          *  @param status_cb The callback for status changes
00076          */
00077         virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00078 
00079         /** Get the connection status
00080          *
00081          *  @return         The connection status according to ConnectionStatusType
00082          */
00083         virtual nsapi_connection_status_t get_connection_status() const;
00084 
00085         /** Return MAC address of the network interface
00086          *
00087          * @return              MAC address as "V:W:X:Y:Z"
00088          */
00089         virtual char *get_mac_address(char *buf, nsapi_size_t buflen);
00090 
00091         /** Copies IP address of the network interface to user supplied buffer
00092          *
00093          * @param    emac       EMAC HAL implementation for this network interface
00094          * @param    buf        buffer to which IP address will be copied as "W:X:Y:Z"
00095          * @param    buflen     size of supplied buffer
00096          * @return              Pointer to a buffer, or NULL if the buffer is too small
00097          */
00098         virtual char *get_ip_address(char *buf, nsapi_size_t buflen);
00099 
00100         /** Copies netmask of the network interface to user supplied buffer
00101          *
00102          * @param    buf        buffer to which netmask will be copied as "W:X:Y:Z"
00103          * @param    buflen     size of supplied buffer
00104          * @return              Pointer to a buffer, or NULL if the buffer is too small
00105          */
00106         virtual char *get_netmask(char *buf, nsapi_size_t buflen);
00107 
00108         /** Copies gateway address of the network interface to user supplied buffer
00109          *
00110          * @param    buf        buffer to which gateway address will be copied as "W:X:Y:Z"
00111          * @param    buflen     size of supplied buffer
00112          * @return              Pointer to a buffer, or NULL if the buffer is too small
00113          */
00114         virtual char *get_gateway(char *buf, nsapi_size_t buflen);
00115 
00116     private:
00117         friend EmacTestNetworkStack;
00118 
00119         Interface();
00120 
00121         EMAC *m_emac;
00122     };
00123 
00124     /** Register a network interface with the IP stack
00125      *
00126      * Connects EMAC layer with the IP stack and initializes all the required infrastructure.
00127      * This function should be called only once for each available interface.
00128      *
00129      * @param      emac             EMAC HAL implementation for this network interface
00130      * @param      default_if       true if the interface should be treated as the default one
00131      * @param[out] interface_out    pointer to stack interface object controlling the EMAC
00132      * @return                      NSAPI_ERROR_OK on success, or error code
00133      */
00134     virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, OnboardNetworkStack::Interface **interface_out);
00135 
00136     /** Translates a hostname to an IP address with specific version
00137      *
00138      *  The hostname may be either a domain name or an IP address. If the
00139      *  hostname is an IP address, no network transactions will be performed.
00140      *
00141      *  If no stack-specific DNS resolution is provided, the hostname
00142      *  will be resolve using a UDP socket on the stack.
00143      *
00144      *  @param host     Hostname to resolve
00145      *  @param address  Destination for the host SocketAddress
00146      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
00147      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
00148      *  @return         0 on success, negative error code on failure
00149      */
00150     virtual nsapi_error_t gethostbyname(const char *host,
00151             SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC );
00152 
00153     /** Add a domain name server to list of servers to query
00154      *
00155      *  @param address  Destination for the host address
00156      *  @return         0 on success, negative error code on failure
00157      */
00158     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
00159 
00160 protected:
00161 
00162     /** Opens a socket
00163      *
00164      *  Creates a network socket and stores it in the specified handle.
00165      *  The handle must be passed to following calls on the socket.
00166      *
00167      *  A stack may have a finite number of sockets, in this case
00168      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00169      *
00170      *  @param handle   Destination for the handle to a newly created socket
00171      *  @param proto    Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
00172      *  @return         0 on success, negative error code on failure
00173      */
00174     virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto);
00175 
00176     /** Close the socket
00177      *
00178      *  Closes any open connection and deallocates any memory associated
00179      *  with the socket.
00180      *
00181      *  @param handle   Socket handle
00182      *  @return         0 on success, negative error code on failure
00183      */
00184     virtual nsapi_error_t socket_close(nsapi_socket_t handle);
00185 
00186     /** Bind a specific address to a socket
00187      *
00188      *  Binding a socket specifies the address and port on which to recieve
00189      *  data. If the IP address is zeroed, only the port is bound.
00190      *
00191      *  @param handle   Socket handle
00192      *  @param address  Local address to bind
00193      *  @return         0 on success, negative error code on failure.
00194      */
00195     virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address);
00196 
00197     /** Listen for connections on a TCP socket
00198      *
00199      *  Marks the socket as a passive socket that can be used to accept
00200      *  incoming connections.
00201      *
00202      *  @param handle   Socket handle
00203      *  @param backlog  Number of pending connections that can be queued
00204      *                  simultaneously
00205      *  @return         0 on success, negative error code on failure
00206      */
00207     virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog);
00208 
00209     /** Connects TCP socket to a remote host
00210      *
00211      *  Initiates a connection to a remote server specified by the
00212      *  indicated address.
00213      *
00214      *  @param handle   Socket handle
00215      *  @param address  The SocketAddress of the remote host
00216      *  @return         0 on success, negative error code on failure
00217      */
00218     virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address);
00219 
00220     /** Accepts a connection on a TCP socket
00221      *
00222      *  The server socket must be bound and set to listen for connections.
00223      *  On a new connection, creates a network socket and stores it in the
00224      *  specified handle. The handle must be passed to following calls on
00225      *  the socket.
00226      *
00227      *  A stack may have a finite number of sockets, in this case
00228      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00229      *
00230      *  This call is non-blocking. If accept would block,
00231      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00232      *
00233      *  @param server   Socket handle to server to accept from
00234      *  @param handle   Destination for a handle to the newly created socket
00235      *  @param address  Destination for the remote address or NULL
00236      *  @return         0 on success, negative error code on failure
00237      */
00238     virtual nsapi_error_t socket_accept(nsapi_socket_t server,
00239                                         nsapi_socket_t *handle, SocketAddress *address=0);
00240 
00241     /** Send data over a TCP socket
00242      *
00243      *  The socket must be connected to a remote host. Returns the number of
00244      *  bytes sent from the buffer.
00245      *
00246      *  This call is non-blocking. If send would block,
00247      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00248      *
00249      *  @param handle   Socket handle
00250      *  @param data     Buffer of data to send to the host
00251      *  @param size     Size of the buffer in bytes
00252      *  @return         Number of sent bytes on success, negative error
00253      *                  code on failure
00254      */
00255     virtual nsapi_size_or_error_t socket_send(nsapi_socket_t handle,
00256                                               const void *data, nsapi_size_t size);
00257 
00258     /** Receive data over a TCP socket
00259      *
00260      *  The socket must be connected to a remote host. Returns the number of
00261      *  bytes received into the buffer.
00262      *
00263      *  This call is non-blocking. If recv would block,
00264      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00265      *
00266      *  @param handle   Socket handle
00267      *  @param data     Destination buffer for data received from the host
00268      *  @param size     Size of the buffer in bytes
00269      *  @return         Number of received bytes on success, negative error
00270      *                  code on failure
00271      */
00272     virtual nsapi_size_or_error_t socket_recv(nsapi_socket_t handle,
00273                                               void *data, nsapi_size_t size);
00274 
00275     /** Send a packet over a UDP socket
00276      *
00277      *  Sends data to the specified address. Returns the number of bytes
00278      *  sent from the buffer.
00279      *
00280      *  This call is non-blocking. If sendto would block,
00281      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00282      *
00283      *  @param handle   Socket handle
00284      *  @param address  The SocketAddress of the remote host
00285      *  @param data     Buffer of data to send to the host
00286      *  @param size     Size of the buffer in bytes
00287      *  @return         Number of sent bytes on success, negative error
00288      *                  code on failure
00289      */
00290     virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address,
00291                                                 const void *data, nsapi_size_t size);
00292 
00293     /** Receive a packet over a UDP socket
00294      *
00295      *  Receives data and stores the source address in address if address
00296      *  is not NULL. Returns the number of bytes received into the buffer.
00297      *
00298      *  This call is non-blocking. If recvfrom would block,
00299      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00300      *
00301      *  @param handle   Socket handle
00302      *  @param address  Destination for the source address or NULL
00303      *  @param buffer   Destination buffer for data received from the host
00304      *  @param size     Size of the buffer in bytes
00305      *  @return         Number of received bytes on success, negative error
00306      *                  code on failure
00307      */
00308     virtual nsapi_size_or_error_t socket_recvfrom(nsapi_socket_t handle, SocketAddress *address,
00309                                                   void *buffer, nsapi_size_t size);
00310 
00311     /** Register a callback on state change of the socket
00312      *
00313      *  The specified callback will be called on state changes such as when
00314      *  the socket can recv/send/accept successfully and on when an error
00315      *  occurs. The callback may also be called spuriously without reason.
00316      *
00317      *  The callback may be called in an interrupt context and should not
00318      *  perform expensive operations such as recv/send calls.
00319      *
00320      *  @param handle   Socket handle
00321      *  @param callback Function to call on state change
00322      *  @param data     Argument to pass to callback
00323      */
00324     virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data);
00325 
00326     /*  Set stack-specific socket options
00327      *
00328      *  The setsockopt allow an application to pass stack-specific hints
00329      *  to the underlying stack. For unsupported options,
00330      *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
00331      *
00332      *  @param handle   Socket handle
00333      *  @param level    Stack-specific protocol level
00334      *  @param optname  Stack-specific option identifier
00335      *  @param optval   Option value
00336      *  @param optlen   Length of the option value
00337      *  @return         0 on success, negative error code on failure
00338      */
00339     virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
00340                                      int optname, const void *optval, unsigned optlen);
00341 
00342     /*  Get stack-specific socket options
00343      *
00344      *  The getstackopt allow an application to retrieve stack-specific hints
00345      *  from the underlying stack. For unsupported options,
00346      *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
00347      *
00348      *  @param handle   Socket handle
00349      *  @param level    Stack-specific protocol level
00350      *  @param optname  Stack-specific option identifier
00351      *  @param optval   Destination for option value
00352      *  @param optlen   Length of the option value
00353      *  @return         0 on success, negative error code on failure
00354      */
00355     virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
00356                                      int optname, void *optval, unsigned *optlen);
00357 
00358 private:
00359 
00360     /** Call in callback
00361       *
00362       *  Callback is used to call the call in method of the network stack.
00363       */
00364     typedef mbed::Callback<nsapi_error_t (int delay_ms, mbed::Callback<void()> user_cb)> call_in_callback_cb_t;
00365 
00366     /** Get a call in callback
00367      *
00368      *  Get a call in callback from the network stack context.
00369      *
00370      *  Callback should not take more than 10ms to execute, otherwise it might
00371      *  prevent underlying thread processing. A portable user of the callback
00372      *  should not make calls to network operations due to stack size limitations.
00373      *  The callback should not perform expensive operations such as socket recv/send
00374      *  calls or blocking operations.
00375      *
00376      *  @return         Call in callback
00377      */
00378     virtual call_in_callback_cb_t get_call_in_callback();
00379 
00380     /** Call a callback after a delay
00381      *
00382      *  Call a callback from the network stack context after a delay. If function
00383      *  returns error callback will not be called.
00384      *
00385      *  @param delay    Delay in milliseconds
00386      *  @param func     Callback to be called
00387      *  @return         0 on success, negative error code on failure
00388      */
00389     virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
00390 
00391     Interface *m_interface;
00392 };
00393 
00394 #endif /* EMAC_TEST_NETWORK_STACK_H */
00395 
00396 #endif