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