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_atomic.h"
00029 #include "mbed_toolchain.h"
00030 #include "SocketStats.h"
00031 
00032 /** Socket implementation that uses IP network stack.
00033  * Not to be directly used by applications. Cannot be directly instantiated.
00034  */
00035 class InternetSocket : public Socket {
00036 public:
00037     /** Destroy the socket.
00038      *
00039      *  @note Closes socket if it's still open.
00040      */
00041     virtual ~InternetSocket();
00042 
00043     /** Open a network socket on the network stack of the given
00044      *  network interface.
00045      *
00046      *  @note Not needed if stack is passed to the socket's constructor.
00047      *
00048      *  @param stack    Network stack as target for socket.
00049      *  @retval         NSAPI_ERROR_OK on success.
00050      *  @retval         NSAPI_ERROR_PARAMETER in case the provided stack was invalid
00051      *                  or a stack was already created and socket opened successfully.
00052      *  @retval         int negative error codes for stack-related failures.
00053      *                  See @ref NetworkStack::socket_open.
00054      */
00055     nsapi_error_t open(NetworkStack *stack);
00056 
00057 #if !defined(DOXYGEN_ONLY)
00058     template <typename S>
00059     nsapi_error_t open(S *stack)
00060     {
00061         return open(nsapi_create_stack(stack));
00062     }
00063 #endif //!defined(DOXYGEN_ONLY)
00064 
00065     /** Close any open connection, and deallocate any memory associated
00066      *  with the socket. Called from destructor if socket is not closed.
00067      *
00068      *  @retval         NSAPI_ERROR_OK on success.
00069      *  @retval         NSAPI_ERROR_NO_SOCKET if socket is not open.
00070      *  @retval         int negative error codes for stack-related failures.
00071      *                  See @ref NetworkStack::socket_close.
00072      */
00073     virtual nsapi_error_t close();
00074 
00075     /** Subscribe to an IP multicast group.
00076      *
00077      * @param address   Multicast group IP address.
00078      *  @return         NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt).
00079      */
00080     int join_multicast_group(const SocketAddress &address);
00081 
00082     /** Leave an IP multicast group.
00083      *
00084      * @param address   Multicast group IP address.
00085      *  @return         NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt).
00086      */
00087     int leave_multicast_group(const SocketAddress &address);
00088 
00089     /** Bind the socket to a port on which to receive data.
00090      *
00091      *  @param port     Local port to bind.
00092      *  @retval         NSAPI_ERROR_OK on success.
00093      *  @retval         NSAPI_ERROR_NO_SOCKET if socket is not open.
00094      *  @retval         int negative error codes for stack-related failures.
00095      *                  See @ref NetworkStack::socket_bind.
00096      */
00097     nsapi_error_t bind(uint16_t port);
00098 
00099     /** Bind the socket to a specific address and port on which to receive
00100      *  data. If the IP address is zeroed, only the port is bound.
00101      *
00102      *  @param address  Null-terminated local address to bind.
00103      *  @param port     Local port to bind.
00104      *  @retval         NSAPI_ERROR_OK on success.
00105      *  @retval         NSAPI_ERROR_NO_SOCKET if socket is not open.
00106      *  @retval         int negative error codes for stack-related failures.
00107      *                  See @ref NetworkStack::socket_bind.
00108      */
00109     MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00110     nsapi_error_t bind(const char *address, uint16_t port);
00111 
00112     /** @copydoc Socket::bind
00113      */
00114     virtual nsapi_error_t bind(const SocketAddress &address);
00115 
00116     /** @copydoc Socket::set_blocking
00117      */
00118     virtual void set_blocking (bool blocking);
00119 
00120     /** @copydoc Socket::set_timeout
00121      */
00122     virtual void set_timeout (int timeout);
00123 
00124     /** @copydoc Socket::setsockopt
00125      */
00126     virtual nsapi_error_t setsockopt (int level, int optname, const void *optval, unsigned optlen);
00127 
00128     /** @copydoc Socket::getsockopt
00129      */
00130     virtual nsapi_error_t getsockopt (int level, int optname, void *optval, unsigned *optlen);
00131 
00132     /** @copydoc Socket::sigio
00133      */
00134     virtual void sigio (mbed::Callback<void()> func);
00135 
00136     /** @copydoc Socket::getpeername
00137      */
00138     virtual nsapi_error_t getpeername (SocketAddress *address);
00139 
00140     /** Register a callback on state change of the socket.
00141      *
00142      *  @see Socket::sigio
00143      *  @deprecated
00144      *      The behavior of Socket::attach differs from other attach functions in
00145      *      Mbed OS and has been known to cause confusion. Replaced by Socket::sigio.
00146      */
00147     MBED_DEPRECATED_SINCE("mbed-os-5.4",
00148                           "The behavior of Socket::attach differs from other attach functions in "
00149                           "Mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
00150     void attach(mbed::Callback<void()> func);
00151 
00152     /** Register a callback on state change of the socket.
00153      *
00154      *  @see Socket::sigio
00155      *  @deprecated
00156      *      The attach function does not support cv-qualifiers. Replaced by
00157      *      attach(callback(obj, method)).
00158      */
00159     template <typename T, typename M>
00160     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00161                           "The attach function does not support cv-qualifiers. Replaced by "
00162                           "attach(callback(obj, method)).")
00163     void attach(T *obj, M method)
00164     {
00165         attach(mbed::callback(obj, method));
00166     }
00167 
00168 #if !defined(DOXYGEN_ONLY)
00169 
00170 protected:
00171     InternetSocket();
00172     virtual nsapi_protocol_t get_proto() = 0;
00173     virtual void event();
00174     int modify_multicast_group(const SocketAddress &address, nsapi_socket_option_t socketopt);
00175     char _interface_name[NSAPI_INTERFACE_NAME_MAX_SIZE];
00176     NetworkStack *_stack;
00177     nsapi_socket_t _socket;
00178     uint32_t _timeout;
00179     mbed::Callback<void()> _event;
00180     mbed::Callback<void()> _callback;
00181     rtos::EventFlags _event_flag;
00182     rtos::Mutex _lock;
00183     SocketAddress _remote_peer;
00184     uint8_t _readers;
00185     uint8_t _writers;
00186     core_util_atomic_flag _pending;
00187     bool _factory_allocated;
00188 
00189     // Event flags
00190     static const int READ_FLAG     = 0x1u;
00191     static const int WRITE_FLAG    = 0x2u;
00192     static const int FINISHED_FLAG = 0x3u;
00193 
00194     friend class DTLSSocket;  // Allow DTLSSocket::connect() to do name resolution on the _stack
00195     SocketStats _socket_stats;
00196 
00197 #endif //!defined(DOXYGEN_ONLY)
00198 };
00199 
00200 #endif // INTERNETSOCKET_H
00201 
00202 /** @}*/