Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
TCPSocket.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 TCPSocket.h TCPSocket class */
18 /** \addtogroup netsocket
19  * @{*/
20 
21 #ifndef TCPSOCKET_H
22 #define TCPSOCKET_H
23 
24 #include "netsocket/InternetSocket.h"
25 #include "netsocket/NetworkStack.h"
26 #include "netsocket/NetworkInterface.h"
27 #include "rtos/EventFlags.h"
28 
29 
30 /** TCP socket connection
31  */
32 class TCPSocket : public InternetSocket {
33 public:
34  /** Create an uninitialized socket
35  *
36  * Must call open to initialize the socket on a network stack.
37  */
38  TCPSocket();
39 
40  /** Create a socket on a network interface
41  *
42  * Creates and opens a socket on the network stack of the given
43  * network interface.
44  *
45  * @param stack Network stack as target for socket
46  *
47  * @deprecated since mbed-os-5.11
48  */
49  template <typename S>
50  MBED_DEPRECATED_SINCE("mbed-os-5.11",
51  "The TCPSocket(S *stack) constructor is deprecated."
52  "It discards the open() call return value."
53  "Use another constructor and call open() explicitly, instead.")
54  TCPSocket(S *stack)
55  {
56  open(stack);
57  }
58 
59  /** Destroy a socket
60  *
61  * Closes socket if the socket is still open
62  */
63  virtual ~TCPSocket();
64 
65  /** Override multicast functions to return error for TCP
66  *
67  */
68  virtual int join_multicast_group(const SocketAddress &address)
69  {
70  return NSAPI_ERROR_UNSUPPORTED;
71  }
72 
73  /** Connects TCP socket to a remote host
74  *
75  * Initiates a connection to a remote server specified by either
76  * a domain name or an IP address and a port.
77  *
78  * @param host Hostname of the remote host
79  * @param port Port of the remote host
80  * @retval NSAPI_ERROR_OK on success
81  * @retval NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
82  * @retval NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
83  * @retval NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
84  * @retval NSAPI_ERROR_IS_CONNECTED if the connection is already established
85  * @retval int Other negative error codes for stack-related failures.
86  * See NetworkStack::socket_connect().
87  */
88  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
89  nsapi_error_t connect(const char *host, uint16_t port);
90 
91  /** Connects TCP socket to a remote host
92  *
93  * Initiates a connection to a remote server specified by the
94  * indicated address.
95  *
96  * @param address The SocketAddress of the remote host
97  * @retval NSAPI_ERROR_OK on success
98  * @retval NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
99  * @retval NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
100  * @retval NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
101  * @retval NSAPI_ERROR_IS_CONNECTED if the connection is already established
102  * @retval int Other negative error codes for stack-related failures.
103  * See NetworkStack::socket_connect().
104  */
105  virtual nsapi_error_t connect(const SocketAddress &address);
106 
107  /** Send data over a TCP socket
108  *
109  * The socket must be connected to a remote host. Returns the number of
110  * bytes sent from the buffer.
111  *
112  * By default, send blocks until all data is sent. If socket is set to
113  * non-blocking or times out, a partial amount can be written.
114  * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
115  *
116  * @param data Buffer of data to send to the host
117  * @param size Size of the buffer in bytes
118  * @retval int Number of sent bytes on success
119  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
120  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
121  * and send cannot be performed immediately
122  * @retval int Other negative error codes for stack-related failures.
123  * See @ref NetworkStack::socket_send.
124  */
125  virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size);
126 
127  /** Receive data over a TCP socket
128  *
129  * The socket must be connected to a remote host. Returns the number of
130  * bytes received into the buffer.
131  *
132  * By default, recv blocks until some data is received. If socket is set to
133  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
134  * indicate no data.
135  *
136  * @param data Destination buffer for data received from the host
137  * @param size Size of the buffer in bytes
138  * @retval int Number of received bytes on success
139  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
140  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
141  * and send cannot be performed immediately
142  * @retval int Other negative error codes for stack-related failures.
143  * See @ref NetworkStack::socket_recv.
144  */
145  virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
146 
147  /** Send data on a socket.
148  *
149  * TCP socket is connection oriented protocol, so address is ignored.
150  *
151  * By default, sendto blocks until data is sent. If socket is set to
152  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
153  * immediately.
154  *
155  * @param address Remote address
156  * @param data Buffer of data to send to the host
157  * @param size Size of the buffer in bytes
158  * @retval int Number of sent bytes on success
159  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
160  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
161  * and send cannot be performed immediately
162  * @retval int Other negative error codes for stack-related failures.
163  * See @ref NetworkStack::socket_send.
164  */
165  virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
166  const void *data, nsapi_size_t size);
167 
168  /** Receive a data from a socket
169  *
170  * Receives a data and stores the source address in address if address
171  * is not NULL. Returns the number of bytes written into the buffer.
172  *
173  * By default, recvfrom blocks until a data is received. If socket is set to
174  * non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
175  * is returned.
176  *
177  * @param address Destination for the source address or NULL
178  * @param data Destination buffer for datagram received from the host
179  * @param size Size of the buffer in bytes
180  * @retval int Number of received bytes on success
181  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
182  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
183  * and send cannot be performed immediately
184  * @retval int Other negative error codes for stack-related failures.
185  * See @ref NetworkStack::socket_recv.
186  */
187  virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
188  void *data, nsapi_size_t size);
189 
190  /** Accepts a connection on a socket.
191  *
192  * The server socket must be bound and set to listen for connections.
193  * On a new connection, returns connected network socket which user is expected to call close()
194  * and that deallocates the resources. Referencing a returned pointer after a close()
195  * call is not allowed and leads to undefined behavior.
196  *
197  * By default, accept blocks until incoming connection occurs. If socket is set to
198  * non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
199  *
200  * @param error pointer to storage of the error value or NULL
201  * @return pointer to a socket
202  */
203  virtual TCPSocket *accept(nsapi_error_t *error = NULL);
204 
205  /** Listen for incoming connections.
206  *
207  * Marks the socket as a passive socket that can be used to accept
208  * incoming connections.
209  *
210  * @param backlog Number of pending connections that can be queued
211  * simultaneously, defaults to 1
212  * @retval NSAPI_ERROR_OK on success
213  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
214  * @retval int Other negative error codes for stack-related failures.
215  * See @ref NetworkStack::socket_listen.
216  */
217  virtual nsapi_error_t listen(int backlog = 1);
218 
219 protected:
220  friend class TCPServer;
221  virtual nsapi_protocol_t get_proto();
222 
223 private:
224  /** Create a socket out of a given socket
225  *
226  * To be used within accept() function. Close() will clean this up.
227  */
228  TCPSocket(TCPSocket *parent, nsapi_socket_t socket, SocketAddress address);
229 };
230 
231 
232 #endif
233 
234 /** @}*/
InternetSocket::open
nsapi_error_t open(NetworkStack *stack)
Open a network socket on the network stack of the given network interface.
TCPSocket::accept
virtual TCPSocket * accept(nsapi_error_t *error=NULL)
Accepts a connection on a socket.
InternetSocket
Socket implementation that uses IP network stack.
Definition: InternetSocket.h:35
TCPSocket::send
virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size)
Send data over a TCP socket.
TCPSocket::listen
virtual nsapi_error_t listen(int backlog=1)
Listen for incoming connections.
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.
TCPSocket::recv
virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size)
Receive data over a TCP socket.
NetworkInterface.h
Network Interface base class.
nsapi_socket_t
void * nsapi_socket_t
Opaque handle for network sockets.
Definition: nsapi_types.h:205
TCPServer
TCP socket server.
Definition: TCPServer.h:32
TCPSocket::~TCPSocket
virtual ~TCPSocket()
Destroy a socket.
nsapi_error_t
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
TCPSocket::recvfrom
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size)
Receive a data from a socket.
TCPSocket::TCPSocket
TCPSocket()
Create an uninitialized socket.
TCPSocket::join_multicast_group
virtual int join_multicast_group(const SocketAddress &address)
Override multicast functions to return error for TCP.
Definition: TCPSocket.h:68
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
TCPSocket::sendto
virtual nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size)
Send data on a socket.
SocketAddress
SocketAddress class.
Definition: SocketAddress.h:35
TCPSocket
TCP socket connection.
Definition: TCPSocket.h:32
NSAPI_ERROR_UNSUPPORTED
Definition: nsapi_types.h:40
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.
TCPSocket::connect
nsapi_error_t connect(const char *host, uint16_t port)
Connects TCP socket to a remote host.
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
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.