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"
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  {
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  * @return 0 on success, negative error code on failure
81  */
82  nsapi_error_t connect(const char *host, uint16_t port);
83 
84  /** Connects TCP socket to a remote host
85  *
86  * Initiates a connection to a remote server specified by the
87  * indicated address.
88  *
89  * @param address The SocketAddress of the remote host
90  * @return 0 on success, negative error code on failure
91  */
92  virtual nsapi_error_t connect(const SocketAddress &address);
93 
94  /** Send data over a TCP socket
95  *
96  * The socket must be connected to a remote host. Returns the number of
97  * bytes sent from the buffer.
98  *
99  * By default, send blocks until all data is sent. If socket is set to
100  * non-blocking or times out, a partial amount can be written.
101  * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
102  *
103  * @param data Buffer of data to send to the host
104  * @param size Size of the buffer in bytes
105  * @return Number of sent bytes on success, negative error
106  * code on failure
107  */
108  virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size);
109 
110  /** Receive data over a TCP socket
111  *
112  * The socket must be connected to a remote host. Returns the number of
113  * bytes received into the buffer.
114  *
115  * By default, recv blocks until some data is received. If socket is set to
116  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
117  * indicate no data.
118  *
119  * @param data Destination buffer for data received from the host
120  * @param size Size of the buffer in bytes
121  * @return Number of received bytes on success, negative error
122  * code on failure. If no data is available to be received
123  * and the peer has performed an orderly shutdown,
124  * recv() returns 0.
125  */
126  virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
127 
128  /** Send data on a socket.
129  *
130  * TCP socket is connection oriented protocol, so address is ignored.
131  *
132  * By default, sendto blocks until data is sent. If socket is set to
133  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
134  * immediately.
135  *
136  * @param address Remote address
137  * @param data Buffer of data to send to the host
138  * @param size Size of the buffer in bytes
139  * @return Number of sent bytes on success, negative error
140  * code on failure
141  */
142  virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
143  const void *data, nsapi_size_t size);
144 
145  /** Receive a data from a socket
146  *
147  * Receives a data and stores the source address in address if address
148  * is not NULL. Returns the number of bytes written into the buffer.
149  *
150  * By default, recvfrom blocks until a data is received. If socket is set to
151  * non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
152  * is returned.
153  *
154  * @param address Destination for the source address or NULL
155  * @param data Destination buffer for datagram received from the host
156  * @param size Size of the buffer in bytes
157  * @return Number of received bytes on success, negative error
158  * code on failure
159  */
161  void *data, nsapi_size_t size);
162 
163  /** Accepts a connection on a socket.
164  *
165  * The server socket must be bound and set to listen for connections.
166  * On a new connection, returns connected network socket which user is expected to call close()
167  * and that deallocates the resources. Referencing a returned pointer after a close()
168  * call is not allowed and leads to undefined behavior.
169  *
170  * By default, accept blocks until incoming connection occurs. If socket is set to
171  * non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
172  *
173  * @param error pointer to storage of the error value or NULL
174  * @return pointer to a socket
175  */
176  virtual TCPSocket *accept(nsapi_error_t *error = NULL);
177 
178  /** Listen for incoming connections.
179  *
180  * Marks the socket as a passive socket that can be used to accept
181  * incoming connections.
182  *
183  * @param backlog Number of pending connections that can be queued
184  * simultaneously, defaults to 1
185  * @return 0 on success, negative error code on failure
186  */
187  virtual nsapi_error_t listen(int backlog = 1);
188 
189 protected:
190  friend class TCPServer;
191  virtual nsapi_protocol_t get_proto();
192 
193 private:
194  /** Create a socket out of a given socket
195  *
196  * To be used within accept() function. Close() will clean this up.
197  */
198  TCPSocket(TCPSocket *parent, nsapi_socket_t socket, SocketAddress address);
199 };
200 
201 
202 #endif
203 
204 /** @}*/
nsapi_error_t open(NetworkStack *stack)
Open a network socket on the network stack of the given network interface.
virtual TCPSocket * accept(nsapi_error_t *error=NULL)
Accepts a connection on a socket.
Socket implementation that uses IP network stack.
virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size)
Send data over a TCP socket.
virtual nsapi_error_t listen(int backlog=1)
Listen for incoming connections.
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_size_or_error_t recv(void *data, nsapi_size_t size)
Receive data over a TCP socket.
Network Interface base class.
void * nsapi_socket_t
Opaque handle for network sockets.
Definition: nsapi_types.h:204
TCP socket server.
Definition: TCPServer.h:32
virtual ~TCPSocket()
Destroy 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)
Receive a data from a socket.
TCPSocket()
Create an uninitialized socket.
virtual int join_multicast_group(const SocketAddress &address)
Override multicast functions to return error for TCP.
Definition: TCPSocket.h:68
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_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size)
Send data on a socket.
SocketAddress class.
Definition: SocketAddress.h:35
TCP socket connection.
Definition: TCPSocket.h:32
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:99
NetworkStack class.
nsapi_error_t connect(const char *host, uint16_t port)
Connects TCP socket to a remote host.
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
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.