Socket.h

00001 /* Socket
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 SOCKET_H
00018 #define SOCKET_H
00019 
00020 #include "network-socket/SocketAddress.h"
00021 #include "network-socket/NetworkStack.h"
00022 #include "rtos/Mutex.h"
00023 #include "Callback.h"
00024 #include "toolchain.h"
00025 
00026 
00027 /** Abstract socket class
00028  */
00029 class Socket {
00030 public:
00031     /** Destroy a socket
00032      *
00033      *  Closes socket if the socket is still open
00034      */
00035     virtual ~Socket() {}
00036 
00037     /** Opens a socket
00038      *
00039      *  Creates a network socket on the network stack of the given
00040      *  network interface. Not needed if stack is passed to the
00041      *  socket's constructor.
00042      *
00043      *  @param stack    Network stack as target for socket
00044      *  @return         0 on success, negative error code on failure
00045      */
00046     int open(NetworkStack *stack);
00047 
00048     template <typename S>
00049     int open(S *stack) {
00050         return open(nsapi_create_stack(stack));
00051     }
00052     
00053     /** Close the socket
00054      *
00055      *  Closes any open connection and deallocates any memory associated
00056      *  with the socket. Called from destructor if socket is not closed.
00057      *
00058      *  @return         0 on success, negative error code on failure
00059      */
00060     int close();
00061     
00062     /** Bind a specific address to a socket
00063      *
00064      *  Binding a socket specifies the address and port on which to recieve
00065      *  data.
00066      *
00067      *  @param port     Local port to bind
00068      *  @return         0 on success, negative error code on failure.
00069      */
00070     int bind(uint16_t port);
00071 
00072     /** Bind a specific address to a socket
00073      *
00074      *  Binding a socket specifies the address and port on which to recieve
00075      *  data. If the IP address is zeroed, only the port is bound.
00076      *
00077      *  @param address  Null-terminated local address to bind
00078      *  @param port     Local port to bind
00079      *  @return         0 on success, negative error code on failure.
00080      */
00081     int bind(const char *address, uint16_t port);
00082 
00083     /** Bind a specific address to a socket
00084      *
00085      *  Binding a socket specifies the address and port on which to recieve
00086      *  data. If the IP address is zeroed, only the port is bound.
00087      *
00088      *  @param address  Local address to bind
00089      *  @return         0 on success, negative error code on failure.
00090      */
00091     int bind(const SocketAddress &address);
00092     
00093     /** Set blocking or non-blocking mode of the socket
00094      *
00095      *  Initially all sockets are in blocking mode. In non-blocking mode
00096      *  blocking operations such as send/recv/accept return
00097      *  NSAPI_ERROR_WOULD_BLOCK if they can not continue.
00098      *
00099      *  set_blocking(false) is equivalent to set_timeout(-1)
00100      *  set_blocking(true) is equivalent to set_timeout(0)
00101      *
00102      *  @param blocking true for blocking mode, false for non-blocking mode.
00103      */
00104     void set_blocking(bool blocking);
00105     
00106     /** Set timeout on blocking socket operations
00107      *
00108      *  Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
00109      *  is returned if a blocking operation takes longer than the specified
00110      *  timeout. A timeout of 0 removes the timeout from the socket. A negative
00111      *  value give the socket an unbounded timeout.
00112      *
00113      *  set_timeout(0) is equivalent to set_blocking(false)
00114      *  set_timeout(-1) is equivalent to set_blocking(true)
00115      *
00116      *  @param timeout  Timeout in milliseconds
00117      */
00118     void set_timeout(int timeout);
00119 
00120     /*  Set stack-specific socket options
00121      *
00122      *  The setsockopt allow an application to pass stack-specific hints
00123      *  to the underlying stack. For unsupported options,
00124      *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
00125      *
00126      *  @param level    Stack-specific protocol level
00127      *  @param optname  Stack-specific option identifier
00128      *  @param optval   Option value
00129      *  @param optlen   Length of the option value
00130      *  @return         0 on success, negative error code on failure
00131      */    
00132     int setsockopt(int level, int optname, const void *optval, unsigned optlen);
00133 
00134     /*  Get stack-specific socket options
00135      *
00136      *  The getstackopt allow an application to retrieve stack-specific hints
00137      *  from the underlying stack. For unsupported options,
00138      *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
00139      *
00140      *  @param level    Stack-specific protocol level
00141      *  @param optname  Stack-specific option identifier
00142      *  @param optval   Destination for option value
00143      *  @param optlen   Length of the option value
00144      *  @return         0 on success, negative error code on failure
00145      */    
00146     int getsockopt(int level, int optname, void *optval, unsigned *optlen);
00147 
00148     /** Register a callback on state change of the socket
00149      *
00150      *  The specified callback will be called on state changes such as when
00151      *  the socket can recv/send/accept successfully and on when an error
00152      *  occurs. The callback may also be called spuriously without reason.
00153      *
00154      *  The callback may be called in an interrupt context and should not
00155      *  perform expensive operations such as recv/send calls.
00156      *
00157      *  @param func     Function to call on state change
00158      */
00159     void attach(mbed::Callback<void()> func);
00160 
00161     /** Register a callback on state change of the socket
00162      *
00163      *  The specified callback will be called on state changes such as when
00164      *  the socket can recv/send/accept successfully and on when an error
00165      *  occurs. The callback may also be called spuriously without reason.
00166      *
00167      *  The callback may be called in an interrupt context and should not
00168      *  perform expensive operations such as recv/send calls.
00169      *
00170      *  @param obj      Pointer to object to call method on
00171      *  @param method   Method to call on state change
00172      *
00173      *  @deprecated
00174      *      The attach function does not support cv-qualifiers. Replaced by
00175      *      attach(callback(obj, method)).
00176      */
00177     template <typename T, typename M>
00178     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00179         "The attach function does not support cv-qualifiers. Replaced by "
00180         "attach(callback(obj, method)).")
00181     void attach(T *obj, M method) {
00182         attach(mbed::callback(obj, method));
00183     }
00184 
00185 protected:
00186     Socket();
00187     virtual nsapi_protocol_t get_proto() = 0;
00188     virtual void event() = 0;
00189 
00190     NetworkStack *_stack;
00191     nsapi_socket_t _socket;
00192     uint32_t _timeout;
00193     mbed::Callback<void()> _event;
00194     mbed::Callback<void()> _callback;
00195     rtos::Mutex _lock;
00196 };
00197 
00198 
00199 #endif