Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
InternetDatagramSocket.h
1 /** \addtogroup netsocket */
2 /** @{*/
3 /* InternetDatagramSocket
4  * Copyright (c) 2015 ARM Limited
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 #ifndef INTERNETDATAGRAMSOCKET_H
20 #define INTERNETDATAGRAMSOCKET_H
21 
22 #include "netsocket/InternetSocket.h"
23 #include "netsocket/NetworkStack.h"
24 #include "netsocket/NetworkInterface.h"
25 #include "rtos/EventFlags.h"
26 
27 
28 /** InternetDatagramSocket socket implementation.
29  */
30 class InternetDatagramSocket : public InternetSocket {
31 public:
32 
33  /** Send data to the specified host and port.
34  *
35  * By default, sendto blocks until data is sent. If socket is set to
36  * nonblocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
37  * immediately.
38  *
39  * @param host Domain name of the remote host or a dotted notation IP address.
40  * @param port Port of the remote host.
41  * @param data Buffer of data to send to the host.
42  * @param size Size of the buffer in bytes.
43  * @retval int Number of sent bytes on success.
44  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
45  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
46  * and send cannot be performed immediately.
47  * @retval int Other negative error codes for stack-related failures.
48  * See @ref NetworkStack::socket_send.
49  */
50  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
51  virtual nsapi_size_or_error_t sendto(const char *host, uint16_t port,
52  const void *data, nsapi_size_t size);
53 
54  /** Send data to the specified address.
55  *
56  * By default, sendto blocks until data is sent. If socket is set to
57  * nonblocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
58  * immediately.
59  *
60  * @param address The SocketAddress of the remote host.
61  * @param data Buffer of data to send to the host.
62  * @param size Size of the buffer in bytes.
63  * @retval NSAPI_ERROR_DNS_FAILURE in case the address parameter cannot
64  * be resolved.
65  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
66  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
67  * and send cannot be performed immediately.
68  * @retval int Other negative error codes for stack-related failures.
69  * See \ref NetworkStack::socket_send.
70  */
71  virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
72  const void *data, nsapi_size_t size);
73 
74  /** Receive a datagram and store the source address in address if it's not NULL.
75  *
76  * By default, recvfrom blocks until a datagram is received. If socket is set to
77  * nonblocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
78  * is returned.
79  *
80  * @note If the datagram is larger than the buffer, the excess data is silently discarded.
81  *
82  * @note If socket is connected, only packets coming from connected peer address
83  * are accepted.
84  *
85  * @note recvfrom() is allowed write to address and data buffers even if error occurs.
86  *
87  * @param address Destination for the source address or NULL.
88  * @param data Destination buffer for RAW data to be received from the host.
89  * @param size Size of the buffer in bytes.
90  * @retval int Number of received bytes on success.
91  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
92  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
93  * and send cannot be performed immediately.
94  * @retval int Other negative error codes for stack-related failures.
95  * See \ref NetworkStack::socket_recv.
96  */
97  virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
98  void *data, nsapi_size_t size);
99 
100  /** Set the remote address for next send() call and filtering
101  * of incoming packets. To reset the address, zero initialized
102  * SocketAddress must be in the address parameter.
103  *
104  * @param address The SocketAddress of the remote host.
105  * @return NSAPI_ERROR_OK on success.
106  */
107  virtual nsapi_error_t connect(const SocketAddress &address);
108 
109  /** Send a raw data to connected remote address.
110  *
111  * By default, send blocks until all data is sent. If socket is set to
112  * nonblocking or times out, a partial amount can be written.
113  * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
114  *
115  * @note The socket must be connected to a remote host before send() call.
116  *
117  * @param data Buffer of data to send to the host.
118  * @param size Size of the buffer in bytes.
119  * @retval int Number of sent bytes on success.
120  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
121  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
122  * and send cannot be performed immediately.
123  * @retval int Other negative error codes for stack-related failures.
124  * See \ref NetworkStack::socket_send.
125  */
126  virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size);
127 
128  /** Receive data from a socket.
129  *
130  * This is equivalent to calling recvfrom(NULL, data, size).
131  *
132  * By default, recv blocks until some data is received. If socket is set to
133  * nonblocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
134  * indicate no data.
135  *
136  * @note recv() is allowed write to data buffer even if error occurs.
137  *
138  * @param data Pointer to buffer for data received from the host.
139  * @param size Size of the buffer in bytes.
140  * @retval int Number of received bytes on success.
141  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
142  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
143  * and send cannot be performed immediately.
144  * @retval int Other negative error codes for stack-related failures.
145  * See \ref NetworkStack::socket_recv.
146  */
147  virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
148 
149  /** Not implemented for InternetDatagramSocket.
150  *
151  * @param error Not used.
152  * @return NSAPI_ERROR_UNSUPPORTED
153  */
154  virtual Socket *accept(nsapi_error_t *error = NULL);
155 
156  /** Not implemented for InternetDatagramSocket.
157  *
158  * @param backlog Not used.
159  * @return NSAPI_ERROR_UNSUPPORTED
160  */
161  virtual nsapi_error_t listen(int backlog = 1);
162 #if !defined(DOXYGEN_ONLY)
163 
164 protected:
165 
166  /** Create an uninitialized socket.
167  *
168  * @note Must call open to initialize the socket on a network stack.
169  */
170  InternetDatagramSocket() = default;
171 
172 #endif //!defined(DOXYGEN_ONLY)
173 };
174 
175 
176 #endif
177 
178 /** @}*/
InternetSocket
Socket implementation that uses IP network stack.
Definition: InternetSocket.h:35
error
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.
NetworkInterface.h
Network Interface base class.
InternetDatagramSocket::connect
virtual nsapi_error_t connect(const SocketAddress &address)
Set the remote address for next send() call and filtering of incoming packets.
nsapi_error_t
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
nsapi_size_or_error_t
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:106
InternetDatagramSocket::sendto
virtual nsapi_size_or_error_t sendto(const char *host, uint16_t port, const void *data, nsapi_size_t size)
Send data to the specified host and port.
SocketAddress
SocketAddress class.
Definition: SocketAddress.h:35
InternetDatagramSocket::accept
virtual Socket * accept(nsapi_error_t *error=NULL)
Not implemented for InternetDatagramSocket.
Socket
Socket interface.
Definition: Socket.h:39
InternetDatagramSocket::send
virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size)
Send a raw data to connected remote address.
nsapi_size_t
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:99
NetworkStack.h
NetworkStack class.
InternetDatagramSocket::recvfrom
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size)
Receive a datagram and store the source address in address if it's not NULL.
InternetDatagramSocket::listen
virtual nsapi_error_t listen(int backlog=1)
Not implemented for InternetDatagramSocket.
InternetDatagramSocket::recv
virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size)
Receive data from a socket.
MBED_DEPRECATED_SINCE
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Definition: mbed_toolchain.h:378
InternetDatagramSocket
InternetDatagramSocket socket implementation.
Definition: InternetDatagramSocket.h:30
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.