Simon Cooksey / mbed-os

Pinned to some recent date

features/netsocket/Socket.h@0:fb7af294d5d9, 2016-11-17 (annotated)

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

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