Mbed OS Reference
Loading...
Searching...
No Matches
Socket.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2015 ARM Limited
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/** @file Socket.h Abstract Socket interface */
19/** @addtogroup NetSocket
20 * Mbed OS Socket API
21 * @{ */
22
23#ifndef SOCKET_H
24#define SOCKET_H
25
27#include "Callback.h"
28
29/** Socket interface.
30 *
31 * This class defines the Mbed OS Socket API.
32 * Socket is an abstract interface for communicating with remote endpoints.
33 *
34 * This API is intended for applications and libraries instead of
35 * protocol-specific implementations. For example, TCPSocket
36 * and UDPSocket are implementations of the Socket interface.
37 * Socket API is intentionally not protocol-specific, and allows all protocol
38 * to provide the same API regardless of the underlying transport mechanism.
39 */
40class Socket {
41public:
42 /** Destroy a socket.
43 *
44 * Closes socket if the socket is still open.
45 */
46 virtual ~Socket() = default;
47
48 /** Closes the socket.
49 *
50 * Closes any open connection and deallocates any memory associated
51 * with the socket. Called from destructor if socket is not closed.
52 *
53 * If this socket was allocated by an accept() call, then calling this will also delete
54 * the socket object itself.
55 *
56 * @return NSAPI_ERROR_OK on success.
57 * Negative subclass-dependent error code on failure.
58 */
59 virtual nsapi_error_t close() = 0;
60
61 /** Connects socket to a remote address.
62 *
63 * Attempts to make connection on connection-mode protocol or set or reset
64 * the peer address on connectionless protocol.
65 *
66 * Connectionless protocols also use the connected address to filter
67 * incoming packets for recv() and recvfrom() calls.
68 *
69 * To reset the peer address, there must be zero initialized(default constructor) SocketAddress
70 * objects in the address parameter.
71 *
72 * @note If connect() fails it is recommended to close the Socket and create
73 * a new one before attempting to reconnect.
74 *
75 * @param address The SocketAddress of the remote peer.
76 * @return NSAPI_ERROR_OK on success.
77 * Negative subclass-dependent error code on failure.
78 */
79 virtual nsapi_error_t connect(const SocketAddress &address) = 0;
80
81 /** Send data on a socket
82 *
83 * The socket must be connected to a remote host before send() call.
84 * Returns the number of bytes sent from the buffer.
85 * In case of connectionless socket, sends data to pre-specified remote.
86 *
87 * By default, send blocks until all data is sent. If socket is set to
88 * non-blocking or times out, a partial amount can be written.
89 * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
90 *
91 * @param data Buffer of data to send to the host.
92 * @param size Size of the buffer in bytes.
93 * @return NSAPI_ERROR_OK on success.
94 * Negative subclass-dependent error code on failure.
95 */
96 virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size) = 0;
97
98 /** Receive data from a socket.
99 *
100 * Receive data from connected socket, or in the case of connectionless socket,
101 * equivalent to calling recvfrom(NULL, data, size).
102 *
103 * If socket is connected, only packets coming from connected peer address
104 * are accepted.
105 *
106 * @note recv() is allowed write to data buffer even if an error occurs.
107 *
108 * By default, recv blocks until some data is received. If socket is set to
109 * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
110 * indicate no data.
111 *
112 * @param data Destination buffer for data received from the host.
113 * @param size Size of the buffer in bytes.
114 * @return Number of received bytes on success, negative, subclass-dependent
115 * error code on failure. If no data is available to be received
116 * and the peer has performed an orderly shutdown,
117 * recv() returns 0.
118 */
119 virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size) = 0;
120
121 /** Send a message on a socket.
122 *
123 * The sendto() function sends a message through a connection-mode or connectionless-mode socket.
124 * If the socket is a connectionless-mode socket, the message is sent to the address specified.
125 * If the socket is a connected-mode socket, address is ignored.
126 *
127 * By default, sendto blocks until data is sent. If socket is set to
128 * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
129 * immediately.
130 *
131 * @param address Remote address
132 * @param data Buffer of data to send to the host
133 * @param size Size of the buffer in bytes
134 * @return Number of sent bytes on success, negative subclass-dependent error
135 * code on failure
136 */
138 const void *data, nsapi_size_t size) = 0;
139
140 /** Receive a data from a socket
141 *
142 * Receives a data and stores the source address in address if address
143 * is not NULL. Returns the number of bytes written into the buffer.
144 *
145 * If socket is connected, only packets coming from connected peer address
146 * are accepted.
147 *
148 * @note recvfrom() is allowed write to address and data buffers even if error occurs.
149 *
150 * By default, recvfrom blocks until a datagram is received. If socket is set to
151 * non-blocking or times out with no data, NSAPI_ERROR_WOULD_BLOCK
152 * is returned.
153 *
154 * @param address Destination for the source address or NULL
155 * @param data Destination buffer for datagram received from the host
156 * @param size Size of the buffer in bytes
157 * @return Number of received bytes on success, negative subclass-dependent
158 * error code on failure
159 */
161 void *data, nsapi_size_t size) = 0;
162
163 /** Send a message on a socket.
164 *
165 * The sendto_control() function sends a message through a connection-mode or connectionless-mode socket.
166 * If the socket is a connectionless-mode socket, the message is sent to the address specified.
167 * If the socket is a connected-mode socket, address is ignored.
168 *
169 * Additional control information can be passed to the stack for specific operations.
170 *
171 * By default, sendto blocks until data is sent. If socket is set to
172 * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
173 * immediately.
174 *
175 * @param address Remote address
176 * @param data Buffer of data to send to the host
177 * @param size Size of the buffer in bytes
178 * @param control Control data, for instance a populated #nsapi_pktinfo structure.
179 * @param control_size Size of \c control in bytes.
180 * @return Number of sent bytes on success, negative subclass-dependent error
181 * code on failure
182 */
184 const void *data, nsapi_size_t size,
185 nsapi_msghdr_t *control, nsapi_size_t control_size) = 0;
186
187
188 /** Receive a data from a socket
189 *
190 * Receives a data and stores the source address in address if address
191 * is not NULL. Returns the number of bytes written into the buffer.
192 *
193 * If socket is connected, only packets coming from connected peer address
194 * are accepted.
195 *
196 * Ancillary data is stored into \c control. The caller needs to allocate a buffer
197 * that is large enough to contain the data they want to receive, then pass the pointer in
198 * through the \c control member. The data will be filled into \c control, beginning with a header
199 * specifying what data was received. See #MsgHeaderIterator for how to parse this data.
200 *
201 * @note recvfrom_control() is allowed write to address and data buffers even if error occurs.
202 *
203 * By default, recvfrom blocks until a datagram is received. If socket is set to
204 * non-blocking or times out with no data, NSAPI_ERROR_WOULD_BLOCK
205 * is returned.
206 *
207 * @param address Destination for the source address or NULL
208 * @param data Destination buffer for datagram received from the host
209 * @param size Size of the buffer in bytes
210 * @param control Caller-allocated buffer to store ancillary data.
211 * @param control_size Size of the \c control buffer that the caller has allocated.
212 * @return Number of received bytes on success, negative subclass-dependent
213 * error code on failure
214 */
216 void *data, nsapi_size_t size,
217 nsapi_msghdr_t *control, nsapi_size_t control_size) = 0;
218
219 /** Bind a specific address to a socket.
220 *
221 * Binding a socket specifies the address and port on which to receive
222 * data. If the IP address is zeroed, only the port is bound.
223 *
224 * @param address Local address to bind.
225 * @return NSAPI_ERROR_OK on success, negative subclass-dependent error
226 * code on failure.
227 */
228 virtual nsapi_error_t bind(const SocketAddress &address) = 0;
229
230 /** Set blocking or non-blocking mode of the socket.
231 *
232 * Initially all sockets are in blocking mode. In non-blocking mode
233 * blocking operations such as send/recv/accept return
234 * NSAPI_ERROR_WOULD_BLOCK if they cannot continue.
235 *
236 * set_blocking(false) is equivalent to set_timeout(0)
237 * set_blocking(true) is equivalent to set_timeout(-1)
238 *
239 * @param blocking true for blocking mode, false for non-blocking mode.
240 */
241 virtual void set_blocking(bool blocking) = 0;
242
243 /** Set timeout on blocking socket operations.
244 *
245 * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
246 * is returned if a blocking operation takes longer than the specified
247 * timeout. A timeout of 0 removes the timeout from the socket. A negative
248 * value gives the socket an unbounded timeout.
249 *
250 * set_timeout(0) is equivalent to set_blocking(false)
251 * set_timeout(-1) is equivalent to set_blocking(true)
252 *
253 * @param timeout Timeout in milliseconds
254 */
255 virtual void set_timeout(int timeout) = 0;
256
257 /** Register a callback on state change of the socket.
258 *
259 * The specified callback is called on state changes, such as when
260 * the socket can receive/send/accept successfully and when an error
261 * occurs. The callback may also be called spuriously without reason.
262 *
263 * The callback may be called in an interrupt context and should not
264 * perform expensive operations such as receive/send calls.
265 *
266 * Note! This is not intended as a replacement for a poll or attach-like
267 * asynchronous API, but rather as a building block for constructing
268 * such functionality. The exact timing of the registered function
269 * is not guaranteed and susceptible to change.
270 *
271 * @param func Function to call on state change.
272 */
273 virtual void sigio(mbed::Callback<void()> func) = 0;
274
275 /** Set socket options.
276 *
277 * setsockopt() allows an application to pass stack-specific options
278 * to the underlying stack using stack-specific level and option names,
279 * or to request generic options using levels from nsapi_socket_level_t.
280 *
281 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
282 * and the socket is unmodified.
283 *
284 * @param level Stack-specific protocol level or nsapi_socket_level_t.
285 * @param optname Level-specific option name.
286 * @param optval Option value.
287 * @param optlen Length of the option value.
288 * @retval NSAPI_ERROR_OK on success.
289 * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
290 * @retval Negative error code on failure, see #NetworkStack::setsockopt
291 */
292 virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;
293
294 /** Get socket options.
295 *
296 * getsockopt() allows an application to retrieve stack-specific options
297 * from the underlying stack using stack-specific level and option names,
298 * or to request generic options using levels from nsapi_socket_level_t.
299 *
300 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
301 * and the socket is unmodified.
302 *
303 * @param level Stack-specific protocol level or nsapi_socket_level_t.
304 * @param optname Level-specific option name.
305 * @param optval Destination for option value.
306 * @param optlen Length of the option value.
307 * @retval NSAPI_ERROR_OK on success.
308 * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
309 * @retval Negative error code on failure, see #NetworkStack::getsockopt
310 */
311 virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;
312
313 /**
314 * @brief Waits for a client to try to connect to this socket, then returns a socket for the new connection.
315 *
316 * On error, returns nullptr and sets the error code parameter (if provided).
317 *
318 * Note that if a socket is returned, you must eventually call close() on it to release its resources.
319 * Calling close() will also delete the socket object, no separate \c delete is required.
320 * Referencing the returned socket after a close() call is not allowed and leads to undefined behavior.
321 *
322 * By default, this function blocks until an incoming connection occurs. If socket is set to
323 * non-blocking or times out, an \c NSAPI_ERROR_WOULD_BLOCK error is returned.
324 *
325 * @param error If you wish to check the error code, pass an error code pointer here.
326 * @return Pointer to a socket, or nullptr on error
327 */
328 virtual Socket *accept(nsapi_error_t *error = nullptr) = 0;
329
330 /** Listen for incoming connections.
331 *
332 * Marks the socket as a passive socket that can be used to accept
333 * incoming connections.
334 *
335 * @param backlog Number of pending connections that can be queued
336 * simultaneously, defaults to 1.
337 * @return NSAPI_ERROR_OK on success, negative error code on failure.
338 */
339 virtual nsapi_error_t listen(int backlog = 1) = 0;
340
341 /** Get the remote-end peer associated with this socket.
342 *
343 * Copy the remote peer address to a SocketAddress structure pointed by
344 * address parameter. Socket must be connected to have a peer address
345 * associated.
346 *
347 * @param address Pointer to SocketAddress structure.
348 * @retval NSAPI_ERROR_OK on success.
349 * @retval NSAPI_ERROR_NO_SOCKET if socket is not connected.
350 * @retval NSAPI_ERROR_NO_CONNECTION if the remote peer was not set.
351 */
353};
354
355
356#endif
357
358/** @}*/
SocketAddress class.
SocketAddress class.
Socket interface.
Definition Socket.h:40
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen)=0
Set socket options.
virtual Socket * accept(nsapi_error_t *error=nullptr)=0
Waits for a client to try to connect to this socket, then returns a socket for the new connection.
virtual nsapi_size_or_error_t recvfrom_control(SocketAddress *address, void *data, nsapi_size_t size, nsapi_msghdr_t *control, nsapi_size_t control_size)=0
Receive a data from a socket.
virtual nsapi_size_or_error_t sendto_control(const SocketAddress &address, const void *data, nsapi_size_t size, nsapi_msghdr_t *control, nsapi_size_t control_size)=0
Send a message on a socket.
virtual nsapi_error_t close()=0
Closes the socket.
virtual nsapi_error_t bind(const SocketAddress &address)=0
Bind a specific address to a socket.
virtual void sigio(mbed::Callback< void()> func)=0
Register a callback on state change of the socket.
virtual ~Socket()=default
Destroy a socket.
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size)=0
Receive a data from a socket.
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen)=0
Get socket options.
virtual nsapi_error_t getpeername(SocketAddress *address)=0
Get the remote-end peer associated with this socket.
virtual nsapi_error_t connect(const SocketAddress &address)=0
Connects socket to a remote address.
virtual nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size)=0
Send a message on a socket.
virtual nsapi_error_t listen(int backlog=1)=0
Listen for incoming connections.
virtual void set_timeout(int timeout)=0
Set timeout on blocking socket operations.
virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size)=0
Send data on a socket.
virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size)=0
Receive data from a socket.
virtual void set_blocking(bool blocking)=0
Set blocking or non-blocking mode of the socket.
Callback class based on template specialization.
Definition Callback.h:53
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
signed int nsapi_error_t
Type used to represent error codes.
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
MBED_NORETURN void error(const char *format,...) MBED_PRINTF(1
To generate a fatal compile-time error, you can use the pre-processor error directive.
Header structure for control info.