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  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 /** @file TCPSocket.h TCPSocket class */
19 /** \addtogroup netsocket
20  * @{*/
21 
22 #ifndef TCPSOCKET_H
23 #define TCPSOCKET_H
24 
25 #include "netsocket/InternetSocket.h"
26 #include "netsocket/NetworkStack.h"
27 #include "netsocket/NetworkInterface.h"
28 #include "rtos/EventFlags.h"
29 
30 
31 /** TCP socket connection
32  */
33 class TCPSocket : public InternetSocket {
34 public:
35  /** Create an uninitialized socket
36  *
37  * Must call open to initialize the socket on a network stack.
38  */
39  TCPSocket();
40 
41  /** Override multicast functions to return error for TCP
42  *
43  */
44  int join_multicast_group(const SocketAddress &address)
45  {
46  return NSAPI_ERROR_UNSUPPORTED;
47  }
48 
49  /** Connects TCP socket to a remote host
50  *
51  * Initiates a connection to a remote server specified by the
52  * indicated address.
53  *
54  * @param address The SocketAddress of the remote host
55  * @retval NSAPI_ERROR_OK on success
56  * @retval NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
57  * @retval NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
58  * @retval NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
59  * @retval NSAPI_ERROR_IS_CONNECTED if the connection is already established
60  * @retval int Other negative error codes for stack-related failures.
61  * See NetworkStack::socket_connect().
62  */
63  nsapi_error_t connect(const SocketAddress &address) override;
64 
65  /** Send data over a TCP socket
66  *
67  * The socket must be connected to a remote host. Returns the number of
68  * bytes sent from the buffer.
69  *
70  * By default, send blocks until all data is sent. If socket is set to
71  * non-blocking or times out, a partial amount can be written.
72  * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
73  *
74  * @param data Buffer of data to send to the host
75  * @param size Size of the buffer in bytes
76  * @retval int Number of sent bytes on success
77  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
78  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
79  * and send cannot be performed immediately
80  * @retval int Other negative error codes for stack-related failures.
81  * See @ref NetworkStack::socket_send.
82  */
83  nsapi_size_or_error_t send(const void *data, nsapi_size_t size) override;
84 
85  /** Receive data over a TCP socket
86  *
87  * The socket must be connected to a remote host. Returns the number of
88  * bytes received into the buffer.
89  *
90  * By default, recv blocks until some data is received. If socket is set to
91  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
92  * indicate no data.
93  *
94  * @param data Destination buffer for data received from the host
95  * @param size Size of the buffer in bytes
96  * @retval int Number of received bytes on success
97  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
98  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
99  * and send cannot be performed immediately
100  * @retval int Other negative error codes for stack-related failures.
101  * See @ref NetworkStack::socket_recv.
102  */
103  nsapi_size_or_error_t recv(void *data, nsapi_size_t size) override;
104 
105  /** Send data on a socket.
106  *
107  * TCP socket is connection oriented protocol, so address is ignored.
108  *
109  * By default, sendto blocks until data is sent. If socket is set to
110  * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
111  * immediately.
112  *
113  * @param address Remote address
114  * @param data Buffer of data to send to the host
115  * @param size Size of the buffer in bytes
116  * @retval int Number of sent bytes on success
117  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
118  * @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
119  * and send cannot be performed immediately
120  * @retval int Other negative error codes for stack-related failures.
121  * See @ref NetworkStack::socket_send.
122  */
123  nsapi_size_or_error_t sendto(const SocketAddress &address,
124  const void *data, nsapi_size_t size) override;
125 
126  /** Receive a data from a socket
127  *
128  * Receives a data and stores the source address in address if address
129  * is not NULL. Returns the number of bytes written into the buffer.
130  *
131  * By default, recvfrom blocks until a data is received. If socket is set to
132  * non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
133  * is returned.
134  *
135  * @param address Destination for the source address or NULL
136  * @param data Destination buffer for datagram 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  nsapi_size_or_error_t recvfrom(SocketAddress *address,
146  void *data, nsapi_size_t size) override;
147 
148  /** Accepts a connection on a socket.
149  *
150  * The server socket must be bound and set to listen for connections.
151  * On a new connection, returns connected network socket which user is expected to call close()
152  * and that deallocates the resources. Referencing a returned pointer after a close()
153  * call is not allowed and leads to undefined behavior.
154  *
155  * By default, accept blocks until incoming connection occurs. If socket is set to
156  * non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
157  *
158  * @param error pointer to storage of the error value or NULL:
159  * NSAPI_ERROR_OK on success
160  * NSAPI_ERROR_WOULD_BLOCK if socket is set to non-blocking and would block
161  * NSAPI_ERROR_NO_SOCKET if the socket was not open
162  * @return pointer to a socket
163  */
164  TCPSocket *accept(nsapi_error_t *error = NULL) override;
165 
166  /** Listen for incoming connections.
167  *
168  * Marks the socket as a passive socket that can be used to accept
169  * incoming connections.
170  *
171  * @param backlog Number of pending connections that can be queued
172  * simultaneously, defaults to 1
173  * @retval NSAPI_ERROR_OK on success
174  * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
175  * @retval int Other negative error codes for stack-related failures.
176  * See @ref NetworkStack::socket_listen.
177  */
178  nsapi_error_t listen(int backlog = 1) override;
179 
180 protected:
181  nsapi_protocol_t get_proto() override;
182 
183 private:
184  /** Create a socket out of a given socket
185  *
186  * To be used within accept() function. Close() will clean this up.
187  */
188  TCPSocket(TCPSocket *parent, nsapi_socket_t socket, SocketAddress address);
189 };
190 
191 
192 #endif
193 
194 /** @}*/
InternetSocket
Socket implementation that uses IP network stack.
Definition: InternetSocket.h:36
TCPSocket::recvfrom
nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size) override
Receive a data from a socket.
TCPSocket::join_multicast_group
int join_multicast_group(const SocketAddress &address)
Override multicast functions to return error for TCP.
Definition: TCPSocket.h:44
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.
nsapi_socket_t
void * nsapi_socket_t
Opaque handle for network sockets.
Definition: nsapi_types.h:252
nsapi_error_t
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:140
TCPSocket::TCPSocket
TCPSocket()
Create an uninitialized socket.
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:151
TCPSocket::send
nsapi_size_or_error_t send(const void *data, nsapi_size_t size) override
Send data over a TCP socket.
TCPSocket::accept
TCPSocket * accept(nsapi_error_t *error=NULL) override
Accepts a connection on a socket.
TCPSocket::connect
nsapi_error_t connect(const SocketAddress &address) override
Connects TCP socket to a remote host.
SocketAddress
SocketAddress class.
Definition: SocketAddress.h:37
TCPSocket
TCP socket connection.
Definition: TCPSocket.h:33
TCPSocket::recv
nsapi_size_or_error_t recv(void *data, nsapi_size_t size) override
Receive data over a TCP socket.
TCPSocket::sendto
nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size) override
Send data on a socket.
NSAPI_ERROR_UNSUPPORTED
Definition: nsapi_types.h:85
nsapi_size_t
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:144
NetworkStack.h
NetworkStack class.
TCPSocket::listen
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.