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  /** Override multicast functions to return error for TCP
41  *
42  */
43  int join_multicast_group(const SocketAddress &address)
44  {
46  }
47 
48  /** Connects TCP socket to a remote host
49  *
50  * Initiates a connection to a remote server specified by the
51  * indicated address.
52  *
53  * @param address The SocketAddress of the remote host
54  * @retval NSAPI_ERROR_OK on success
55  * @retval NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
56  * @retval NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
57  * @retval NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
58  * @retval NSAPI_ERROR_IS_CONNECTED if the connection is already established
59  * @retval int Other negative error codes for stack-related failures.
60  * See NetworkStack::socket_connect().
61  */
62  nsapi_error_t connect(const SocketAddress &address) override;
63 
64  /** Send data over a TCP socket
65  *
66  * The socket must be connected to a remote host. Returns the number of
67  * bytes sent from the buffer.
68  *
69  * By default, send blocks until all data is sent. If socket is set to
70  * non-blocking or times out, a partial amount can be written.
71  * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
72  *
73  * @param data Buffer of data to send to the host
74  * @param size Size of the buffer in bytes
75  * @retval int Number of sent bytes on success
76  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
77  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
78  * and send cannot be performed immediately
79  * @retval int Other negative error codes for stack-related failures.
80  * See @ref NetworkStack::socket_send.
81  */
82  nsapi_size_or_error_t send(const void *data, nsapi_size_t size) override;
83 
84  /** Receive data over a TCP socket
85  *
86  * The socket must be connected to a remote host. Returns the number of
87  * bytes received into the buffer.
88  *
89  * By default, recv blocks until some data is received. If socket is set to
90  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
91  * indicate no data.
92  *
93  * @param data Destination buffer for data received from the host
94  * @param size Size of the buffer in bytes
95  * @retval int Number of received bytes on success
96  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
97  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
98  * and send cannot be performed immediately
99  * @retval int Other negative error codes for stack-related failures.
100  * See @ref NetworkStack::socket_recv.
101  */
102  nsapi_size_or_error_t recv(void *data, nsapi_size_t size) override;
103 
104  /** Send data on a socket.
105  *
106  * TCP socket is connection oriented protocol, so address is ignored.
107  *
108  * By default, sendto blocks until data is sent. If socket is set to
109  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
110  * immediately.
111  *
112  * @param address Remote address
113  * @param data Buffer of data to send to the host
114  * @param size Size of the buffer in bytes
115  * @retval int Number of sent bytes on success
116  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
117  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
118  * and send cannot be performed immediately
119  * @retval int Other negative error codes for stack-related failures.
120  * See @ref NetworkStack::socket_send.
121  */
123  const void *data, nsapi_size_t size) override;
124 
125  /** Receive a data from a socket
126  *
127  * Receives a data and stores the source address in address if address
128  * is not NULL. Returns the number of bytes written into the buffer.
129  *
130  * By default, recvfrom blocks until a data is received. If socket is set to
131  * non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
132  * is returned.
133  *
134  * @param address Destination for the source address or NULL
135  * @param data Destination buffer for datagram received from the host
136  * @param size Size of the buffer in bytes
137  * @retval int Number of received bytes on success
138  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
139  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
140  * and send cannot be performed immediately
141  * @retval int Other negative error codes for stack-related failures.
142  * See @ref NetworkStack::socket_recv.
143  */
145  void *data, nsapi_size_t size) override;
146 
147  /** Accepts a connection on a socket.
148  *
149  * The server socket must be bound and set to listen for connections.
150  * On a new connection, returns connected network socket which user is expected to call close()
151  * and that deallocates the resources. Referencing a returned pointer after a close()
152  * call is not allowed and leads to undefined behavior.
153  *
154  * By default, accept blocks until incoming connection occurs. If socket is set to
155  * non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
156  *
157  * @param error pointer to storage of the error value or NULL:
158  * NSAPI_ERROR_OK on success
159  * NSAPI_ERROR_WOULD_BLOCK if socket is set to non-blocking and would block
160  * NSAPI_ERROR_NO_SOCKET if the socket was not open
161  * @return pointer to a socket
162  */
163  TCPSocket *accept(nsapi_error_t *error = NULL) override;
164 
165  /** Listen for incoming connections.
166  *
167  * Marks the socket as a passive socket that can be used to accept
168  * incoming connections.
169  *
170  * @param backlog Number of pending connections that can be queued
171  * simultaneously, defaults to 1
172  * @retval NSAPI_ERROR_OK on success
173  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
174  * @retval int Other negative error codes for stack-related failures.
175  * See @ref NetworkStack::socket_listen.
176  */
177  nsapi_error_t listen(int backlog = 1) override;
178 
179 protected:
180  nsapi_protocol_t get_proto() override;
181 
182 private:
183  /** Create a socket out of a given socket
184  *
185  * To be used within accept() function. Close() will clean this up.
186  */
187  TCPSocket(TCPSocket *parent, nsapi_socket_t socket, SocketAddress address);
188 };
189 
190 
191 #endif
192 
193 /** @}*/
Socket implementation that uses IP network stack.
nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size) override
Receive a data from a socket.
int join_multicast_group(const SocketAddress &address)
Override multicast functions to return error for TCP.
Definition: TCPSocket.h:43
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.
Network Interface base class.
void * nsapi_socket_t
Opaque handle for network sockets.
Definition: nsapi_types.h:207
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
TCPSocket()
Create an uninitialized socket.
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:106
nsapi_size_or_error_t send(const void *data, nsapi_size_t size) override
Send data over a TCP socket.
TCPSocket * accept(nsapi_error_t *error=NULL) override
Accepts a connection on a socket.
nsapi_error_t connect(const SocketAddress &address) override
Connects TCP socket to a remote host.
SocketAddress class.
Definition: SocketAddress.h:36
TCP socket connection.
Definition: TCPSocket.h:32
nsapi_size_or_error_t recv(void *data, nsapi_size_t size) override
Receive data over a TCP socket.
nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size) override
Send data on a socket.
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 listen(int backlog=1) override
Listen for incoming connections.
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.