Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Socket.h
00001 00002 /** \addtogroup netsocket */ 00003 /** @{*/ 00004 /* Socket 00005 * Copyright (c) 2015 ARM Limited 00006 * 00007 * Licensed under the Apache License, Version 2.0 (the "License"); 00008 * you may not use this file except in compliance with the License. 00009 * You may obtain a copy of the License at 00010 * 00011 * http://www.apache.org/licenses/LICENSE-2.0 00012 * 00013 * Unless required by applicable law or agreed to in writing, software 00014 * distributed under the License is distributed on an "AS IS" BASIS, 00015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00016 * See the License for the specific language governing permissions and 00017 * limitations under the License. 00018 */ 00019 00020 #ifndef SOCKET_H 00021 #define SOCKET_H 00022 00023 #include "netsocket/SocketAddress.h" 00024 #include "Callback.h" 00025 00026 /** Abstract socket class 00027 */ 00028 class Socket { 00029 public: 00030 /** Destroy a socket. 00031 * 00032 * Closes socket if the socket is still open 00033 */ 00034 virtual ~Socket() {} 00035 00036 /** Close the socket. 00037 * 00038 * Closes any open connection and deallocates any memory associated 00039 * with the socket. Called from destructor if socket is not closed. 00040 * 00041 * @return 0 on success, negative error code on failure 00042 */ 00043 virtual nsapi_error_t close() = 0; 00044 00045 /** Connects socket to a remote address. 00046 * 00047 * Attempt to make connection on connection-mode protocol or set or reset 00048 * the peer address on connectionless protocol. 00049 * 00050 * Also connectionless protocols use the connected address to filter 00051 * incoming packets for recv() and recvfrom() calls. 00052 * 00053 * To reset the peer address, zero initialised(default constructor) SocketAddress 00054 * object have to be in the address parameter. 00055 * 00056 * @param address The SocketAddress of the remote peer 00057 * @return 0 on success, negative error code on failure 00058 */ 00059 virtual nsapi_error_t connect(const SocketAddress &address) = 0; 00060 00061 /** Send data on a socket 00062 * 00063 * The socket must be connected to a remote host before send() call. 00064 * Returns the number of bytes sent from the buffer. 00065 * In case of connectionless socket, send data to pre-specified remote. 00066 * 00067 * By default, send blocks until all data is sent. If socket is set to 00068 * non-blocking or times out, a partial amount can be written. 00069 * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written. 00070 * 00071 * @param data Buffer of data to send to the host 00072 * @param size Size of the buffer in bytes 00073 * @return Number of sent bytes on success, negative error 00074 * code on failure. 00075 */ 00076 virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size) = 0; 00077 00078 /** Receive data from a socket. 00079 * 00080 * Receive data from connected socket or in case of connectionless socket 00081 * this is equivalent of calling recvfrom(NULL, data, size). 00082 * 00083 * If socket is connected, only packets coming from connected peer address 00084 * are accepted. 00085 * 00086 * @note recv() is allowed write to data buffer even if error occurs. 00087 * 00088 * By default, recv blocks until some data is received. If socket is set to 00089 * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to 00090 * indicate no data. 00091 * 00092 * @param data Destination buffer for data received from the host 00093 * @param size Size of the buffer in bytes 00094 * @return Number of received bytes on success, negative error 00095 * code on failure. If no data is available to be received 00096 * and the peer has performed an orderly shutdown, 00097 * recv() returns 0. 00098 */ 00099 virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size) = 0; 00100 00101 /** Send a message on a socket. 00102 * 00103 * The sendto() function shall send a message through a connection-mode or connectionless-mode socket. 00104 * If the socket is connectionless-mode, the message shall be sent to the address specified. 00105 * If the socket is connection-mode, address shall be ignored. 00106 * 00107 * By default, sendto blocks until data is sent. If socket is set to 00108 * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned 00109 * immediately. 00110 * 00111 * @param address Remote address 00112 * @param data Buffer of data to send to the host 00113 * @param size Size of the buffer in bytes 00114 * @return Number of sent bytes on success, negative error 00115 * code on failure 00116 */ 00117 virtual nsapi_size_or_error_t sendto(const SocketAddress &address, 00118 const void *data, nsapi_size_t size) = 0; 00119 00120 /** Receive a data from a socket 00121 * 00122 * Receives a data and stores the source address in address if address 00123 * is not NULL. Returns the number of bytes written into the buffer. 00124 * 00125 * If socket is connected, only packets coming from connected peer address 00126 * are accepted. 00127 * 00128 * @note recvfrom() is allowed write to address and data buffers even if error occurs. 00129 * 00130 * By default, recvfrom blocks until a datagram is received. If socket is set to 00131 * non-blocking or times out with no data, NSAPI_ERROR_WOULD_BLOCK 00132 * is returned. 00133 * 00134 * @param address Destination for the source address or NULL 00135 * @param data Destination buffer for datagram received from the host 00136 * @param size Size of the buffer in bytes 00137 * @return Number of received bytes on success, negative error 00138 * code on failure 00139 */ 00140 virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, 00141 void *data, nsapi_size_t size) = 0; 00142 00143 /** Bind a specific address to a socket. 00144 * 00145 * Binding assigns a local address to a socket. 00146 * 00147 * @param address Local address to bind 00148 * @return 0 on success, negative error code on failure. 00149 */ 00150 virtual nsapi_error_t bind(const SocketAddress &address) = 0; 00151 00152 /** Set blocking or non-blocking mode of the socket. 00153 * 00154 * Initially all sockets are in blocking mode. In non-blocking mode 00155 * blocking operations such as send/recv/accept return 00156 * NSAPI_ERROR_WOULD_BLOCK if they can not continue. 00157 * 00158 * set_blocking(false) is equivalent to set_timeout(-1) 00159 * set_blocking(true) is equivalent to set_timeout(0) 00160 * 00161 * @param blocking true for blocking mode, false for non-blocking mode. 00162 */ 00163 virtual void set_blocking(bool blocking) = 0; 00164 00165 /** Set timeout on blocking socket operations. 00166 * 00167 * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK 00168 * is returned if a blocking operation takes longer than the specified 00169 * timeout. A timeout of 0 removes the timeout from the socket. A negative 00170 * value give the socket an unbounded timeout. 00171 * 00172 * set_timeout(0) is equivalent to set_blocking(false) 00173 * set_timeout(-1) is equivalent to set_blocking(true) 00174 * 00175 * @param timeout Timeout in milliseconds 00176 */ 00177 virtual void set_timeout(int timeout) = 0; 00178 00179 /** Register a callback on state change of the socket. 00180 * 00181 * The specified callback will be called on state changes such as when 00182 * the socket can recv/send/accept successfully and on when an error 00183 * occurs. The callback may also be called spuriously without reason. 00184 * 00185 * The callback may be called in an interrupt context and should not 00186 * perform expensive operations such as recv/send calls. 00187 * 00188 * Note! This is not intended as a replacement for a poll or attach-like 00189 * asynchronous api, but rather as a building block for constructing 00190 * such functionality. The exact timing of when the registered function 00191 * is called is not guaranteed and susceptible to change. 00192 * 00193 * @param func Function to call on state change 00194 */ 00195 virtual void sigio(mbed::Callback<void()> func) = 0; 00196 00197 /* Set socket options. 00198 * 00199 * setsockopt() allows an application to pass stack-specific options 00200 * to the underlying stack using stack-specific level and option names, 00201 * or to request generic options using levels from nsapi_socket_level_t. 00202 * 00203 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned 00204 * and the socket is unmodified. 00205 * 00206 * @param level Stack-specific protocol level or nsapi_socket_level_t 00207 * @param optname Level-specific option name 00208 * @param optval Option value 00209 * @param optlen Length of the option value 00210 * @return 0 on success, negative error code on failure 00211 */ 00212 virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0; 00213 00214 /* Get socket options. 00215 * 00216 * getsockopt() allows an application to retrieve stack-specific options 00217 * from the underlying stack using stack-specific level and option names, 00218 * or to request generic options using levels from nsapi_socket_level_t. 00219 * 00220 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned 00221 * and the socket is unmodified. 00222 * 00223 * @param level Stack-specific protocol level or nsapi_socket_level_t 00224 * @param optname Level-specific option name 00225 * @param optval Destination for option value 00226 * @param optlen Length of the option value 00227 * @return 0 on success, negative error code on failure 00228 */ 00229 virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0; 00230 00231 /** Accepts a connection on a socket. 00232 * 00233 * The server socket must be bound and set to listen for connections. 00234 * On a new connection, returns connected network socket which user is expected to call close() 00235 * and that deallocates the resources. Referencing a returned pointer after a close() 00236 * call is not allowed and leads to undefined behaviour. 00237 * 00238 * By default, accept blocks until incomming connection occurs. If socket is set to 00239 * non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK. 00240 * 00241 * @param error pointer to storage of the error value or NULL 00242 * @return pointer to a socket 00243 */ 00244 virtual Socket *accept(nsapi_error_t *error = NULL) = 0; 00245 00246 /** Listen for incoming connections. 00247 * 00248 * Marks the socket as a passive socket that can be used to accept 00249 * incoming connections. 00250 * 00251 * @param backlog Number of pending connections that can be queued 00252 * simultaneously, defaults to 1 00253 * @return 0 on success, negative error code on failure 00254 */ 00255 virtual nsapi_error_t listen(int backlog = 1) = 0; 00256 }; 00257 00258 00259 #endif 00260 00261 /** @}*/
Generated on Tue Aug 9 2022 00:37:19 by
