NanostackInterface.h

00001 /*
00002  * Copyright (c) 2016 ARM Limited. All rights reserved.
00003  */
00004 
00005 #ifndef NANOSTACK_INTERFACE_H_
00006 #define NANOSTACK_INTERFACE_H_
00007 
00008 #include "NetworkStack.h"
00009 #include "MeshInterface.h"
00010 #include "NanostackRfPhy.h"
00011 
00012 #include "mbed-mesh-api/Mesh6LoWPAN_ND.h"
00013 #include "mbed-mesh-api/MeshThread.h"
00014 
00015 class NanostackInterface : public NetworkStack {
00016 public:
00017     static NanostackInterface *get_stack();
00018 
00019 protected:
00020 
00021     /** Get the local IP address
00022      *
00023      *  @return         Null-terminated representation of the local IP address
00024      *                  or null if not yet connected
00025      */
00026     virtual const char *get_ip_address();
00027 
00028     /** Opens a socket
00029      *
00030      *  Creates a network socket and stores it in the specified handle.
00031      *  The handle must be passed to following calls on the socket.
00032      *
00033      *  A stack may have a finite number of sockets, in this case
00034      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00035      *
00036      *  @param handle   Destination for the handle to a newly created socket
00037      *  @param proto    Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
00038      *  @return         0 on success, negative error code on failure
00039      */
00040     virtual nsapi_error_t socket_open(void **handle, nsapi_protocol_t proto);
00041 
00042     /** Close the socket
00043      *
00044      *  Closes any open connection and deallocates any memory associated
00045      *  with the socket.
00046      *
00047      *  @param handle   Socket handle
00048      *  @return         0 on success, negative error code on failure
00049      */
00050     virtual nsapi_error_t socket_close(void *handle);
00051 
00052     /** Bind a specific address to a socket
00053      *
00054      *  Binding a socket specifies the address and port on which to recieve
00055      *  data. If the IP address is zeroed, only the port is bound.
00056      *
00057      *  @param handle   Socket handle
00058      *  @param address  Local address to bind
00059      *  @return         0 on success, negative error code on failure.
00060      */
00061     virtual nsapi_error_t socket_bind(void *handle, const SocketAddress &address);
00062 
00063     /** Listen for connections on a TCP socket
00064      *
00065      *  Marks the socket as a passive socket that can be used to accept
00066      *  incoming connections.
00067      *
00068      *  @param handle   Socket handle
00069      *  @param backlog  Number of pending connections that can be queued
00070      *                  simultaneously
00071      *  @return         0 on success, negative error code on failure
00072      */
00073     virtual nsapi_error_t socket_listen(void *handle, int backlog);
00074 
00075     /** Connects TCP socket to a remote host
00076      *
00077      *  Initiates a connection to a remote server specified by the
00078      *  indicated address.
00079      *
00080      *  @param handle   Socket handle
00081      *  @param address  The SocketAddress of the remote host
00082      *  @return         0 on success, negative error code on failure
00083      */
00084     virtual nsapi_error_t socket_connect(void *handle, const SocketAddress &address);
00085 
00086     /** Accepts a connection on a TCP socket
00087      *
00088      *  The server socket must be bound and set to listen for connections.
00089      *  On a new connection, creates a network socket and stores it in the
00090      *  specified handle. The handle must be passed to following calls on
00091      *  the socket.
00092      *
00093      *  A stack may have a finite number of sockets, in this case
00094      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
00095      *
00096      *  This call is non-blocking. If accept would block,
00097      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00098      *
00099      *  @param server   Socket handle to server to accept from
00100      *  @param handle   Destination for a handle to the newly created socket
00101      *  @param address  Destination for the remote address or NULL
00102      *  @return         0 on success, negative error code on failure
00103      */
00104     virtual nsapi_error_t socket_accept(void *handle, void **server, SocketAddress *address);
00105 
00106     /** Send data over a TCP socket
00107      *
00108      *  The socket must be connected to a remote host. Returns the number of
00109      *  bytes sent from the buffer.
00110      *
00111      *  This call is non-blocking. If send would block,
00112      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00113      *
00114      *  @param handle   Socket handle
00115      *  @param data     Buffer of data to send to the host
00116      *  @param size     Size of the buffer in bytes
00117      *  @return         Number of sent bytes on success, negative error
00118      *                  code on failure
00119      */
00120     virtual nsapi_size_or_error_t socket_send(void *handle, const void *data, nsapi_size_t size);
00121 
00122     /** Receive data over a TCP socket
00123      *
00124      *  The socket must be connected to a remote host. Returns the number of
00125      *  bytes received into the buffer.
00126      *
00127      *  This call is non-blocking. If recv would block,
00128      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00129      *
00130      *  @param handle   Socket handle
00131      *  @param data     Destination buffer for data received from the host
00132      *  @param size     Size of the buffer in bytes
00133      *  @return         Number of received bytes on success, negative error
00134      *                  code on failure
00135      */
00136     virtual nsapi_size_or_error_t socket_recv(void *handle, void *data, nsapi_size_t size);
00137 
00138     /** Send a packet over a UDP socket
00139      *
00140      *  Sends data to the specified address. Returns the number of bytes
00141      *  sent from the buffer.
00142      *
00143      *  This call is non-blocking. If sendto would block,
00144      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00145      *
00146      *  @param handle   Socket handle
00147      *  @param address  The SocketAddress of the remote host
00148      *  @param data     Buffer of data to send to the host
00149      *  @param size     Size of the buffer in bytes
00150      *  @return         Number of sent bytes on success, negative error
00151      *                  code on failure
00152      */
00153     virtual nsapi_size_or_error_t socket_sendto(void *handle, const SocketAddress &address, const void *data, nsapi_size_t size);
00154 
00155     /** Receive a packet over a UDP socket
00156      *
00157      *  Receives data and stores the source address in address if address
00158      *  is not NULL. Returns the number of bytes received into the buffer.
00159      *
00160      *  This call is non-blocking. If recvfrom would block,
00161      *  NSAPI_ERROR_WOULD_BLOCK is returned immediately.
00162      *
00163      *  @param handle   Socket handle
00164      *  @param address  Destination for the source address or NULL
00165      *  @param data     Destination buffer for data received from the host
00166      *  @param size     Size of the buffer in bytes
00167      *  @return         Number of received bytes on success, negative error
00168      *                  code on failure
00169      */
00170     virtual nsapi_size_or_error_t socket_recvfrom(void *handle, SocketAddress *address, void *buffer, nsapi_size_t size);
00171 
00172     /** Register a callback on state change of the socket
00173      *
00174      *  The specified callback will be called on state changes such as when
00175      *  the socket can recv/send/accept successfully and on when an error
00176      *  occurs. The callback may also be called spuriously without reason.
00177      *
00178      *  The callback may be called in an interrupt context and should not
00179      *  perform expensive operations such as recv/send calls.
00180      *
00181      *  @param handle   Socket handle
00182      *  @param callback Function to call on state change
00183      *  @param data     Argument to pass to callback
00184      */
00185     virtual void socket_attach(void *handle, void (*callback)(void *), void *data);
00186 
00187     /*  Set stack-specific socket options
00188      *
00189      *  The setsockopt allow an application to pass stack-specific hints
00190      *  to the underlying stack. For unsupported options,
00191      *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
00192      *
00193      *  @param handle   Socket handle
00194      *  @param level    Stack-specific protocol level
00195      *  @param optname  Stack-specific option identifier
00196      *  @param optval   Option value
00197      *  @param optlen   Length of the option value
00198      *  @return         0 on success, negative error code on failure
00199      */
00200     virtual nsapi_error_t setsockopt(void *handle, int level, int optname, const void *optval, unsigned optlen);
00201 
00202     /*  Get stack-specific socket options
00203      *
00204      *  The getstackopt allow an application to retrieve stack-specific hints
00205      *  from the underlying stack. For unsupported options,
00206      *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
00207      *
00208      *  @param handle   Socket handle
00209      *  @param level    Stack-specific protocol level
00210      *  @param optname  Stack-specific option identifier
00211      *  @param optval   Destination for option value
00212      *  @param optlen   Length of the option value
00213      *  @return         0 on success, negative error code on failure
00214      */
00215     virtual nsapi_error_t getsockopt(void *handle, int level, int optname, void *optval, unsigned *optlen);
00216 
00217 private:
00218     static NanostackInterface * _ns_interface;
00219 };
00220 
00221 class MeshInterfaceNanostack : public MeshInterface {
00222 public:
00223 
00224     /** Attach phy and initialize the mesh
00225      *
00226      *  Initializes a mesh interface on the given phy. Not needed if
00227      *  the phy is passed to the mesh's constructor.
00228      *
00229      *  @return     0 on success, negative on failure
00230      */
00231     virtual nsapi_error_t initialize(NanostackRfPhy *phy);
00232 
00233     /** Start the interface
00234      *
00235      *  @return     0 on success, negative on failure
00236      */
00237     virtual nsapi_error_t connect() = 0;
00238 
00239     /** Stop the interface
00240      *
00241      *  @return     0 on success, negative on failure
00242      */
00243     virtual nsapi_error_t disconnect();
00244 
00245     /** Get the internally stored IP address
00246     /return     IP address of the interface or null if not yet connected
00247     */
00248     virtual const char *get_ip_address();
00249 
00250     /** Get the internally stored MAC address
00251     /return     MAC address of the interface
00252     */
00253     virtual const char *get_mac_address();
00254 
00255 protected:
00256     MeshInterfaceNanostack();
00257     MeshInterfaceNanostack(NanostackRfPhy *phy);
00258     nsapi_error_t register_rf();
00259     nsapi_error_t actual_connect();
00260     virtual NetworkStack * get_stack(void);
00261 
00262     void mesh_network_handler(mesh_connection_status_t status);
00263     NanostackRfPhy *phy;
00264     AbstractMesh *mesh_api;
00265     int8_t rf_device_id;
00266     uint8_t eui64[8];
00267     char ip_addr_str[40];
00268     char mac_addr_str[24];
00269     Semaphore connect_semaphore;
00270 };
00271 
00272 class LoWPANNDInterface : public MeshInterfaceNanostack {
00273 public:
00274 
00275     /** Create an uninitialized LoWPANNDInterface
00276      *
00277      *  Must initialize to initialize the mesh on a phy.
00278      */
00279     LoWPANNDInterface() : MeshInterfaceNanostack() {
00280 
00281     }
00282 
00283     /** Create an initialized MeshInterface
00284      *
00285      */
00286     LoWPANNDInterface(NanostackRfPhy *phy) : MeshInterfaceNanostack(phy) {
00287 
00288     }
00289 
00290     nsapi_error_t connect();
00291 protected:
00292     Mesh6LoWPAN_ND *get_mesh_api() const { return static_cast<Mesh6LoWPAN_ND *>(mesh_api); }
00293 private:
00294 
00295 };
00296 
00297 class ThreadInterface : public MeshInterfaceNanostack {
00298 public:
00299 
00300     /** Create an uninitialized LoWPANNDInterface
00301      *
00302      *  Must initialize to initialize the mesh on a phy.
00303      */
00304     ThreadInterface() : MeshInterfaceNanostack() {
00305 
00306     }
00307 
00308     /** Create an initialized MeshInterface
00309      *
00310      */
00311     ThreadInterface(NanostackRfPhy *phy) : MeshInterfaceNanostack(phy) {
00312 
00313     }
00314 
00315     nsapi_error_t connect();
00316 protected:
00317     MeshThread *get_mesh_api() const { return static_cast<MeshThread *>(mesh_api); }
00318 private:
00319 
00320 };
00321 
00322 
00323 #endif /* NANOSTACK_INTERFACE_H_ */