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