Daniel Vizcaya / Mbed OS 04_RTOS_Embebidos

Entrega 3er corte - sistemas embebidos

mbed-os/features/netsocket/Socket.h@1:fcdb45ee95b9, 2018-05-30 (annotated)

Committer:
Bethory
Date:
Wed May 30 04:46:28 2018 +0000
Revision:
1:fcdb45ee95b9
Parent:
0:6ad07c9019fd 
Entrega Final

Who changed what in which revision?

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