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 the socket.
00036      *
00037      *  @note Closes socket if it's still open.
00038      */
00039     virtual ~InternetSocket();
00040 
00041     /** Open a network socket on the network stack of the given
00042      *  network interface.
00043      *
00044      *  @note Not needed if stack is passed to the socket's constructor.
00045      *
00046      *  @param stack    Network stack as target for socket.
00047      *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
00048      */
00049     nsapi_error_t open(NetworkStack *stack);
00050 
00051 #if !defined(DOXYGEN_ONLY)
00052     template <typename S>
00053     nsapi_error_t open(S *stack)
00054     {
00055         return open(nsapi_create_stack(stack));
00056     }
00057 #endif //!defined(DOXYGEN_ONLY)
00058 
00059     /** Close any open connection, and deallocate any memory associated
00060      *  with the socket. Called from destructor if socket is not closed.
00061      *
00062      *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
00063      */
00064     virtual nsapi_error_t close();
00065 
00066     /** Subscribe to an IP multicast group.
00067      *
00068      * @param address   Multicast group IP address.
00069      *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
00070      */
00071     int join_multicast_group(const SocketAddress &address);
00072 
00073     /** Leave an IP multicast group.
00074      *
00075      * @param address   Multicast group IP address.
00076      *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
00077      */
00078     int leave_multicast_group(const SocketAddress &address);
00079 
00080     /** Bind the socket to a port on which to receive data.
00081      *
00082      *  @param port     Local port to bind.
00083      *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
00084      */
00085     nsapi_error_t bind(uint16_t port);
00086 
00087     /** Bind the socket to a specific address and port on which to receive
00088      *  data. If the IP address is zeroed, only the port is bound.
00089      *
00090      *  @param address  Null-terminated local address to bind.
00091      *  @param port     Local port to bind.
00092      *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
00093      */
00094     nsapi_error_t bind(const char *address, uint16_t port);
00095 
00096     /** @copydoc Socket::bind
00097      */
00098     virtual nsapi_error_t bind(const SocketAddress &address);
00099 
00100     /** @copydoc Socket::set_blocking
00101      */
00102     virtual void set_blocking (bool blocking);
00103 
00104     /** @copydoc Socket::set_timeout
00105      */
00106     virtual void set_timeout (int timeout);
00107 
00108     /** @copydoc Socket::setsockopt
00109      */
00110     virtual nsapi_error_t setsockopt (int level, int optname, const void *optval, unsigned optlen);
00111 
00112     /** @copydoc Socket::getsockopt
00113      */
00114     virtual nsapi_error_t getsockopt (int level, int optname, void *optval, unsigned *optlen);
00115 
00116     /** @copydoc Socket::sigio
00117      */
00118     virtual void sigio (mbed::Callback<void()> func);
00119 
00120     /** Register a callback on state change of the socket.
00121      *
00122      *  @see Socket::sigio
00123      *  @deprecated
00124      *      The behavior of Socket::attach differs from other attach functions in
00125      *      Mbed OS and has been known to cause confusion. Replaced by Socket::sigio.
00126      */
00127     MBED_DEPRECATED_SINCE("mbed-os-5.4",
00128                           "The behavior of Socket::attach differs from other attach functions in "
00129                           "Mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
00130     void attach(mbed::Callback<void()> func);
00131 
00132     /** Register a callback on state change of the socket.
00133      *
00134      *  @see Socket::sigio
00135      *  @deprecated
00136      *      The attach function does not support cv-qualifiers. Replaced by
00137      *      attach(callback(obj, method)).
00138      */
00139     template <typename T, typename M>
00140     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00141                           "The attach function does not support cv-qualifiers. Replaced by "
00142                           "attach(callback(obj, method)).")
00143     void attach(T *obj, M method)
00144     {
00145         attach(mbed::callback(obj, method));
00146     }
00147 
00148 #if !defined(DOXYGEN_ONLY)
00149 
00150 protected:
00151     InternetSocket();
00152     virtual nsapi_protocol_t get_proto() = 0;
00153     virtual void event();
00154     int modify_multicast_group(const SocketAddress &address, nsapi_socket_option_t socketopt);
00155 
00156     NetworkStack *_stack;
00157     nsapi_socket_t _socket;
00158     uint32_t _timeout;
00159     mbed::Callback<void()> _event;
00160     mbed::Callback<void()> _callback;
00161     rtos::EventFlags _event_flag;
00162     rtos::Mutex _lock;
00163     SocketAddress _remote_peer;
00164     uint8_t _readers;
00165     uint8_t _writers;
00166     volatile unsigned _pending;
00167     bool _factory_allocated;
00168 
00169     // Event flags
00170     static const int READ_FLAG     = 0x1u;
00171     static const int WRITE_FLAG    = 0x2u;
00172     static const int FINISHED_FLAG = 0x3u;
00173 
00174 #endif //!defined(DOXYGEN_ONLY)
00175 };
00176 
00177 #endif // INTERNETSOCKET_H
00178 
00179 /** @}*/