Lee Kai Xuan / mbed-os

mbed-os

Fork of mbed-os by erkin yucel

features/netsocket/Socket.h@1:3deb71413561, 2017-07-20 (annotated)

Committer:
xuaner
Date:
Thu Jul 20 14:26:57 2017 +0000
Revision:
1:3deb71413561
Parent:
0:f269e3021894 
mbed_os

Who changed what in which revision?

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