Daiki Kato / mbed-os-lychee

mbed-os for GR-LYCHEE

Dependents:   mbed-os-example-blinky-gr-lychee GR-Boads_Camera_sample GR-Boards_Audio_Recoder GR-Boads_Camera_DisplayApp ... more

features/netsocket/Socket.h@0:f782d9c66c49, 2018-02-02 (annotated)

Committer:
dkato
Date:
Fri Feb 02 05:42:23 2018 +0000
Revision:
0:f782d9c66c49
mbed-os for GR-LYCHEE

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dkato 0:f782d9c66c49 1
dkato 0:f782d9c66c49 2 /** \addtogroup netsocket */
dkato 0:f782d9c66c49 3 /** @{*/
dkato 0:f782d9c66c49 4 /* Socket
dkato 0:f782d9c66c49 5 * Copyright (c) 2015 ARM Limited
dkato 0:f782d9c66c49 6 *
dkato 0:f782d9c66c49 7 * Licensed under the Apache License, Version 2.0 (the "License");
dkato 0:f782d9c66c49 8 * you may not use this file except in compliance with the License.
dkato 0:f782d9c66c49 9 * You may obtain a copy of the License at
dkato 0:f782d9c66c49 10 *
dkato 0:f782d9c66c49 11 * http://www.apache.org/licenses/LICENSE-2.0
dkato 0:f782d9c66c49 12 *
dkato 0:f782d9c66c49 13 * Unless required by applicable law or agreed to in writing, software
dkato 0:f782d9c66c49 14 * distributed under the License is distributed on an "AS IS" BASIS,
dkato 0:f782d9c66c49 15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
dkato 0:f782d9c66c49 16 * See the License for the specific language governing permissions and
dkato 0:f782d9c66c49 17 * limitations under the License.
dkato 0:f782d9c66c49 18 */
dkato 0:f782d9c66c49 19
dkato 0:f782d9c66c49 20 #ifndef SOCKET_H
dkato 0:f782d9c66c49 21 #define SOCKET_H
dkato 0:f782d9c66c49 22
dkato 0:f782d9c66c49 23 #include "netsocket/SocketAddress.h"
dkato 0:f782d9c66c49 24 #include "netsocket/NetworkStack.h"
dkato 0:f782d9c66c49 25 #include "rtos/Mutex.h"
dkato 0:f782d9c66c49 26 #include "Callback.h"
dkato 0:f782d9c66c49 27 #include "mbed_toolchain.h"
dkato 0:f782d9c66c49 28
dkato 0:f782d9c66c49 29
dkato 0:f782d9c66c49 30 /** Abstract socket class
dkato 0:f782d9c66c49 31 */
dkato 0:f782d9c66c49 32 class Socket {
dkato 0:f782d9c66c49 33 public:
dkato 0:f782d9c66c49 34 /** Destroy a socket
dkato 0:f782d9c66c49 35 *
dkato 0:f782d9c66c49 36 * Closes socket if the socket is still open
dkato 0:f782d9c66c49 37 */
dkato 0:f782d9c66c49 38 virtual ~Socket() {}
dkato 0:f782d9c66c49 39
dkato 0:f782d9c66c49 40 /** Opens a socket
dkato 0:f782d9c66c49 41 *
dkato 0:f782d9c66c49 42 * Creates a network socket on the network stack of the given
dkato 0:f782d9c66c49 43 * network interface. Not needed if stack is passed to the
dkato 0:f782d9c66c49 44 * socket's constructor.
dkato 0:f782d9c66c49 45 *
dkato 0:f782d9c66c49 46 * @param stack Network stack as target for socket
dkato 0:f782d9c66c49 47 * @return 0 on success, negative error code on failure
dkato 0:f782d9c66c49 48 */
dkato 0:f782d9c66c49 49 nsapi_error_t open(NetworkStack *stack);
dkato 0:f782d9c66c49 50
dkato 0:f782d9c66c49 51 template <typename S>
dkato 0:f782d9c66c49 52 nsapi_error_t open(S *stack) {
dkato 0:f782d9c66c49 53 return open(nsapi_create_stack(stack));
dkato 0:f782d9c66c49 54 }
dkato 0:f782d9c66c49 55
dkato 0:f782d9c66c49 56 /** Close the socket
dkato 0:f782d9c66c49 57 *
dkato 0:f782d9c66c49 58 * Closes any open connection and deallocates any memory associated
dkato 0:f782d9c66c49 59 * with the socket. Called from destructor if socket is not closed.
dkato 0:f782d9c66c49 60 *
dkato 0:f782d9c66c49 61 * @return 0 on success, negative error code on failure
dkato 0:f782d9c66c49 62 */
dkato 0:f782d9c66c49 63 nsapi_error_t close();
dkato 0:f782d9c66c49 64
dkato 0:f782d9c66c49 65 /** Bind a specific address to a socket
dkato 0:f782d9c66c49 66 *
dkato 0:f782d9c66c49 67 * Binding a socket specifies the address and port on which to recieve
dkato 0:f782d9c66c49 68 * data.
dkato 0:f782d9c66c49 69 *
dkato 0:f782d9c66c49 70 * @param port Local port to bind
dkato 0:f782d9c66c49 71 * @return 0 on success, negative error code on failure.
dkato 0:f782d9c66c49 72 */
dkato 0:f782d9c66c49 73 nsapi_error_t bind(uint16_t port);
dkato 0:f782d9c66c49 74
dkato 0:f782d9c66c49 75 /** Bind a specific address to a socket
dkato 0:f782d9c66c49 76 *
dkato 0:f782d9c66c49 77 * Binding a socket specifies the address and port on which to recieve
dkato 0:f782d9c66c49 78 * data. If the IP address is zeroed, only the port is bound.
dkato 0:f782d9c66c49 79 *
dkato 0:f782d9c66c49 80 * @param address Null-terminated local address to bind
dkato 0:f782d9c66c49 81 * @param port Local port to bind
dkato 0:f782d9c66c49 82 * @return 0 on success, negative error code on failure.
dkato 0:f782d9c66c49 83 */
dkato 0:f782d9c66c49 84 nsapi_error_t bind(const char *address, uint16_t port);
dkato 0:f782d9c66c49 85
dkato 0:f782d9c66c49 86 /** Bind a specific address to a socket
dkato 0:f782d9c66c49 87 *
dkato 0:f782d9c66c49 88 * Binding a socket specifies the address and port on which to recieve
dkato 0:f782d9c66c49 89 * data. If the IP address is zeroed, only the port is bound.
dkato 0:f782d9c66c49 90 *
dkato 0:f782d9c66c49 91 * @param address Local address to bind
dkato 0:f782d9c66c49 92 * @return 0 on success, negative error code on failure.
dkato 0:f782d9c66c49 93 */
dkato 0:f782d9c66c49 94 nsapi_error_t bind(const SocketAddress &address);
dkato 0:f782d9c66c49 95
dkato 0:f782d9c66c49 96 /** Set blocking or non-blocking mode of the socket
dkato 0:f782d9c66c49 97 *
dkato 0:f782d9c66c49 98 * Initially all sockets are in blocking mode. In non-blocking mode
dkato 0:f782d9c66c49 99 * blocking operations such as send/recv/accept return
dkato 0:f782d9c66c49 100 * NSAPI_ERROR_WOULD_BLOCK if they can not continue.
dkato 0:f782d9c66c49 101 *
dkato 0:f782d9c66c49 102 * set_blocking(false) is equivalent to set_timeout(-1)
dkato 0:f782d9c66c49 103 * set_blocking(true) is equivalent to set_timeout(0)
dkato 0:f782d9c66c49 104 *
dkato 0:f782d9c66c49 105 * @param blocking true for blocking mode, false for non-blocking mode.
dkato 0:f782d9c66c49 106 */
dkato 0:f782d9c66c49 107 void set_blocking(bool blocking);
dkato 0:f782d9c66c49 108
dkato 0:f782d9c66c49 109 /** Set timeout on blocking socket operations
dkato 0:f782d9c66c49 110 *
dkato 0:f782d9c66c49 111 * Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
dkato 0:f782d9c66c49 112 * is returned if a blocking operation takes longer than the specified
dkato 0:f782d9c66c49 113 * timeout. A timeout of 0 removes the timeout from the socket. A negative
dkato 0:f782d9c66c49 114 * value give the socket an unbounded timeout.
dkato 0:f782d9c66c49 115 *
dkato 0:f782d9c66c49 116 * set_timeout(0) is equivalent to set_blocking(false)
dkato 0:f782d9c66c49 117 * set_timeout(-1) is equivalent to set_blocking(true)
dkato 0:f782d9c66c49 118 *
dkato 0:f782d9c66c49 119 * @param timeout Timeout in milliseconds
dkato 0:f782d9c66c49 120 */
dkato 0:f782d9c66c49 121 void set_timeout(int timeout);
dkato 0:f782d9c66c49 122
dkato 0:f782d9c66c49 123 /* Set socket options
dkato 0:f782d9c66c49 124 *
dkato 0:f782d9c66c49 125 * setsockopt allows an application to pass stack-specific options
dkato 0:f782d9c66c49 126 * to the underlying stack using stack-specific level and option names,
dkato 0:f782d9c66c49 127 * or to request generic options using levels from nsapi_socket_level_t.
dkato 0:f782d9c66c49 128 *
dkato 0:f782d9c66c49 129 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
dkato 0:f782d9c66c49 130 * and the socket is unmodified.
dkato 0:f782d9c66c49 131 *
dkato 0:f782d9c66c49 132 * @param level Stack-specific protocol level or nsapi_socket_level_t
dkato 0:f782d9c66c49 133 * @param optname Level-specific option name
dkato 0:f782d9c66c49 134 * @param optval Option value
dkato 0:f782d9c66c49 135 * @param optlen Length of the option value
dkato 0:f782d9c66c49 136 * @return 0 on success, negative error code on failure
dkato 0:f782d9c66c49 137 */
dkato 0:f782d9c66c49 138 nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);
dkato 0:f782d9c66c49 139
dkato 0:f782d9c66c49 140 /* Get socket options
dkato 0:f782d9c66c49 141 *
dkato 0:f782d9c66c49 142 * getsockopt allows an application to retrieve stack-specific options
dkato 0:f782d9c66c49 143 * from the underlying stack using stack-specific level and option names,
dkato 0:f782d9c66c49 144 * or to request generic options using levels from nsapi_socket_level_t.
dkato 0:f782d9c66c49 145 *
dkato 0:f782d9c66c49 146 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
dkato 0:f782d9c66c49 147 * and the socket is unmodified.
dkato 0:f782d9c66c49 148 *
dkato 0:f782d9c66c49 149 * @param level Stack-specific protocol level or nsapi_socket_level_t
dkato 0:f782d9c66c49 150 * @param optname Level-specific option name
dkato 0:f782d9c66c49 151 * @param optval Destination for option value
dkato 0:f782d9c66c49 152 * @param optlen Length of the option value
dkato 0:f782d9c66c49 153 * @return 0 on success, negative error code on failure
dkato 0:f782d9c66c49 154 */
dkato 0:f782d9c66c49 155 nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen);
dkato 0:f782d9c66c49 156
dkato 0:f782d9c66c49 157 /** Register a callback on state change of the socket
dkato 0:f782d9c66c49 158 *
dkato 0:f782d9c66c49 159 * The specified callback will be called on state changes such as when
dkato 0:f782d9c66c49 160 * the socket can recv/send/accept successfully and on when an error
dkato 0:f782d9c66c49 161 * occurs. The callback may also be called spuriously without reason.
dkato 0:f782d9c66c49 162 *
dkato 0:f782d9c66c49 163 * The callback may be called in an interrupt context and should not
dkato 0:f782d9c66c49 164 * perform expensive operations such as recv/send calls.
dkato 0:f782d9c66c49 165 *
dkato 0:f782d9c66c49 166 * Note! This is not intended as a replacement for a poll or attach-like
dkato 0:f782d9c66c49 167 * asynchronous api, but rather as a building block for constructing
dkato 0:f782d9c66c49 168 * such functionality. The exact timing of when the registered function
dkato 0:f782d9c66c49 169 * is called is not guaranteed and susceptible to change.
dkato 0:f782d9c66c49 170 *
dkato 0:f782d9c66c49 171 * @param func Function to call on state change
dkato 0:f782d9c66c49 172 */
dkato 0:f782d9c66c49 173 void sigio(mbed::Callback<void()> func);
dkato 0:f782d9c66c49 174
dkato 0:f782d9c66c49 175 /** Register a callback on state change of the socket
dkato 0:f782d9c66c49 176 *
dkato 0:f782d9c66c49 177 * @see Socket::sigio
dkato 0:f782d9c66c49 178 * @deprecated
dkato 0:f782d9c66c49 179 * The behaviour of Socket::attach differs from other attach functions in
dkato 0:f782d9c66c49 180 * mbed OS and has been known to cause confusion. Replaced by Socket::sigio.
dkato 0:f782d9c66c49 181 */
dkato 0:f782d9c66c49 182 MBED_DEPRECATED_SINCE("mbed-os-5.4",
dkato 0:f782d9c66c49 183 "The behaviour of Socket::attach differs from other attach functions in "
dkato 0:f782d9c66c49 184 "mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
dkato 0:f782d9c66c49 185 void attach(mbed::Callback<void()> func);
dkato 0:f782d9c66c49 186
dkato 0:f782d9c66c49 187 /** Register a callback on state change of the socket
dkato 0:f782d9c66c49 188 *
dkato 0:f782d9c66c49 189 * @see Socket::sigio
dkato 0:f782d9c66c49 190 * @deprecated
dkato 0:f782d9c66c49 191 * The attach function does not support cv-qualifiers. Replaced by
dkato 0:f782d9c66c49 192 * attach(callback(obj, method)).
dkato 0:f782d9c66c49 193 */
dkato 0:f782d9c66c49 194 template <typename T, typename M>
dkato 0:f782d9c66c49 195 MBED_DEPRECATED_SINCE("mbed-os-5.1",
dkato 0:f782d9c66c49 196 "The attach function does not support cv-qualifiers. Replaced by "
dkato 0:f782d9c66c49 197 "attach(callback(obj, method)).")
dkato 0:f782d9c66c49 198 void attach(T *obj, M method) {
dkato 0:f782d9c66c49 199 attach(mbed::callback(obj, method));
dkato 0:f782d9c66c49 200 }
dkato 0:f782d9c66c49 201
dkato 0:f782d9c66c49 202 protected:
dkato 0:f782d9c66c49 203 Socket();
dkato 0:f782d9c66c49 204 virtual nsapi_protocol_t get_proto() = 0;
dkato 0:f782d9c66c49 205 virtual void event() = 0;
dkato 0:f782d9c66c49 206
dkato 0:f782d9c66c49 207 NetworkStack *_stack;
dkato 0:f782d9c66c49 208 nsapi_socket_t _socket;
dkato 0:f782d9c66c49 209 uint32_t _timeout;
dkato 0:f782d9c66c49 210 mbed::Callback<void()> _event;
dkato 0:f782d9c66c49 211 mbed::Callback<void()> _callback;
dkato 0:f782d9c66c49 212 rtos::Mutex _lock;
dkato 0:f782d9c66c49 213 };
dkato 0:f782d9c66c49 214
dkato 0:f782d9c66c49 215
dkato 0:f782d9c66c49 216 #endif
dkato 0:f782d9c66c49 217
dkato 0:f782d9c66c49 218 /** @}*/