InternetSocket.h

00001 
00002 /** \addtogroup netsocket */
00003 /** @{*/
00004 /* Socket
00005  * Copyright (c) 2015 ARM Limited
00006  *
00007  * Licensed under the Apache License, Version 2.0 (the "License");
00008  * you may not use this file except in compliance with the License.
00009  * You may obtain a copy of the License at
00010  *
00011  *     http://www.apache.org/licenses/LICENSE-2.0
00012  *
00013  * Unless required by applicable law or agreed to in writing, software
00014  * distributed under the License is distributed on an "AS IS" BASIS,
00015  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016  * See the License for the specific language governing permissions and
00017  * limitations under the License.
00018  */
00019 
00020 #ifndef INTERNETSOCKET_H
00021 #define INTERNETSOCKET_H
00022 
00023 #include "netsocket/Socket.h"
00024 #include "netsocket/NetworkStack.h"
00025 #include "rtos/Mutex.h"
00026 #include "rtos/EventFlags.h"
00027 #include "Callback.h"
00028 #include "mbed_toolchain.h"
00029 
00030 /** Socket implementation that uses IP network stack.
00031  * Not to be directly used by applications. Cannot be directly instantiated.
00032  */
00033 class InternetSocket : public Socket {
00034 public:
00035     /** Destroy a socket
00036      *
00037      *  Closes socket if the socket is still open
00038      */
00039     virtual ~InternetSocket() {}
00040 
00041     /** Opens a socket
00042      *
00043      *  Creates a network socket on the network stack of the given
00044      *  network interface. Not needed if stack is passed to the
00045      *  socket's constructor.
00046      *
00047      *  @param stack    Network stack as target for socket
00048      *  @return         0 on success, negative error code on failure
00049      */
00050     nsapi_error_t open(NetworkStack *stack);
00051 
00052     template <typename S>
00053     nsapi_error_t open(S *stack)
00054     {
00055         return open(nsapi_create_stack(stack));
00056     }
00057 
00058     /** Close the socket
00059      *
00060      *  Closes any open connection and deallocates any memory associated
00061      *  with the socket. Called from destructor if socket is not closed.
00062      *
00063      *  @return         0 on success, negative error code on failure
00064      */
00065     virtual nsapi_error_t close();
00066 
00067     /** Subscribes to an IP multicast group
00068      *
00069      * @param address   Multicast group IP address
00070      * @return          Negative error code on failure
00071      */
00072     int join_multicast_group(const SocketAddress &address);
00073 
00074     /** Leave an IP multicast group
00075      *
00076      * @param address   Multicast group IP address
00077      * @return          Negative error code on failure
00078      */
00079     int leave_multicast_group(const SocketAddress &address);
00080 
00081 
00082     /** Bind a specific address to a socket
00083      *
00084      *  Binding a socket specifies the address and port on which to receive
00085      *  data.
00086      *
00087      *  @param port     Local port to bind
00088      *  @return         0 on success, negative error code on failure.
00089      */
00090     nsapi_error_t bind(uint16_t port);
00091 
00092     /** Bind a specific address to a socket
00093      *
00094      *  Binding a socket specifies the address and port on which to receive
00095      *  data. If the IP address is zeroed, only the port is bound.
00096      *
00097      *  @param address  Null-terminated local address to bind
00098      *  @param port     Local port to bind
00099      *  @return         0 on success, negative error code on failure.
00100      */
00101     nsapi_error_t bind(const char *address, uint16_t port);
00102 
00103     /** Bind a specific address to a socket
00104      *
00105      *  Binding a socket specifies the address and port on which to receive
00106      *  data. If the IP address is zeroed, only the port is bound.
00107      *
00108      *  @param address  Local address to bind
00109      *  @return         0 on success, negative error code on failure.
00110      */
00111     virtual nsapi_error_t bind(const SocketAddress &address);
00112 
00113     /** Set blocking or non-blocking mode of the socket
00114      *
00115      *  Initially all sockets are in blocking mode. In non-blocking mode
00116      *  blocking operations such as send/recv/accept return
00117      *  NSAPI_ERROR_WOULD_BLOCK if they can not continue.
00118      *
00119      *  set_blocking(false) is equivalent to set_timeout(-1)
00120      *  set_blocking(true) is equivalent to set_timeout(0)
00121      *
00122      *  @param blocking true for blocking mode, false for non-blocking mode.
00123      */
00124     virtual void set_blocking(bool blocking);
00125 
00126     /** Set timeout on blocking socket operations
00127      *
00128      *  Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
00129      *  is returned if a blocking operation takes longer than the specified
00130      *  timeout. A timeout of 0 removes the timeout from the socket. A negative
00131      *  value give the socket an unbounded timeout.
00132      *
00133      *  set_timeout(0) is equivalent to set_blocking(false)
00134      *  set_timeout(-1) is equivalent to set_blocking(true)
00135      *
00136      *  @param timeout  Timeout in milliseconds
00137      */
00138     virtual void set_timeout(int timeout);
00139 
00140     /*  Set socket options
00141      *
00142      *  setsockopt allows an application to pass stack-specific options
00143      *  to the underlying stack using stack-specific level and option names,
00144      *  or to request generic options using levels from nsapi_socket_level_t.
00145      *
00146      *  For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
00147      *  and the socket is unmodified.
00148      *
00149      *  @param level    Stack-specific protocol level or nsapi_socket_level_t
00150      *  @param optname  Level-specific option name
00151      *  @param optval   Option value
00152      *  @param optlen   Length of the option value
00153      *  @return         0 on success, negative error code on failure
00154      */
00155     virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);
00156 
00157     /*  Get socket options
00158      *
00159      *  getsockopt allows an application to retrieve stack-specific options
00160      *  from the underlying stack using stack-specific level and option names,
00161      *  or to request generic options using levels from nsapi_socket_level_t.
00162      *
00163      *  For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
00164      *  and the socket is unmodified.
00165      *
00166      *  @param level    Stack-specific protocol level or nsapi_socket_level_t
00167      *  @param optname  Level-specific option name
00168      *  @param optval   Destination for option value
00169      *  @param optlen   Length of the option value
00170      *  @return         0 on success, negative error code on failure
00171      */
00172     virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen);
00173 
00174     /** Register a callback on state change of the socket
00175      *
00176      *  The specified callback will be called on state changes such as when
00177      *  the socket can recv/send/accept successfully and on when an error
00178      *  occurs. The callback may also be called spuriously without reason.
00179      *
00180      *  The callback may be called in an interrupt context and should not
00181      *  perform expensive operations such as recv/send calls.
00182      *
00183      *  Note! This is not intended as a replacement for a poll or attach-like
00184      *  asynchronous api, but rather as a building block for constructing
00185      *  such functionality. The exact timing of when the registered function
00186      *  is called is not guaranteed and susceptible to change.
00187      *
00188      *  @param func     Function to call on state change
00189      */
00190     virtual void sigio(mbed::Callback<void()> func);
00191 
00192     /** Register a callback on state change of the socket
00193      *
00194      *  @see Socket::sigio
00195      *  @deprecated
00196      *      The behaviour of Socket::attach differs from other attach functions in
00197      *      mbed OS and has been known to cause confusion. Replaced by Socket::sigio.
00198      */
00199     MBED_DEPRECATED_SINCE("mbed-os-5.4",
00200                           "The behaviour of Socket::attach differs from other attach functions in "
00201                           "mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
00202     void attach(mbed::Callback<void()> func);
00203 
00204     /** Register a callback on state change of the socket
00205      *
00206      *  @see Socket::sigio
00207      *  @deprecated
00208      *      The attach function does not support cv-qualifiers. Replaced by
00209      *      attach(callback(obj, method)).
00210      */
00211     template <typename T, typename M>
00212     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00213                           "The attach function does not support cv-qualifiers. Replaced by "
00214                           "attach(callback(obj, method)).")
00215     void attach(T *obj, M method)
00216     {
00217         attach(mbed::callback(obj, method));
00218     }
00219 
00220 protected:
00221     InternetSocket();
00222     virtual nsapi_protocol_t get_proto() = 0;
00223     virtual void event();
00224     int modify_multicast_group(const SocketAddress &address, nsapi_socket_option_t socketopt);
00225 
00226     NetworkStack *_stack;
00227     nsapi_socket_t _socket;
00228     uint32_t _timeout;
00229     mbed::Callback<void()> _event;
00230     mbed::Callback<void()> _callback;
00231     rtos::EventFlags _event_flag;
00232     rtos::Mutex _lock;
00233     SocketAddress _remote_peer;
00234     uint8_t _readers;
00235     uint8_t _writers;
00236     volatile unsigned _pending;
00237     bool _factory_allocated;
00238 
00239     // Event flags
00240     static const int READ_FLAG     = 0x1u;
00241     static const int WRITE_FLAG    = 0x2u;
00242     static const int FINISHED_FLAG = 0x3u;
00243 };
00244 
00245 #endif // INTERNETSOCKET_H
00246 
00247 /** @}*/