Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/features/netsocket/Socket.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

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