Mistake on this page?
Report an issue in GitHub or email us
InternetSocket.h
1 
2 /** \addtogroup netsocket */
3 /** @{*/
4 /* Socket
5  * Copyright (c) 2015 ARM Limited
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  */
19 
20 #ifndef INTERNETSOCKET_H
21 #define INTERNETSOCKET_H
22 
23 #include "netsocket/Socket.h"
24 #include "netsocket/NetworkStack.h"
25 #include "rtos/Mutex.h"
26 #include "rtos/EventFlags.h"
27 #include "Callback.h"
28 #include "mbed_atomic.h"
29 #include "mbed_toolchain.h"
30 #include "SocketStats.h"
31 
32 /** Socket implementation that uses IP network stack.
33  * Not to be directly used by applications. Cannot be directly instantiated.
34  */
35 class InternetSocket : public Socket {
36 public:
37  /** Destroy the socket.
38  *
39  * @note Closes socket if it's still open.
40  */
41  ~InternetSocket() override;
42 
43  /** Open a network socket on the network stack of the given
44  * network interface.
45  *
46  * @note Not needed if stack is passed to the socket's constructor.
47  *
48  * @param stack Network stack as target for socket.
49  * @retval NSAPI_ERROR_OK on success.
50  * @retval NSAPI_ERROR_PARAMETER in case the provided stack was invalid
51  * or a stack was already created and socket opened successfully.
52  * @retval int negative error codes for stack-related failures.
53  * See @ref NetworkStack::socket_open.
54  */
56 
57 #if !defined(DOXYGEN_ONLY)
58  template <typename S>
59  nsapi_error_t open(S *stack)
60  {
61  return open(nsapi_create_stack(stack));
62  }
63 #endif //!defined(DOXYGEN_ONLY)
64 
65  /** Close any open connection, and deallocate any memory associated
66  * with the socket. Called from destructor if socket is not closed.
67  *
68  * @retval NSAPI_ERROR_OK on success.
69  * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
70  * @retval int negative error codes for stack-related failures.
71  * See @ref NetworkStack::socket_close.
72  */
73  nsapi_error_t close() override;
74 
75  /** Subscribe to an IP multicast group.
76  *
77  * @param address Multicast group IP address.
78  * @return NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt).
79  */
80  int join_multicast_group(const SocketAddress &address);
81 
82  /** Leave an IP multicast group.
83  *
84  * @param address Multicast group IP address.
85  * @return NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt).
86  */
87  int leave_multicast_group(const SocketAddress &address);
88 
89  /** Get estimated round trip time to destination address.
90  *
91  * Use estimated round trip time to adjust application retry timers to work in networks
92  * that have low data rate and high latency.
93  *
94  * @param address Destination address to use in rtt estimate.
95  * @param rtt_estimate Returned round trip time value in milliseconds.
96  * @return NSAPI_ERROR_OK on success.
97  * @return NSAPI_ERROR_PARAMETER if the provided pointer is invalid.
98  * @return negative error code on other failures (@see InternetSocket::getsockopt).
99  */
100  int get_rtt_estimate_to_address(const SocketAddress &address, uint32_t *rtt_estimate);
101 
102  /** Get estimated stagger value.
103  *
104  * Stagger value is a time that application should wait before using heavy network operations after connecting to network.
105  * Purpose of staggering is to avoid network congestion that may happen in low bandwith networks if multiple
106  * applications simultaneously start heavy network usage after joining to the network.
107  *
108  * @param address Destination added used to estimate stagger value.
109  * @param data_amount Amount of bytes to transfer in kilobytes.
110  * @param stagger_min Minimum stagger value in seconds.
111  * @param stagger_max Maximum stagger value in seconds.
112  * @param stagger_rand Randomized stagger value between stagger_min and stagger_max in seconds.
113  * @return NSAPI_ERROR_OK on success.
114  * @return negative error code on other failures (@see InternetSocket::getsockopt).
115  */
116  int get_stagger_estimate_to_address(const SocketAddress &address, uint16_t data_amount, uint16_t *stagger_min, uint16_t *stagger_max, uint16_t *stagger_rand);
117 
118  /** Bind the socket to a port on which to receive data.
119  *
120  * @param port Local port to bind.
121  * @retval NSAPI_ERROR_OK on success.
122  * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
123  * @retval int negative error codes for stack-related failures.
124  * See @ref NetworkStack::socket_bind.
125  */
126  nsapi_error_t bind(uint16_t port);
127 
128  /** @copydoc Socket::bind
129  */
130  nsapi_error_t bind(const SocketAddress &address) override;
131 
132  /** @copydoc Socket::set_blocking
133  */
134  void set_blocking(bool blocking) override;
135 
136  /** @copydoc Socket::set_timeout
137  */
138  void set_timeout(int timeout) override;
139 
140  /** @copydoc Socket::setsockopt
141  */
142  nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) override;
143 
144  /** @copydoc Socket::getsockopt
145  */
146  nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) override;
147 
148  /** @copydoc Socket::sigio
149  */
150  void sigio(mbed::Callback<void()> func) override;
151 
152  /** @copydoc Socket::getpeername
153  */
154  nsapi_error_t getpeername(SocketAddress *address) override;
155 
156 
157 #if !defined(DOXYGEN_ONLY)
158 
159 protected:
160  InternetSocket();
161  virtual nsapi_protocol_t get_proto() = 0;
162  void event();
163  int modify_multicast_group(const SocketAddress &address, nsapi_socket_option_t socketopt);
164  char _interface_name[NSAPI_INTERFACE_NAME_MAX_SIZE];
165  NetworkStack *_stack = nullptr;
166  nsapi_socket_t _socket = nullptr;
167  uint32_t _timeout = osWaitForever;
168  mbed::Callback<void()> _event;
169  mbed::Callback<void()> _callback;
170  rtos::EventFlags _event_flag;
171  rtos::Mutex _lock;
172  SocketAddress _remote_peer;
173  uint8_t _readers = 0;
174  uint8_t _writers = 0;
176  bool _factory_allocated = false;
177 
178  // Event flags
179  static const int READ_FLAG = 0x1u;
180  static const int WRITE_FLAG = 0x2u;
181  static const int FINISHED_FLAG = 0x3u;
182 
183  friend class DTLSSocket; // Allow DTLSSocket::connect() to do name resolution on the _stack
184  SocketStats _socket_stats;
185 
186 #endif //!defined(DOXYGEN_ONLY)
187 };
188 
189 #endif // INTERNETSOCKET_H
190 
191 /** @}*/
nsapi_error_t open(NetworkStack *stack)
Open a network socket on the network stack of the given network interface.
Socket implementation that uses IP network stack.
~InternetSocket() override
Destroy the socket.
DTLSSocket implement DTLS stream over UDP Socket.
Definition: DTLSSocket.h:39
NetworkStack * nsapi_create_stack(nsapi_stack_t *stack)
Convert a raw nsapi_stack_t object into a C++ NetworkStack object.
int join_multicast_group(const SocketAddress &address)
Subscribe to an IP multicast group.
The EventFlags class is used to control event flags or wait for event flags other threads control...
Definition: EventFlags.h:53
NetworkStack class.
Definition: NetworkStack.h:41
void * nsapi_socket_t
Opaque handle for network sockets.
Definition: nsapi_types.h:207
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
#define NSAPI_INTERFACE_NAME_MAX_SIZE
Maximum size of network interface name.
Definition: nsapi_types.h:142
A lock-free, primitive atomic flag.
Definition: mbed_atomic.h:115
void set_blocking(bool blocking) override
Set blocking or non-blocking mode of the socket.
void set_timeout(int timeout) override
Set timeout on blocking socket operations.
Abstract Socket interface.
int get_rtt_estimate_to_address(const SocketAddress &address, uint32_t *rtt_estimate)
Get estimated round trip time to destination address.
nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) override
Set socket options.
SocketAddress class.
Definition: SocketAddress.h:36
The Mutex class is used to synchronize the execution of threads.
Definition: Mutex.h:70
Socket interface.
Definition: Socket.h:39
nsapi_error_t getpeername(SocketAddress *address) override
Get the remote-end peer associated with this socket.
int get_stagger_estimate_to_address(const SocketAddress &address, uint16_t data_amount, uint16_t *stagger_min, uint16_t *stagger_max, uint16_t *stagger_rand)
Get estimated stagger value.
SocketStats class.
Definition: SocketStats.h:59
NetworkStack class.
int leave_multicast_group(const SocketAddress &address)
Leave an IP multicast group.
nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) override
Get socket options.
nsapi_error_t close() override
defined(DOXYGEN_ONLY)
Callback class based on template specialization.
Definition: Callback.h:53
nsapi_error_t bind(uint16_t port)
Bind the socket to a port on which to receive data.
#define CORE_UTIL_ATOMIC_FLAG_INIT
Initializer for a core_util_atomic_flag.
Definition: mbed_atomic.h:127
void sigio(mbed::Callback< void()> func) override
Register a callback on state change of the socket.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.