Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

features/netsocket/Socket.h@1:9db0e321a9f4, 2019-12-31 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 31 06:02:27 2019 +0000
Revision:
1:9db0e321a9f4
Parent:
0:5b88d5760320 
updated based on mbed-os5.15.0

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kenjiArai 0:5b88d5760320 1 /*
kenjiArai 0:5b88d5760320 2 * Copyright (c) 2015 ARM Limited
kenjiArai 0:5b88d5760320 3 *
kenjiArai 0:5b88d5760320 4 * Licensed under the Apache License, Version 2.0 (the "License");
kenjiArai 0:5b88d5760320 5 * you may not use this file except in compliance with the License.
kenjiArai 0:5b88d5760320 6 * You may obtain a copy of the License at
kenjiArai 0:5b88d5760320 7 *
kenjiArai 0:5b88d5760320 8 * http://www.apache.org/licenses/LICENSE-2.0
kenjiArai 0:5b88d5760320 9 *
kenjiArai 0:5b88d5760320 10 * Unless required by applicable law or agreed to in writing, software
kenjiArai 0:5b88d5760320 11 * distributed under the License is distributed on an "AS IS" BASIS,
kenjiArai 0:5b88d5760320 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
kenjiArai 0:5b88d5760320 13 * See the License for the specific language governing permissions and
kenjiArai 0:5b88d5760320 14 * limitations under the License.
kenjiArai 0:5b88d5760320 15 */
kenjiArai 0:5b88d5760320 16
kenjiArai 0:5b88d5760320 17 /** @file Socket.h Abstract Socket interface */
kenjiArai 0:5b88d5760320 18 /** @addtogroup netsocket
kenjiArai 0:5b88d5760320 19 * Mbed OS Socket API
kenjiArai 0:5b88d5760320 20 * @{ */
kenjiArai 0:5b88d5760320 21
kenjiArai 0:5b88d5760320 22 #ifndef SOCKET_H
kenjiArai 0:5b88d5760320 23 #define SOCKET_H
kenjiArai 0:5b88d5760320 24
kenjiArai 0:5b88d5760320 25 #include "netsocket/SocketAddress.h"
kenjiArai 0:5b88d5760320 26 #include "Callback.h"
kenjiArai 0:5b88d5760320 27
kenjiArai 0:5b88d5760320 28 /** Socket interface.
kenjiArai 0:5b88d5760320 29 *
kenjiArai 0:5b88d5760320 30 * This class defines the Mbed OS Socket API.
kenjiArai 0:5b88d5760320 31 * Socket is an abstract interface for communicating with remote endpoints.
kenjiArai 0:5b88d5760320 32 *
kenjiArai 0:5b88d5760320 33 * This API is intended for applications and libraries instead of
kenjiArai 0:5b88d5760320 34 * protocol-specific implementations. For example, TCPSocket
kenjiArai 0:5b88d5760320 35 * and UDPSocket are implementations of the Socket interface.
kenjiArai 0:5b88d5760320 36 * Socket API is intentionally not protocol-specific, and allows all protocol
kenjiArai 0:5b88d5760320 37 * to provide the same API regardless of the underlying transport mechanism.
kenjiArai 0:5b88d5760320 38 */
kenjiArai 0:5b88d5760320 39 class Socket {
kenjiArai 0:5b88d5760320 40 public:
kenjiArai 0:5b88d5760320 41 /** Destroy a socket.
kenjiArai 0:5b88d5760320 42 *
kenjiArai 0:5b88d5760320 43 * Closes socket if the socket is still open.
kenjiArai 0:5b88d5760320 44 */
kenjiArai 0:5b88d5760320 45 virtual ~Socket() {}
kenjiArai 0:5b88d5760320 46
kenjiArai 0:5b88d5760320 47 /** Closes the socket.
kenjiArai 0:5b88d5760320 48 *
kenjiArai 0:5b88d5760320 49 * Closes any open connection and deallocates any memory associated
kenjiArai 0:5b88d5760320 50 * with the socket. Called from destructor if socket is not closed.
kenjiArai 0:5b88d5760320 51 *
kenjiArai 1:9db0e321a9f4 52 * @return NSAPI_ERROR_OK on success.
kenjiArai 1:9db0e321a9f4 53 * Negative subclass-dependent error code on failure.
kenjiArai 0:5b88d5760320 54 */
kenjiArai 0:5b88d5760320 55 virtual nsapi_error_t close() = 0;
kenjiArai 0:5b88d5760320 56
kenjiArai 0:5b88d5760320 57 /** Connects socket to a remote address.
kenjiArai 0:5b88d5760320 58 *
kenjiArai 0:5b88d5760320 59 * Attempts to make connection on connection-mode protocol or set or reset
kenjiArai 0:5b88d5760320 60 * the peer address on connectionless protocol.
kenjiArai 0:5b88d5760320 61 *
kenjiArai 0:5b88d5760320 62 * Connectionless protocols also use the connected address to filter
kenjiArai 0:5b88d5760320 63 * incoming packets for recv() and recvfrom() calls.
kenjiArai 0:5b88d5760320 64 *
kenjiArai 0:5b88d5760320 65 * To reset the peer address, there must be zero initialized(default constructor) SocketAddress
kenjiArai 0:5b88d5760320 66 * objects in the address parameter.
kenjiArai 0:5b88d5760320 67 *
kenjiArai 0:5b88d5760320 68 * @note If connect() fails it is recommended to close the Socket and create
kenjiArai 0:5b88d5760320 69 * a new one before attempting to reconnect.
kenjiArai 0:5b88d5760320 70 *
kenjiArai 0:5b88d5760320 71 * @param address The SocketAddress of the remote peer.
kenjiArai 1:9db0e321a9f4 72 * @return NSAPI_ERROR_OK on success.
kenjiArai 1:9db0e321a9f4 73 * Negative subclass-dependent error code on failure.
kenjiArai 0:5b88d5760320 74 */
kenjiArai 0:5b88d5760320 75 virtual nsapi_error_t connect(const SocketAddress &address) = 0;
kenjiArai 0:5b88d5760320 76
kenjiArai 0:5b88d5760320 77 /** Send data on a socket
kenjiArai 0:5b88d5760320 78 *
kenjiArai 0:5b88d5760320 79 * The socket must be connected to a remote host before send() call.
kenjiArai 0:5b88d5760320 80 * Returns the number of bytes sent from the buffer.
kenjiArai 0:5b88d5760320 81 * In case of connectionless socket, sends data to pre-specified remote.
kenjiArai 0:5b88d5760320 82 *
kenjiArai 0:5b88d5760320 83 * By default, send blocks until all data is sent. If socket is set to
kenjiArai 0:5b88d5760320 84 * non-blocking or times out, a partial amount can be written.
kenjiArai 0:5b88d5760320 85 * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
kenjiArai 0:5b88d5760320 86 *
kenjiArai 0:5b88d5760320 87 * @param data Buffer of data to send to the host.
kenjiArai 0:5b88d5760320 88 * @param size Size of the buffer in bytes.
kenjiArai 1:9db0e321a9f4 89 * @return NSAPI_ERROR_OK on success.
kenjiArai 1:9db0e321a9f4 90 * Negative subclass-dependent error code on failure.
kenjiArai 0:5b88d5760320 91 */
kenjiArai 0:5b88d5760320 92 virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size) = 0;
kenjiArai 0:5b88d5760320 93
kenjiArai 0:5b88d5760320 94 /** Receive data from a socket.
kenjiArai 0:5b88d5760320 95 *
kenjiArai 0:5b88d5760320 96 * Receive data from connected socket, or in the case of connectionless socket,
kenjiArai 0:5b88d5760320 97 * equivalent to calling recvfrom(NULL, data, size).
kenjiArai 0:5b88d5760320 98 *
kenjiArai 0:5b88d5760320 99 * If socket is connected, only packets coming from connected peer address
kenjiArai 0:5b88d5760320 100 * are accepted.
kenjiArai 0:5b88d5760320 101 *
kenjiArai 0:5b88d5760320 102 * @note recv() is allowed write to data buffer even if an error occurs.
kenjiArai 0:5b88d5760320 103 *
kenjiArai 0:5b88d5760320 104 * By default, recv blocks until some data is received. If socket is set to
kenjiArai 0:5b88d5760320 105 * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
kenjiArai 0:5b88d5760320 106 * indicate no data.
kenjiArai 0:5b88d5760320 107 *
kenjiArai 0:5b88d5760320 108 * @param data Destination buffer for data received from the host.
kenjiArai 0:5b88d5760320 109 * @param size Size of the buffer in bytes.
kenjiArai 1:9db0e321a9f4 110 * @return Number of received bytes on success, negative, subclass-dependent
kenjiArai 1:9db0e321a9f4 111 * error code on failure. If no data is available to be received
kenjiArai 0:5b88d5760320 112 * and the peer has performed an orderly shutdown,
kenjiArai 0:5b88d5760320 113 * recv() returns 0.
kenjiArai 0:5b88d5760320 114 */
kenjiArai 0:5b88d5760320 115 virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size) = 0;
kenjiArai 0:5b88d5760320 116
kenjiArai 0:5b88d5760320 117 /** Send a message on a socket.
kenjiArai 0:5b88d5760320 118 *
kenjiArai 0:5b88d5760320 119 * The sendto() function sends a message through a connection-mode or connectionless-mode socket.
kenjiArai 0:5b88d5760320 120 * If the socket is a connectionless-mode socket, the message is sent to the address specified.
kenjiArai 0:5b88d5760320 121 * If the socket is a connected-mode socket, address is ignored.
kenjiArai 0:5b88d5760320 122 *
kenjiArai 0:5b88d5760320 123 * By default, sendto blocks until data is sent. If socket is set to
kenjiArai 0:5b88d5760320 124 * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
kenjiArai 0:5b88d5760320 125 * immediately.
kenjiArai 0:5b88d5760320 126 *
kenjiArai 0:5b88d5760320 127 * @param address Remote address
kenjiArai 0:5b88d5760320 128 * @param data Buffer of data to send to the host
kenjiArai 0:5b88d5760320 129 * @param size Size of the buffer in bytes
kenjiArai 1:9db0e321a9f4 130 * @return Number of sent bytes on success, negative subclass-dependent error
kenjiArai 0:5b88d5760320 131 * code on failure
kenjiArai 0:5b88d5760320 132 */
kenjiArai 0:5b88d5760320 133 virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
kenjiArai 0:5b88d5760320 134 const void *data, nsapi_size_t size) = 0;
kenjiArai 0:5b88d5760320 135
kenjiArai 0:5b88d5760320 136 /** Receive a data from a socket
kenjiArai 0:5b88d5760320 137 *
kenjiArai 0:5b88d5760320 138 * Receives a data and stores the source address in address if address
kenjiArai 0:5b88d5760320 139 * is not NULL. Returns the number of bytes written into the buffer.
kenjiArai 0:5b88d5760320 140 *
kenjiArai 0:5b88d5760320 141 * If socket is connected, only packets coming from connected peer address
kenjiArai 0:5b88d5760320 142 * are accepted.
kenjiArai 0:5b88d5760320 143 *
kenjiArai 0:5b88d5760320 144 * @note recvfrom() is allowed write to address and data buffers even if error occurs.
kenjiArai 0:5b88d5760320 145 *
kenjiArai 0:5b88d5760320 146 * By default, recvfrom blocks until a datagram is received. If socket is set to
kenjiArai 0:5b88d5760320 147 * non-blocking or times out with no data, NSAPI_ERROR_WOULD_BLOCK
kenjiArai 0:5b88d5760320 148 * is returned.
kenjiArai 0:5b88d5760320 149 *
kenjiArai 0:5b88d5760320 150 * @param address Destination for the source address or NULL
kenjiArai 0:5b88d5760320 151 * @param data Destination buffer for datagram received from the host
kenjiArai 0:5b88d5760320 152 * @param size Size of the buffer in bytes
kenjiArai 1:9db0e321a9f4 153 * @return Number of received bytes on success, negative subclass-dependent
kenjiArai 1:9db0e321a9f4 154 * error code on failure
kenjiArai 0:5b88d5760320 155 */
kenjiArai 0:5b88d5760320 156 virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
kenjiArai 0:5b88d5760320 157 void *data, nsapi_size_t size) = 0;
kenjiArai 0:5b88d5760320 158
kenjiArai 0:5b88d5760320 159 /** Bind a specific address to a socket.
kenjiArai 0:5b88d5760320 160 *
kenjiArai 0:5b88d5760320 161 * Binding a socket specifies the address and port on which to receive
kenjiArai 0:5b88d5760320 162 * data. If the IP address is zeroed, only the port is bound.
kenjiArai 0:5b88d5760320 163 *
kenjiArai 0:5b88d5760320 164 * @param address Local address to bind.
kenjiArai 1:9db0e321a9f4 165 * @return NSAPI_ERROR_OK on success, negative subclass-dependent error
kenjiArai 1:9db0e321a9f4 166 * code on failure.
kenjiArai 0:5b88d5760320 167 */
kenjiArai 0:5b88d5760320 168 virtual nsapi_error_t bind(const SocketAddress &address) = 0;
kenjiArai 0:5b88d5760320 169
kenjiArai 0:5b88d5760320 170 /** Set blocking or non-blocking mode of the socket.
kenjiArai 0:5b88d5760320 171 *
kenjiArai 0:5b88d5760320 172 * Initially all sockets are in blocking mode. In non-blocking mode
kenjiArai 0:5b88d5760320 173 * blocking operations such as send/recv/accept return
kenjiArai 0:5b88d5760320 174 * NSAPI_ERROR_WOULD_BLOCK if they cannot continue.
kenjiArai 0:5b88d5760320 175 *
kenjiArai 0:5b88d5760320 176 * set_blocking(false) is equivalent to set_timeout(0)
kenjiArai 0:5b88d5760320 177 * set_blocking(true) is equivalent to set_timeout(-1)
kenjiArai 0:5b88d5760320 178 *
kenjiArai 0:5b88d5760320 179 * @param blocking true for blocking mode, false for non-blocking mode.
kenjiArai 0:5b88d5760320 180 */
kenjiArai 0:5b88d5760320 181 virtual void set_blocking(bool blocking) = 0;
kenjiArai 0:5b88d5760320 182
kenjiArai 0:5b88d5760320 183 /** Set timeout on blocking socket operations.
kenjiArai 0:5b88d5760320 184 *
kenjiArai 0:5b88d5760320 185 * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
kenjiArai 0:5b88d5760320 186 * is returned if a blocking operation takes longer than the specified
kenjiArai 0:5b88d5760320 187 * timeout. A timeout of 0 removes the timeout from the socket. A negative
kenjiArai 0:5b88d5760320 188 * value gives the socket an unbounded timeout.
kenjiArai 0:5b88d5760320 189 *
kenjiArai 0:5b88d5760320 190 * set_timeout(0) is equivalent to set_blocking(false)
kenjiArai 0:5b88d5760320 191 * set_timeout(-1) is equivalent to set_blocking(true)
kenjiArai 0:5b88d5760320 192 *
kenjiArai 0:5b88d5760320 193 * @param timeout Timeout in milliseconds
kenjiArai 0:5b88d5760320 194 */
kenjiArai 0:5b88d5760320 195 virtual void set_timeout(int timeout) = 0;
kenjiArai 0:5b88d5760320 196
kenjiArai 0:5b88d5760320 197 /** Register a callback on state change of the socket.
kenjiArai 0:5b88d5760320 198 *
kenjiArai 0:5b88d5760320 199 * The specified callback is called on state changes, such as when
kenjiArai 0:5b88d5760320 200 * the socket can receive/send/accept successfully and when an error
kenjiArai 0:5b88d5760320 201 * occurs. The callback may also be called spuriously without reason.
kenjiArai 0:5b88d5760320 202 *
kenjiArai 0:5b88d5760320 203 * The callback may be called in an interrupt context and should not
kenjiArai 0:5b88d5760320 204 * perform expensive operations such as receive/send calls.
kenjiArai 0:5b88d5760320 205 *
kenjiArai 0:5b88d5760320 206 * Note! This is not intended as a replacement for a poll or attach-like
kenjiArai 0:5b88d5760320 207 * asynchronous API, but rather as a building block for constructing
kenjiArai 0:5b88d5760320 208 * such functionality. The exact timing of the registered function
kenjiArai 0:5b88d5760320 209 * is not guaranteed and susceptible to change.
kenjiArai 0:5b88d5760320 210 *
kenjiArai 0:5b88d5760320 211 * @param func Function to call on state change.
kenjiArai 0:5b88d5760320 212 */
kenjiArai 0:5b88d5760320 213 virtual void sigio(mbed::Callback<void()> func) = 0;
kenjiArai 0:5b88d5760320 214
kenjiArai 0:5b88d5760320 215 /** Set socket options.
kenjiArai 0:5b88d5760320 216 *
kenjiArai 0:5b88d5760320 217 * setsockopt() allows an application to pass stack-specific options
kenjiArai 0:5b88d5760320 218 * to the underlying stack using stack-specific level and option names,
kenjiArai 0:5b88d5760320 219 * or to request generic options using levels from nsapi_socket_level_t.
kenjiArai 0:5b88d5760320 220 *
kenjiArai 0:5b88d5760320 221 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
kenjiArai 0:5b88d5760320 222 * and the socket is unmodified.
kenjiArai 0:5b88d5760320 223 *
kenjiArai 0:5b88d5760320 224 * @param level Stack-specific protocol level or nsapi_socket_level_t.
kenjiArai 0:5b88d5760320 225 * @param optname Level-specific option name.
kenjiArai 0:5b88d5760320 226 * @param optval Option value.
kenjiArai 0:5b88d5760320 227 * @param optlen Length of the option value.
kenjiArai 1:9db0e321a9f4 228 * @retval NSAPI_ERROR_OK on success.
kenjiArai 1:9db0e321a9f4 229 * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
kenjiArai 1:9db0e321a9f4 230 * @retval int Negative error code on failure, see @ref NetworkStack::setsockopt.
kenjiArai 0:5b88d5760320 231 */
kenjiArai 0:5b88d5760320 232 virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;
kenjiArai 0:5b88d5760320 233
kenjiArai 0:5b88d5760320 234 /** Get socket options.
kenjiArai 0:5b88d5760320 235 *
kenjiArai 0:5b88d5760320 236 * getsockopt() allows an application to retrieve stack-specific options
kenjiArai 0:5b88d5760320 237 * from the underlying stack using stack-specific level and option names,
kenjiArai 0:5b88d5760320 238 * or to request generic options using levels from nsapi_socket_level_t.
kenjiArai 0:5b88d5760320 239 *
kenjiArai 0:5b88d5760320 240 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
kenjiArai 0:5b88d5760320 241 * and the socket is unmodified.
kenjiArai 0:5b88d5760320 242 *
kenjiArai 0:5b88d5760320 243 * @param level Stack-specific protocol level or nsapi_socket_level_t.
kenjiArai 0:5b88d5760320 244 * @param optname Level-specific option name.
kenjiArai 0:5b88d5760320 245 * @param optval Destination for option value.
kenjiArai 0:5b88d5760320 246 * @param optlen Length of the option value.
kenjiArai 1:9db0e321a9f4 247 * @retval NSAPI_ERROR_OK on success.
kenjiArai 1:9db0e321a9f4 248 * @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
kenjiArai 1:9db0e321a9f4 249 * @retval int Negative error code on failure, see @ref NetworkStack::getsockopt.
kenjiArai 0:5b88d5760320 250 */
kenjiArai 0:5b88d5760320 251 virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;
kenjiArai 0:5b88d5760320 252
kenjiArai 0:5b88d5760320 253 /** Accepts a connection on a socket.
kenjiArai 0:5b88d5760320 254 *
kenjiArai 0:5b88d5760320 255 * The server socket must be bound and set to listen for connections.
kenjiArai 0:5b88d5760320 256 * On a new connection, returns connected network socket to call close()
kenjiArai 0:5b88d5760320 257 * that deallocates the resources. Referencing a returned pointer after a close()
kenjiArai 0:5b88d5760320 258 * call is not allowed and leads to undefined behavior.
kenjiArai 0:5b88d5760320 259 *
kenjiArai 0:5b88d5760320 260 * By default, accept blocks until incoming connection occurs. If socket is set to
kenjiArai 0:5b88d5760320 261 * non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
kenjiArai 0:5b88d5760320 262 *
kenjiArai 0:5b88d5760320 263 * @param error Pointer to storage of the error value or NULL.
kenjiArai 0:5b88d5760320 264 * @return Pointer to a socket.
kenjiArai 0:5b88d5760320 265 */
kenjiArai 0:5b88d5760320 266 virtual Socket *accept(nsapi_error_t *error = NULL) = 0;
kenjiArai 0:5b88d5760320 267
kenjiArai 0:5b88d5760320 268 /** Listen for incoming connections.
kenjiArai 0:5b88d5760320 269 *
kenjiArai 0:5b88d5760320 270 * Marks the socket as a passive socket that can be used to accept
kenjiArai 0:5b88d5760320 271 * incoming connections.
kenjiArai 0:5b88d5760320 272 *
kenjiArai 0:5b88d5760320 273 * @param backlog Number of pending connections that can be queued
kenjiArai 0:5b88d5760320 274 * simultaneously, defaults to 1.
kenjiArai 0:5b88d5760320 275 * @return NSAPI_ERROR_OK on success, negative error code on failure.
kenjiArai 0:5b88d5760320 276 */
kenjiArai 0:5b88d5760320 277 virtual nsapi_error_t listen(int backlog = 1) = 0;
kenjiArai 0:5b88d5760320 278
kenjiArai 0:5b88d5760320 279 /** Get the remote-end peer associated with this socket.
kenjiArai 0:5b88d5760320 280 *
kenjiArai 0:5b88d5760320 281 * Copy the remote peer address to a SocketAddress structure pointed by
kenjiArai 0:5b88d5760320 282 * address parameter. Socket must be connected to have a peer address
kenjiArai 0:5b88d5760320 283 * associated.
kenjiArai 0:5b88d5760320 284 *
kenjiArai 0:5b88d5760320 285 * @param address Pointer to SocketAddress structure.
kenjiArai 1:9db0e321a9f4 286 * @retval NSAPI_ERROR_OK on success.
kenjiArai 1:9db0e321a9f4 287 * @retval NSAPI_ERROR_NO_SOCKET if socket is not connected.
kenjiArai 1:9db0e321a9f4 288 * @retval NSAPI_ERROR_NO_CONNECTION if the remote peer was not set.
kenjiArai 0:5b88d5760320 289 */
kenjiArai 0:5b88d5760320 290 virtual nsapi_error_t getpeername(SocketAddress *address) = 0;
kenjiArai 0:5b88d5760320 291 };
kenjiArai 0:5b88d5760320 292
kenjiArai 0:5b88d5760320 293
kenjiArai 0:5b88d5760320 294 #endif
kenjiArai 0:5b88d5760320 295
kenjiArai 0:5b88d5760320 296 /** @}*/