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