Nicolas Borla / Mbed OS BBR_1Ebene

BBR 1 Ebene

mbed-os/features/netsocket/Socket.h@0:fbdae7e6d805, 2018-05-14 (annotated)

Committer:
borlanic
Date:
Mon May 14 11:29:06 2018 +0000
Revision:
0:fbdae7e6d805
BBR

Who changed what in which revision?

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