Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

features/netsocket/Socket.h@0:5b88d5760320, 2019-12-17 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 17 23:23:45 2019 +0000
Revision:
0:5b88d5760320
Child:
1:9db0e321a9f4
mbed-os5 only for TYBLE16

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 0:5b88d5760320 52 * @return NSAPI_ERROR_OK on success, negative error code on failure
kenjiArai 0:5b88d5760320 53 */
kenjiArai 0:5b88d5760320 54 virtual nsapi_error_t close() = 0;
kenjiArai 0:5b88d5760320 55
kenjiArai 0:5b88d5760320 56 /** Connects socket to a remote address.
kenjiArai 0:5b88d5760320 57 *
kenjiArai 0:5b88d5760320 58 * Attempts to make connection on connection-mode protocol or set or reset
kenjiArai 0:5b88d5760320 59 * the peer address on connectionless protocol.
kenjiArai 0:5b88d5760320 60 *
kenjiArai 0:5b88d5760320 61 * Connectionless protocols also use the connected address to filter
kenjiArai 0:5b88d5760320 62 * incoming packets for recv() and recvfrom() calls.
kenjiArai 0:5b88d5760320 63 *
kenjiArai 0:5b88d5760320 64 * To reset the peer address, there must be zero initialized(default constructor) SocketAddress
kenjiArai 0:5b88d5760320 65 * objects in the address parameter.
kenjiArai 0:5b88d5760320 66 *
kenjiArai 0:5b88d5760320 67 * @note If connect() fails it is recommended to close the Socket and create
kenjiArai 0:5b88d5760320 68 * a new one before attempting to reconnect.
kenjiArai 0:5b88d5760320 69 *
kenjiArai 0:5b88d5760320 70 * @param address The SocketAddress of the remote peer.
kenjiArai 0:5b88d5760320 71 * @return NSAPI_ERROR_OK on success, negative error code on failure.
kenjiArai 0:5b88d5760320 72 */
kenjiArai 0:5b88d5760320 73 virtual nsapi_error_t connect(const SocketAddress &address) = 0;
kenjiArai 0:5b88d5760320 74
kenjiArai 0:5b88d5760320 75 /** Send data on a socket
kenjiArai 0:5b88d5760320 76 *
kenjiArai 0:5b88d5760320 77 * The socket must be connected to a remote host before send() call.
kenjiArai 0:5b88d5760320 78 * Returns the number of bytes sent from the buffer.
kenjiArai 0:5b88d5760320 79 * In case of connectionless socket, sends data to pre-specified remote.
kenjiArai 0:5b88d5760320 80 *
kenjiArai 0:5b88d5760320 81 * By default, send blocks until all data is sent. If socket is set to
kenjiArai 0:5b88d5760320 82 * non-blocking or times out, a partial amount can be written.
kenjiArai 0:5b88d5760320 83 * NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
kenjiArai 0:5b88d5760320 84 *
kenjiArai 0:5b88d5760320 85 * @param data Buffer of data to send to the host.
kenjiArai 0:5b88d5760320 86 * @param size Size of the buffer in bytes.
kenjiArai 0:5b88d5760320 87 * @return Number of sent bytes on success, negative error
kenjiArai 0:5b88d5760320 88 * code on failure.
kenjiArai 0:5b88d5760320 89 */
kenjiArai 0:5b88d5760320 90 virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size) = 0;
kenjiArai 0:5b88d5760320 91
kenjiArai 0:5b88d5760320 92 /** Receive data from a socket.
kenjiArai 0:5b88d5760320 93 *
kenjiArai 0:5b88d5760320 94 * Receive data from connected socket, or in the case of connectionless socket,
kenjiArai 0:5b88d5760320 95 * equivalent to calling recvfrom(NULL, data, size).
kenjiArai 0:5b88d5760320 96 *
kenjiArai 0:5b88d5760320 97 * If socket is connected, only packets coming from connected peer address
kenjiArai 0:5b88d5760320 98 * are accepted.
kenjiArai 0:5b88d5760320 99 *
kenjiArai 0:5b88d5760320 100 * @note recv() is allowed write to data buffer even if an error occurs.
kenjiArai 0:5b88d5760320 101 *
kenjiArai 0:5b88d5760320 102 * By default, recv blocks until some data is received. If socket is set to
kenjiArai 0:5b88d5760320 103 * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
kenjiArai 0:5b88d5760320 104 * indicate no data.
kenjiArai 0:5b88d5760320 105 *
kenjiArai 0:5b88d5760320 106 * @param data Destination buffer for data received from the host.
kenjiArai 0:5b88d5760320 107 * @param size Size of the buffer in bytes.
kenjiArai 0:5b88d5760320 108 * @return Number of received bytes on success, negative error
kenjiArai 0:5b88d5760320 109 * code on failure. If no data is available to be received
kenjiArai 0:5b88d5760320 110 * and the peer has performed an orderly shutdown,
kenjiArai 0:5b88d5760320 111 * recv() returns 0.
kenjiArai 0:5b88d5760320 112 */
kenjiArai 0:5b88d5760320 113 virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size) = 0;
kenjiArai 0:5b88d5760320 114
kenjiArai 0:5b88d5760320 115 /** Send a message on a socket.
kenjiArai 0:5b88d5760320 116 *
kenjiArai 0:5b88d5760320 117 * The sendto() function sends a message through a connection-mode or connectionless-mode socket.
kenjiArai 0:5b88d5760320 118 * If the socket is a connectionless-mode socket, the message is sent to the address specified.
kenjiArai 0:5b88d5760320 119 * If the socket is a connected-mode socket, address is ignored.
kenjiArai 0:5b88d5760320 120 *
kenjiArai 0:5b88d5760320 121 * By default, sendto blocks until data is sent. If socket is set to
kenjiArai 0:5b88d5760320 122 * non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
kenjiArai 0:5b88d5760320 123 * immediately.
kenjiArai 0:5b88d5760320 124 *
kenjiArai 0:5b88d5760320 125 * @param address Remote address
kenjiArai 0:5b88d5760320 126 * @param data Buffer of data to send to the host
kenjiArai 0:5b88d5760320 127 * @param size Size of the buffer in bytes
kenjiArai 0:5b88d5760320 128 * @return Number of sent bytes on success, negative error
kenjiArai 0:5b88d5760320 129 * code on failure
kenjiArai 0:5b88d5760320 130 */
kenjiArai 0:5b88d5760320 131 virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
kenjiArai 0:5b88d5760320 132 const void *data, nsapi_size_t size) = 0;
kenjiArai 0:5b88d5760320 133
kenjiArai 0:5b88d5760320 134 /** Receive a data from a socket
kenjiArai 0:5b88d5760320 135 *
kenjiArai 0:5b88d5760320 136 * Receives a data and stores the source address in address if address
kenjiArai 0:5b88d5760320 137 * is not NULL. Returns the number of bytes written into the buffer.
kenjiArai 0:5b88d5760320 138 *
kenjiArai 0:5b88d5760320 139 * If socket is connected, only packets coming from connected peer address
kenjiArai 0:5b88d5760320 140 * are accepted.
kenjiArai 0:5b88d5760320 141 *
kenjiArai 0:5b88d5760320 142 * @note recvfrom() is allowed write to address and data buffers even if error occurs.
kenjiArai 0:5b88d5760320 143 *
kenjiArai 0:5b88d5760320 144 * By default, recvfrom blocks until a datagram is received. If socket is set to
kenjiArai 0:5b88d5760320 145 * non-blocking or times out with no data, NSAPI_ERROR_WOULD_BLOCK
kenjiArai 0:5b88d5760320 146 * is returned.
kenjiArai 0:5b88d5760320 147 *
kenjiArai 0:5b88d5760320 148 * @param address Destination for the source address or NULL
kenjiArai 0:5b88d5760320 149 * @param data Destination buffer for datagram received from the host
kenjiArai 0:5b88d5760320 150 * @param size Size of the buffer in bytes
kenjiArai 0:5b88d5760320 151 * @return Number of received bytes on success, negative error
kenjiArai 0:5b88d5760320 152 * code on failure
kenjiArai 0:5b88d5760320 153 */
kenjiArai 0:5b88d5760320 154 virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
kenjiArai 0:5b88d5760320 155 void *data, nsapi_size_t size) = 0;
kenjiArai 0:5b88d5760320 156
kenjiArai 0:5b88d5760320 157 /** Bind a specific address to a socket.
kenjiArai 0:5b88d5760320 158 *
kenjiArai 0:5b88d5760320 159 * Binding a socket specifies the address and port on which to receive
kenjiArai 0:5b88d5760320 160 * data. If the IP address is zeroed, only the port is bound.
kenjiArai 0:5b88d5760320 161 *
kenjiArai 0:5b88d5760320 162 * @param address Local address to bind.
kenjiArai 0:5b88d5760320 163 * @return NSAPI_ERROR_OK on success, negative error code on failure.
kenjiArai 0:5b88d5760320 164 */
kenjiArai 0:5b88d5760320 165 virtual nsapi_error_t bind(const SocketAddress &address) = 0;
kenjiArai 0:5b88d5760320 166
kenjiArai 0:5b88d5760320 167 /** Set blocking or non-blocking mode of the socket.
kenjiArai 0:5b88d5760320 168 *
kenjiArai 0:5b88d5760320 169 * Initially all sockets are in blocking mode. In non-blocking mode
kenjiArai 0:5b88d5760320 170 * blocking operations such as send/recv/accept return
kenjiArai 0:5b88d5760320 171 * NSAPI_ERROR_WOULD_BLOCK if they cannot continue.
kenjiArai 0:5b88d5760320 172 *
kenjiArai 0:5b88d5760320 173 * set_blocking(false) is equivalent to set_timeout(0)
kenjiArai 0:5b88d5760320 174 * set_blocking(true) is equivalent to set_timeout(-1)
kenjiArai 0:5b88d5760320 175 *
kenjiArai 0:5b88d5760320 176 * @param blocking true for blocking mode, false for non-blocking mode.
kenjiArai 0:5b88d5760320 177 */
kenjiArai 0:5b88d5760320 178 virtual void set_blocking(bool blocking) = 0;
kenjiArai 0:5b88d5760320 179
kenjiArai 0:5b88d5760320 180 /** Set timeout on blocking socket operations.
kenjiArai 0:5b88d5760320 181 *
kenjiArai 0:5b88d5760320 182 * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
kenjiArai 0:5b88d5760320 183 * is returned if a blocking operation takes longer than the specified
kenjiArai 0:5b88d5760320 184 * timeout. A timeout of 0 removes the timeout from the socket. A negative
kenjiArai 0:5b88d5760320 185 * value gives the socket an unbounded timeout.
kenjiArai 0:5b88d5760320 186 *
kenjiArai 0:5b88d5760320 187 * set_timeout(0) is equivalent to set_blocking(false)
kenjiArai 0:5b88d5760320 188 * set_timeout(-1) is equivalent to set_blocking(true)
kenjiArai 0:5b88d5760320 189 *
kenjiArai 0:5b88d5760320 190 * @param timeout Timeout in milliseconds
kenjiArai 0:5b88d5760320 191 */
kenjiArai 0:5b88d5760320 192 virtual void set_timeout(int timeout) = 0;
kenjiArai 0:5b88d5760320 193
kenjiArai 0:5b88d5760320 194 /** Register a callback on state change of the socket.
kenjiArai 0:5b88d5760320 195 *
kenjiArai 0:5b88d5760320 196 * The specified callback is called on state changes, such as when
kenjiArai 0:5b88d5760320 197 * the socket can receive/send/accept successfully and when an error
kenjiArai 0:5b88d5760320 198 * occurs. The callback may also be called spuriously without reason.
kenjiArai 0:5b88d5760320 199 *
kenjiArai 0:5b88d5760320 200 * The callback may be called in an interrupt context and should not
kenjiArai 0:5b88d5760320 201 * perform expensive operations such as receive/send calls.
kenjiArai 0:5b88d5760320 202 *
kenjiArai 0:5b88d5760320 203 * Note! This is not intended as a replacement for a poll or attach-like
kenjiArai 0:5b88d5760320 204 * asynchronous API, but rather as a building block for constructing
kenjiArai 0:5b88d5760320 205 * such functionality. The exact timing of the registered function
kenjiArai 0:5b88d5760320 206 * is not guaranteed and susceptible to change.
kenjiArai 0:5b88d5760320 207 *
kenjiArai 0:5b88d5760320 208 * @param func Function to call on state change.
kenjiArai 0:5b88d5760320 209 */
kenjiArai 0:5b88d5760320 210 virtual void sigio(mbed::Callback<void()> func) = 0;
kenjiArai 0:5b88d5760320 211
kenjiArai 0:5b88d5760320 212 /** Set socket options.
kenjiArai 0:5b88d5760320 213 *
kenjiArai 0:5b88d5760320 214 * setsockopt() allows an application to pass stack-specific options
kenjiArai 0:5b88d5760320 215 * to the underlying stack using stack-specific level and option names,
kenjiArai 0:5b88d5760320 216 * or to request generic options using levels from nsapi_socket_level_t.
kenjiArai 0:5b88d5760320 217 *
kenjiArai 0:5b88d5760320 218 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
kenjiArai 0:5b88d5760320 219 * and the socket is unmodified.
kenjiArai 0:5b88d5760320 220 *
kenjiArai 0:5b88d5760320 221 * @param level Stack-specific protocol level or nsapi_socket_level_t.
kenjiArai 0:5b88d5760320 222 * @param optname Level-specific option name.
kenjiArai 0:5b88d5760320 223 * @param optval Option value.
kenjiArai 0:5b88d5760320 224 * @param optlen Length of the option value.
kenjiArai 0:5b88d5760320 225 * @return NSAPI_ERROR_OK on success, negative error code on failure.
kenjiArai 0:5b88d5760320 226 */
kenjiArai 0:5b88d5760320 227 virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;
kenjiArai 0:5b88d5760320 228
kenjiArai 0:5b88d5760320 229 /** Get socket options.
kenjiArai 0:5b88d5760320 230 *
kenjiArai 0:5b88d5760320 231 * getsockopt() allows an application to retrieve stack-specific options
kenjiArai 0:5b88d5760320 232 * from the underlying stack using stack-specific level and option names,
kenjiArai 0:5b88d5760320 233 * or to request generic options using levels from nsapi_socket_level_t.
kenjiArai 0:5b88d5760320 234 *
kenjiArai 0:5b88d5760320 235 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
kenjiArai 0:5b88d5760320 236 * and the socket is unmodified.
kenjiArai 0:5b88d5760320 237 *
kenjiArai 0:5b88d5760320 238 * @param level Stack-specific protocol level or nsapi_socket_level_t.
kenjiArai 0:5b88d5760320 239 * @param optname Level-specific option name.
kenjiArai 0:5b88d5760320 240 * @param optval Destination for option value.
kenjiArai 0:5b88d5760320 241 * @param optlen Length of the option value.
kenjiArai 0:5b88d5760320 242 * @return NSAPI_ERROR_OK on success, negative error code on failure.
kenjiArai 0:5b88d5760320 243 */
kenjiArai 0:5b88d5760320 244 virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;
kenjiArai 0:5b88d5760320 245
kenjiArai 0:5b88d5760320 246 /** Accepts a connection on a socket.
kenjiArai 0:5b88d5760320 247 *
kenjiArai 0:5b88d5760320 248 * The server socket must be bound and set to listen for connections.
kenjiArai 0:5b88d5760320 249 * On a new connection, returns connected network socket to call close()
kenjiArai 0:5b88d5760320 250 * that deallocates the resources. Referencing a returned pointer after a close()
kenjiArai 0:5b88d5760320 251 * call is not allowed and leads to undefined behavior.
kenjiArai 0:5b88d5760320 252 *
kenjiArai 0:5b88d5760320 253 * By default, accept blocks until incoming connection occurs. If socket is set to
kenjiArai 0:5b88d5760320 254 * non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
kenjiArai 0:5b88d5760320 255 *
kenjiArai 0:5b88d5760320 256 * @param error Pointer to storage of the error value or NULL.
kenjiArai 0:5b88d5760320 257 * @return Pointer to a socket.
kenjiArai 0:5b88d5760320 258 */
kenjiArai 0:5b88d5760320 259 virtual Socket *accept(nsapi_error_t *error = NULL) = 0;
kenjiArai 0:5b88d5760320 260
kenjiArai 0:5b88d5760320 261 /** Listen for incoming connections.
kenjiArai 0:5b88d5760320 262 *
kenjiArai 0:5b88d5760320 263 * Marks the socket as a passive socket that can be used to accept
kenjiArai 0:5b88d5760320 264 * incoming connections.
kenjiArai 0:5b88d5760320 265 *
kenjiArai 0:5b88d5760320 266 * @param backlog Number of pending connections that can be queued
kenjiArai 0:5b88d5760320 267 * simultaneously, defaults to 1.
kenjiArai 0:5b88d5760320 268 * @return NSAPI_ERROR_OK on success, negative error code on failure.
kenjiArai 0:5b88d5760320 269 */
kenjiArai 0:5b88d5760320 270 virtual nsapi_error_t listen(int backlog = 1) = 0;
kenjiArai 0:5b88d5760320 271
kenjiArai 0:5b88d5760320 272 /** Get the remote-end peer associated with this socket.
kenjiArai 0:5b88d5760320 273 *
kenjiArai 0:5b88d5760320 274 * Copy the remote peer address to a SocketAddress structure pointed by
kenjiArai 0:5b88d5760320 275 * address parameter. Socket must be connected to have a peer address
kenjiArai 0:5b88d5760320 276 * associated.
kenjiArai 0:5b88d5760320 277 *
kenjiArai 0:5b88d5760320 278 * @param address Pointer to SocketAddress structure.
kenjiArai 0:5b88d5760320 279 * @return NSAPI_ERROR_OK on success, negative error code on failure.
kenjiArai 0:5b88d5760320 280 */
kenjiArai 0:5b88d5760320 281 virtual nsapi_error_t getpeername(SocketAddress *address) = 0;
kenjiArai 0:5b88d5760320 282 };
kenjiArai 0:5b88d5760320 283
kenjiArai 0:5b88d5760320 284
kenjiArai 0:5b88d5760320 285 #endif
kenjiArai 0:5b88d5760320 286
kenjiArai 0:5b88d5760320 287 /** @}*/