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  /** Bind a specific address to a socket.
161  *
162  * Binding a socket specifies the address and port on which to receive
163  * data. If the IP address is zeroed, only the port is bound.
164  *
165  * @param address Local address to bind.
166  * @return NSAPI_ERROR_OK on success, negative subclass-dependent error
167  * code on failure.
168  */
169  virtual nsapi_error_t bind(const SocketAddress &address) = 0;
170 
171  /** Set blocking or non-blocking mode of the socket.
172  *
173  * Initially all sockets are in blocking mode. In non-blocking mode
174  * blocking operations such as send/recv/accept return
175  * NSAPI_ERROR_WOULD_BLOCK if they cannot continue.
176  *
177  * set_blocking(false) is equivalent to set_timeout(0)
178  * set_blocking(true) is equivalent to set_timeout(-1)
179  *
180  * @param blocking true for blocking mode, false for non-blocking mode.
181  */
182  virtual void set_blocking(bool blocking) = 0;
183 
184  /** Set timeout on blocking socket operations.
185  *
186  * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
187  * is returned if a blocking operation takes longer than the specified
188  * timeout. A timeout of 0 removes the timeout from the socket. A negative
189  * value gives the socket an unbounded timeout.
190  *
191  * set_timeout(0) is equivalent to set_blocking(false)
192  * set_timeout(-1) is equivalent to set_blocking(true)
193  *
194  * @param timeout Timeout in milliseconds
195  */
196  virtual void set_timeout(int timeout) = 0;
197 
198  /** Register a callback on state change of the socket.
199  *
200  * The specified callback is called on state changes, such as when
201  * the socket can receive/send/accept successfully and when an error
202  * occurs. The callback may also be called spuriously without reason.
203  *
204  * The callback may be called in an interrupt context and should not
205  * perform expensive operations such as receive/send calls.
206  *
207  * Note! This is not intended as a replacement for a poll or attach-like
208  * asynchronous API, but rather as a building block for constructing
209  * such functionality. The exact timing of the registered function
210  * is not guaranteed and susceptible to change.
211  *
212  * @param func Function to call on state change.
213  */
214  virtual void sigio(mbed::Callback<void()> func) = 0;
215 
216  /** Set socket options.
217  *
218  * setsockopt() allows an application to pass stack-specific options
219  * to the underlying stack using stack-specific level and option names,
220  * or to request generic options using levels from nsapi_socket_level_t.
221  *
222  * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
223  * and the socket is unmodified.
224  *
225  * @param level Stack-specific protocol level or nsapi_socket_level_t.
226  * @param optname Level-specific option name.
227  * @param optval Option value.
228  * @param optlen Length of the option value.
229  * @retval NSAPI_ERROR_OK on success.
230  * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
231  * @retval int Negative error code on failure, see @ref NetworkStack::setsockopt.
232  */
233  virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;
234 
235  /** Get socket options.
236  *
237  * getsockopt() allows an application to retrieve stack-specific options
238  * from the underlying stack using stack-specific level and option names,
239  * or to request generic options using levels from nsapi_socket_level_t.
240  *
241  * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
242  * and the socket is unmodified.
243  *
244  * @param level Stack-specific protocol level or nsapi_socket_level_t.
245  * @param optname Level-specific option name.
246  * @param optval Destination for option value.
247  * @param optlen Length of the option value.
248  * @retval NSAPI_ERROR_OK on success.
249  * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
250  * @retval int Negative error code on failure, see @ref NetworkStack::getsockopt.
251  */
252  virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;
253 
254  /** Accepts a connection on a socket.
255  *
256  * The server socket must be bound and set to listen for connections.
257  * On a new connection, returns connected network socket to call close()
258  * that deallocates the resources. Referencing a returned pointer after a close()
259  * call is not allowed and leads to undefined behavior.
260  *
261  * By default, accept blocks until incoming connection occurs. If socket is set to
262  * non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
263  *
264  * @param error Pointer to storage of the error value or NULL.
265  * @return Pointer to a socket.
266  */
267  virtual Socket *accept(nsapi_error_t *error = NULL) = 0;
268 
269  /** Listen for incoming connections.
270  *
271  * Marks the socket as a passive socket that can be used to accept
272  * incoming connections.
273  *
274  * @param backlog Number of pending connections that can be queued
275  * simultaneously, defaults to 1.
276  * @return NSAPI_ERROR_OK on success, negative error code on failure.
277  */
278  virtual nsapi_error_t listen(int backlog = 1) = 0;
279 
280  /** Get the remote-end peer associated with this socket.
281  *
282  * Copy the remote peer address to a SocketAddress structure pointed by
283  * address parameter. Socket must be connected to have a peer address
284  * associated.
285  *
286  * @param address Pointer to SocketAddress structure.
287  * @retval NSAPI_ERROR_OK on success.
288  * @retval NSAPI_ERROR_NO_SOCKET if socket is not connected.
289  * @retval NSAPI_ERROR_NO_CONNECTION if the remote peer was not set.
290  */
291  virtual nsapi_error_t getpeername(SocketAddress *address) = 0;
292 };
293 
294 
295 #endif
296 
297 /** @}*/
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:96
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 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:107
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.
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:100
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.