TCPSocket.h

00001 /*
00002  * Copyright (c) 2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /** @file TCPSocket.h TCPSocket class */
00018 /** \addtogroup netsocket
00019  * @{*/
00020 
00021 #ifndef TCPSOCKET_H
00022 #define TCPSOCKET_H
00023 
00024 #include "netsocket/InternetSocket.h"
00025 #include "netsocket/NetworkStack.h"
00026 #include "netsocket/NetworkInterface.h"
00027 #include "rtos/EventFlags.h"
00028 
00029 
00030 /** TCP socket connection
00031  */
00032 class TCPSocket : public InternetSocket {
00033 public:
00034     /** Create an uninitialized socket
00035      *
00036      *  Must call open to initialize the socket on a network stack.
00037      */
00038     TCPSocket();
00039 
00040     /** Create a socket on a network interface
00041      *
00042      *  Creates and opens a socket on the network stack of the given
00043      *  network interface.
00044      *
00045      *  @param stack    Network stack as target for socket
00046      *
00047      *  @deprecated since mbed-os-5.11
00048      */
00049     template <typename S>
00050     MBED_DEPRECATED_SINCE("mbed-os-5.11",
00051                           "The TCPSocket(S *stack) constructor is deprecated."
00052                           "It discards the open() call return value."
00053                           "Use another constructor and call open() explicitly, instead.")
00054     TCPSocket(S *stack)
00055     {
00056         open(stack);
00057     }
00058 
00059     /** Destroy a socket
00060      *
00061      *  Closes socket if the socket is still open
00062      */
00063     virtual ~TCPSocket();
00064 
00065     /** Override multicast functions to return error for TCP
00066      *
00067      */
00068     virtual int join_multicast_group(const SocketAddress &address)
00069     {
00070         return NSAPI_ERROR_UNSUPPORTED ;
00071     }
00072 
00073     /** Connects TCP socket to a remote host
00074      *
00075      *  Initiates a connection to a remote server specified by either
00076      *  a domain name or an IP address and a port.
00077      *
00078      *  @param host     Hostname of the remote host
00079      *  @param port     Port of the remote host
00080      *  @retval         NSAPI_ERROR_OK on success
00081      *  @retval         NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
00082      *  @retval         NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
00083      *  @retval         NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
00084      *  @retval         NSAPI_ERROR_IS_CONNECTED if the connection is already established
00085      *  @retval         int Other negative error codes for stack-related failures.
00086      *                  See NetworkStack::socket_connect().
00087      */
00088     MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00089     nsapi_error_t connect(const char *host, uint16_t port);
00090 
00091     /** Connects TCP socket to a remote host
00092      *
00093      *  Initiates a connection to a remote server specified by the
00094      *  indicated address.
00095      *
00096      *  @param address  The SocketAddress of the remote host
00097      *  @retval         NSAPI_ERROR_OK on success
00098      *  @retval         NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
00099      *  @retval         NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
00100      *  @retval         NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
00101      *  @retval         NSAPI_ERROR_IS_CONNECTED if the connection is already established
00102      *  @retval         int Other negative error codes for stack-related failures.
00103      *                  See NetworkStack::socket_connect().
00104      */
00105     virtual nsapi_error_t connect(const SocketAddress &address);
00106 
00107     /** Send data over a TCP socket
00108      *
00109      *  The socket must be connected to a remote host. Returns the number of
00110      *  bytes sent from the buffer.
00111      *
00112      *  By default, send blocks until all data is sent. If socket is set to
00113      *  non-blocking or times out, a partial amount can be written.
00114      *  NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
00115      *
00116      *  @param data     Buffer of data to send to the host
00117      *  @param size     Size of the buffer in bytes
00118      *  @retval         int Number of sent bytes on success
00119      *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
00120      *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
00121      *                  and send cannot be performed immediately
00122      *  @retval         int Other negative error codes for stack-related failures.
00123      *                  See @ref NetworkStack::socket_send.
00124      */
00125     virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size);
00126 
00127     /** Receive data over a TCP socket
00128      *
00129      *  The socket must be connected to a remote host. Returns the number of
00130      *  bytes received into the buffer.
00131      *
00132      *  By default, recv blocks until some data is received. If socket is set to
00133      *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
00134      *  indicate no data.
00135      *
00136      *  @param data     Destination buffer for data received from the host
00137      *  @param size     Size of the buffer in bytes
00138      *  @retval         int Number of received bytes on success
00139      *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
00140      *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
00141      *                  and send cannot be performed immediately
00142      *  @retval         int Other negative error codes for stack-related failures.
00143      *                  See @ref NetworkStack::socket_recv.
00144      */
00145     virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
00146 
00147     /** Send data on a socket.
00148      *
00149      * TCP socket is connection oriented protocol, so address is ignored.
00150      *
00151      * By default, sendto blocks until data is sent. If socket is set to
00152      * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
00153      * immediately.
00154      *
00155      *  @param address  Remote address
00156      *  @param data     Buffer of data to send to the host
00157      *  @param size     Size of the buffer in bytes
00158      *  @retval         int Number of sent bytes on success
00159      *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
00160      *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
00161      *                  and send cannot be performed immediately
00162      *  @retval         int Other negative error codes for stack-related failures.
00163      *                  See @ref NetworkStack::socket_send.
00164      */
00165     virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
00166                                          const void *data, nsapi_size_t size);
00167 
00168     /** Receive a data from a socket
00169      *
00170      *  Receives a data and stores the source address in address if address
00171      *  is not NULL. Returns the number of bytes written into the buffer.
00172      *
00173      *  By default, recvfrom blocks until a data is received. If socket is set to
00174      *  non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
00175      *  is returned.
00176      *
00177      *  @param address  Destination for the source address or NULL
00178      *  @param data     Destination buffer for datagram received from the host
00179      *  @param size     Size of the buffer in bytes
00180      *  @retval         int Number of received bytes on success
00181      *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
00182      *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
00183      *                  and send cannot be performed immediately
00184      *  @retval         int Other negative error codes for stack-related failures.
00185      *                  See @ref NetworkStack::socket_recv.
00186      */
00187     virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
00188                                            void *data, nsapi_size_t size);
00189 
00190     /** Accepts a connection on a socket.
00191      *
00192      *  The server socket must be bound and set to listen for connections.
00193      *  On a new connection, returns connected network socket which user is expected to call close()
00194      *  and that deallocates the resources. Referencing a returned pointer after a close()
00195      *  call is not allowed and leads to undefined behavior.
00196      *
00197      *  By default, accept blocks until incoming connection occurs. If socket is set to
00198      *  non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
00199      *
00200      *  @param error      pointer to storage of the error value or NULL:
00201      *                    NSAPI_ERROR_OK on success
00202      *                    NSAPI_ERROR_WOULD_BLOCK if socket is set to non-blocking and would block
00203      *                    NSAPI_ERROR_NO_SOCKET if the socket was not open
00204      *  @return           pointer to a socket
00205      */
00206     virtual TCPSocket *accept(nsapi_error_t *error = NULL);
00207 
00208     /** Listen for incoming connections.
00209      *
00210      *  Marks the socket as a passive socket that can be used to accept
00211      *  incoming connections.
00212      *
00213      *  @param backlog  Number of pending connections that can be queued
00214      *                  simultaneously, defaults to 1
00215      *  @retval         NSAPI_ERROR_OK on success
00216      *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
00217      *  @retval         int Other negative error codes for stack-related failures.
00218      *                  See @ref NetworkStack::socket_listen.
00219      */
00220     virtual nsapi_error_t listen(int backlog = 1);
00221 
00222 protected:
00223     friend class TCPServer;
00224     virtual nsapi_protocol_t get_proto();
00225 
00226 private:
00227     /** Create a socket out of a given socket
00228      *
00229      *  To be used within accept() function. Close() will clean this up.
00230      */
00231     TCPSocket(TCPSocket *parent, nsapi_socket_t socket, SocketAddress address);
00232 };
00233 
00234 
00235 #endif
00236 
00237 /** @}*/