Mistake on this page?
Report an issue in GitHub or email us
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  */
40 class Socket {
41 public:
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  * @return NSAPI_ERROR_OK on success.
54  * Negative subclass-dependent error code on failure.
55  */
56  virtual nsapi_error_t close() = 0;
57 
58  /** Connects socket to a remote address.
59  *
60  * Attempts to make connection on connection-mode protocol or set or reset
61  * the peer address on connectionless protocol.
62  *
63  * Connectionless protocols also use the connected address to filter
64  * incoming packets for recv() and recvfrom() calls.
65  *
66  * To reset the peer address, there must be zero initialized(default constructor) SocketAddress
67  * objects in the address parameter.
68  *
69  * @note If connect() fails it is recommended to close the Socket and create
70  * a new one before attempting to reconnect.
71  *
72  * @param address The SocketAddress of the remote peer.
73  * @return NSAPI_ERROR_OK on success.
74  * Negative subclass-dependent error code on failure.
75  */
76  virtual nsapi_error_t connect(const SocketAddress &address) = 0;
77 
78  /** Send data on a socket
79  *
80  * The socket must be connected to a remote host before send() call.
81  * Returns the number of bytes sent from the buffer.
82  * In case of connectionless socket, sends data to pre-specified remote.
83  *
84  * By default, send blocks until all data is sent. If socket is set to
85  * non-blocking or times out, a partial amount can be written.
86  * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
87  *
88  * @param data Buffer of data to send to the host.
89  * @param size Size of the buffer in bytes.
90  * @return NSAPI_ERROR_OK on success.
91  * Negative subclass-dependent error code on failure.
92  */
93  virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size) = 0;
94 
95  /** Receive data from a socket.
96  *
97  * Receive data from connected socket, or in the case of connectionless socket,
98  * equivalent to calling recvfrom(NULL, data, size).
99  *
100  * If socket is connected, only packets coming from connected peer address
101  * are accepted.
102  *
103  * @note recv() is allowed write to data buffer even if an error occurs.
104  *
105  * By default, recv blocks until some data is received. If socket is set to
106  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
107  * indicate no data.
108  *
109  * @param data Destination buffer for data received from the host.
110  * @param size Size of the buffer in bytes.
111  * @return Number of received bytes on success, negative, subclass-dependent
112  * error code on failure. If no data is available to be received
113  * and the peer has performed an orderly shutdown,
114  * recv() returns 0.
115  */
116  virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size) = 0;
117 
118  /** Send a message on a socket.
119  *
120  * The sendto() function sends a message through a connection-mode or connectionless-mode socket.
121  * If the socket is a connectionless-mode socket, the message is sent to the address specified.
122  * If the socket is a connected-mode socket, address is ignored.
123  *
124  * By default, sendto blocks until data is sent. If socket is set to
125  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
126  * immediately.
127  *
128  * @param address Remote address
129  * @param data Buffer of data to send to the host
130  * @param size Size of the buffer in bytes
131  * @return Number of sent bytes on success, negative subclass-dependent error
132  * code on failure
133  */
134  virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
135  const void *data, nsapi_size_t size) = 0;
136 
137  /** Receive a data from a socket
138  *
139  * Receives a data and stores the source address in address if address
140  * is not NULL. Returns the number of bytes written into the buffer.
141  *
142  * If socket is connected, only packets coming from connected peer address
143  * are accepted.
144  *
145  * @note recvfrom() is allowed write to address and data buffers even if error occurs.
146  *
147  * By default, recvfrom blocks until a datagram is received. If socket is set to
148  * non-blocking or times out with no data, NSAPI_ERROR_WOULD_BLOCK
149  * is returned.
150  *
151  * @param address Destination for the source address or NULL
152  * @param data Destination buffer for datagram received from the host
153  * @param size Size of the buffer in bytes
154  * @return Number of received bytes on success, negative subclass-dependent
155  * error code on failure
156  */
158  void *data, nsapi_size_t size) = 0;
159 
160  /** Send a message on a socket.
161  *
162  * The sendto_control() function sends a message through a connection-mode or connectionless-mode socket.
163  * If the socket is a connectionless-mode socket, the message is sent to the address specified.
164  * If the socket is a connected-mode socket, address is ignored.
165  *
166  * Additional control information can be passed to the stack for specific operations.
167  *
168  * By default, sendto blocks until data is sent. If socket is set to
169  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
170  * immediately.
171  *
172  * @param address Remote address
173  * @param data Buffer of data to send to the host
174  * @param size Size of the buffer in bytes
175  * @return Number of sent bytes on success, negative subclass-dependent error
176  * code on failure
177  */
178  virtual nsapi_size_or_error_t sendto_control(const SocketAddress &address,
179  const void *data, nsapi_size_t size,
180  nsapi_msghdr_t *control, nsapi_size_t control_size) = 0;
181 
182 
183  /** Receive a data from a socket
184  *
185  * Receives a data and stores the source address in address if address
186  * is not NULL. Returns the number of bytes written into the buffer.
187  *
188  * If socket is connected, only packets coming from connected peer address
189  * are accepted.
190  *
191  * Additional information related to the message can be retrieved with the control data.
192  *
193  * @note recvfrom_control() is allowed write to address and data buffers even if error occurs.
194  *
195  * By default, recvfrom blocks until a datagram is received. If socket is set to
196  * non-blocking or times out with no data, NSAPI_ERROR_WOULD_BLOCK
197  * is returned.
198  *
199  * @param address Destination for the source address or NULL
200  * @param data Destination buffer for datagram received from the host
201  * @param size Size of the buffer in bytes
202  * @return Number of received bytes on success, negative subclass-dependent
203  * error code on failure
204  */
206  void *data, nsapi_size_t size,
207  nsapi_msghdr_t *control, nsapi_size_t control_size) = 0;
208 
209  /** Bind a specific address to a socket.
210  *
211  * Binding a socket specifies the address and port on which to receive
212  * data. If the IP address is zeroed, only the port is bound.
213  *
214  * @param address Local address to bind.
215  * @return NSAPI_ERROR_OK on success, negative subclass-dependent error
216  * code on failure.
217  */
218  virtual nsapi_error_t bind(const SocketAddress &address) = 0;
219 
220  /** Set blocking or non-blocking mode of the socket.
221  *
222  * Initially all sockets are in blocking mode. In non-blocking mode
223  * blocking operations such as send/recv/accept return
224  * NSAPI_ERROR_WOULD_BLOCK if they cannot continue.
225  *
226  * set_blocking(false) is equivalent to set_timeout(0)
227  * set_blocking(true) is equivalent to set_timeout(-1)
228  *
229  * @param blocking true for blocking mode, false for non-blocking mode.
230  */
231  virtual void set_blocking(bool blocking) = 0;
232 
233  /** Set timeout on blocking socket operations.
234  *
235  * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
236  * is returned if a blocking operation takes longer than the specified
237  * timeout. A timeout of 0 removes the timeout from the socket. A negative
238  * value gives the socket an unbounded timeout.
239  *
240  * set_timeout(0) is equivalent to set_blocking(false)
241  * set_timeout(-1) is equivalent to set_blocking(true)
242  *
243  * @param timeout Timeout in milliseconds
244  */
245  virtual void set_timeout(int timeout) = 0;
246 
247  /** Register a callback on state change of the socket.
248  *
249  * The specified callback is called on state changes, such as when
250  * the socket can receive/send/accept successfully and when an error
251  * occurs. The callback may also be called spuriously without reason.
252  *
253  * The callback may be called in an interrupt context and should not
254  * perform expensive operations such as receive/send calls.
255  *
256  * Note! This is not intended as a replacement for a poll or attach-like
257  * asynchronous API, but rather as a building block for constructing
258  * such functionality. The exact timing of the registered function
259  * is not guaranteed and susceptible to change.
260  *
261  * @param func Function to call on state change.
262  */
263  virtual void sigio(mbed::Callback<void()> func) = 0;
264 
265  /** Set socket options.
266  *
267  * setsockopt() allows an application to pass stack-specific options
268  * to the underlying stack using stack-specific level and option names,
269  * or to request generic options using levels from nsapi_socket_level_t.
270  *
271  * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
272  * and the socket is unmodified.
273  *
274  * @param level Stack-specific protocol level or nsapi_socket_level_t.
275  * @param optname Level-specific option name.
276  * @param optval Option value.
277  * @param optlen Length of the option value.
278  * @retval NSAPI_ERROR_OK on success.
279  * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
280  * @retval int Negative error code on failure, see @ref NetworkStack::setsockopt.
281  */
282  virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;
283 
284  /** Get socket options.
285  *
286  * getsockopt() allows an application to retrieve stack-specific options
287  * from the underlying stack using stack-specific level and option names,
288  * or to request generic options using levels from nsapi_socket_level_t.
289  *
290  * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
291  * and the socket is unmodified.
292  *
293  * @param level Stack-specific protocol level or nsapi_socket_level_t.
294  * @param optname Level-specific option name.
295  * @param optval Destination for option value.
296  * @param optlen Length of the option value.
297  * @retval NSAPI_ERROR_OK on success.
298  * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
299  * @retval int Negative error code on failure, see @ref NetworkStack::getsockopt.
300  */
301  virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;
302 
303  /** Accepts a connection on a socket.
304  *
305  * The server socket must be bound and set to listen for connections.
306  * On a new connection, returns connected network socket to call close()
307  * that deallocates the resources. Referencing a returned pointer after a close()
308  * call is not allowed and leads to undefined behavior.
309  *
310  * By default, accept blocks until incoming connection occurs. If socket is set to
311  * non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
312  *
313  * @param error Pointer to storage of the error value or NULL.
314  * @return Pointer to a socket.
315  */
316  virtual Socket *accept(nsapi_error_t *error = NULL) = 0;
317 
318  /** Listen for incoming connections.
319  *
320  * Marks the socket as a passive socket that can be used to accept
321  * incoming connections.
322  *
323  * @param backlog Number of pending connections that can be queued
324  * simultaneously, defaults to 1.
325  * @return NSAPI_ERROR_OK on success, negative error code on failure.
326  */
327  virtual nsapi_error_t listen(int backlog = 1) = 0;
328 
329  /** Get the remote-end peer associated with this socket.
330  *
331  * Copy the remote peer address to a SocketAddress structure pointed by
332  * address parameter. Socket must be connected to have a peer address
333  * associated.
334  *
335  * @param address Pointer to SocketAddress structure.
336  * @retval NSAPI_ERROR_OK on success.
337  * @retval NSAPI_ERROR_NO_SOCKET if socket is not connected.
338  * @retval NSAPI_ERROR_NO_CONNECTION if the remote peer was not set.
339  */
340  virtual nsapi_error_t getpeername(SocketAddress *address) = 0;
341 };
342 
343 
344 #endif
345 
346 /** @}*/
nsapi_msghdr
Definition: nsapi_types.h:414
SocketAddress class.
virtual nsapi_error_t listen(int backlog=1)=0
Listen for incoming connections.
virtual nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size)=0
Send a message on a socket.
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.
virtual nsapi_error_t connect(const SocketAddress &address)=0
Connects socket to a remote address.
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen)=0
Set socket options.
virtual nsapi_error_t bind(const SocketAddress &address)=0
Bind a specific address to a socket.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:142
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size)=0
Receive a data from a socket.
virtual ~Socket()=default
Destroy a socket.
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 void set_timeout(int timeout)=0
Set timeout on blocking socket operations.
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:153
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen)=0
Get socket options.
SocketAddress class.
Definition: SocketAddress.h:37
virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size)=0
Receive 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.
Socket interface.
Definition: Socket.h:40
virtual void sigio(mbed::Callback< void()> func)=0
Register a callback on state change of the socket.
virtual nsapi_error_t getpeername(SocketAddress *address)=0
Get the remote-end peer associated with this socket.
virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size)=0
Send data on a socket.
virtual nsapi_error_t close()=0
Closes the socket.
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:146
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
virtual Socket * accept(nsapi_error_t *error=NULL)=0
Accepts a connection on a 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.