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