DongEun Koak / NetworkSocketAPI

NetworkSocketAPI

Dependencies:   DnsQuery

Dependents:   HelloWizFi250Interface

Fork of NetworkSocketAPI by NetworkSocketAPI

NetworkInterface.h@91:cad29ce6a01c, 2016-04-19 (annotated)

Committer:
Christopher Haster
Date:
Tue Apr 19 18:23:12 2016 -0500
Revision:
91:cad29ce6a01c
Parent:
89:b1d417383c0d
Child:
92:dd5f19874adf
Remove shutdown parameter from close call



Pros

- Simplifies interface

- Easier base implementation



Cons

- May need shutdown functionality, in this case shutdown

  can be added as another function in the future

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 89:b1d417383c0d 1 /* Socket
Christopher Haster 89:b1d417383c0d 2 * Copyright (c) 2015 ARM Limited
Christopher Haster 89:b1d417383c0d 3 *
Christopher Haster 89:b1d417383c0d 4 * Licensed under the Apache License, Version 2.0 (the "License");
Christopher Haster 89:b1d417383c0d 5 * you may not use this file except in compliance with the License.
Christopher Haster 89:b1d417383c0d 6 * You may obtain a copy of the License at
Christopher Haster 89:b1d417383c0d 7 *
Christopher Haster 89:b1d417383c0d 8 * http://www.apache.org/licenses/LICENSE-2.0
Christopher Haster 89:b1d417383c0d 9 *
Christopher Haster 89:b1d417383c0d 10 * Unless required by applicable law or agreed to in writing, software
Christopher Haster 89:b1d417383c0d 11 * distributed under the License is distributed on an "AS IS" BASIS,
Christopher Haster 89:b1d417383c0d 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Christopher Haster 89:b1d417383c0d 13 * See the License for the specific language governing permissions and
Christopher Haster 89:b1d417383c0d 14 * limitations under the License.
Christopher Haster 89:b1d417383c0d 15 */
Christopher Haster 89:b1d417383c0d 16
Christopher Haster 89:b1d417383c0d 17 #ifndef NETWORK_INTERFACE_H
Christopher Haster 89:b1d417383c0d 18 #define NETWORK_INTERFACE_H
Christopher Haster 89:b1d417383c0d 19
Christopher Haster 89:b1d417383c0d 20 #include "mbed.h"
Christopher Haster 89:b1d417383c0d 21 #include "SocketAddress.h"
Christopher Haster 89:b1d417383c0d 22
Christopher Haster 89:b1d417383c0d 23 /** Enum of standardized error codes
Christopher Haster 89:b1d417383c0d 24 * @enum ns_error_t
Christopher Haster 89:b1d417383c0d 25 */
Christopher Haster 89:b1d417383c0d 26 enum nsapi_error_t {
Christopher Haster 89:b1d417383c0d 27 NSAPI_ERROR_WOULD_BLOCK = -3001, /*!< no data is not available but call is non-blocking */
Christopher Haster 89:b1d417383c0d 28 NSAPI_ERROR_UNSUPPORTED = -3002, /*!< unsupported configuration */
Christopher Haster 89:b1d417383c0d 29 NSAPI_ERROR_NO_CONNECTION = -3003, /*!< not connected to a network */
Christopher Haster 89:b1d417383c0d 30 NSAPI_ERROR_NO_SOCKET = -3004, /*!< socket not available for use */
Christopher Haster 89:b1d417383c0d 31 NSAPI_ERROR_NO_ADDRESS = -3005, /*!< IP address is not known */
Christopher Haster 89:b1d417383c0d 32 NSAPI_ERROR_NO_MEMORY = -3006, /*!< memory resource not available */
Christopher Haster 89:b1d417383c0d 33 NSAPI_ERROR_DNS_FAILURE = -3007, /*!< DNS failed to complete successfully */
Christopher Haster 89:b1d417383c0d 34 NSAPI_ERROR_DHCP_FAILURE = -3008, /*!< DHCP failed to complete successfully */
Christopher Haster 89:b1d417383c0d 35 NSAPI_ERROR_AUTH_FAILURE = -3009, /*!< connection to access point faield */
Christopher Haster 89:b1d417383c0d 36 NSAPI_ERROR_DEVICE_ERROR = -3010, /*!< failure interfacing with the network procesor */
Christopher Haster 89:b1d417383c0d 37 };
Christopher Haster 89:b1d417383c0d 38
Christopher Haster 89:b1d417383c0d 39 /** Enum of available options
Christopher Haster 89:b1d417383c0d 40 * @enum ns_opt_t
Christopher Haster 89:b1d417383c0d 41 */
Christopher Haster 89:b1d417383c0d 42 enum ns_opt_t {
Christopher Haster 89:b1d417383c0d 43 };
Christopher Haster 89:b1d417383c0d 44
Christopher Haster 89:b1d417383c0d 45 /** Enum of socket protocols
Christopher Haster 89:b1d417383c0d 46 * @enum protocol_t
Christopher Haster 89:b1d417383c0d 47 */
Christopher Haster 89:b1d417383c0d 48 enum nsapi_protocol_t {
Christopher Haster 89:b1d417383c0d 49 NSAPI_TCP, /*!< Socket is of TCP type */
Christopher Haster 89:b1d417383c0d 50 NSAPI_UDP, /*!< Socket is of UDP type */
Christopher Haster 89:b1d417383c0d 51 };
Christopher Haster 89:b1d417383c0d 52
Christopher Haster 89:b1d417383c0d 53 /** NetworkInterface class
Christopher Haster 89:b1d417383c0d 54 * Common interface that is shared between all hardware that
Christopher Haster 89:b1d417383c0d 55 * can connect to a network over IP.
Christopher Haster 89:b1d417383c0d 56 */
Christopher Haster 89:b1d417383c0d 57 class NetworkInterface
Christopher Haster 89:b1d417383c0d 58 {
Christopher Haster 89:b1d417383c0d 59 public:
Christopher Haster 89:b1d417383c0d 60 virtual ~NetworkInterface() {};
Christopher Haster 89:b1d417383c0d 61
Christopher Haster 89:b1d417383c0d 62 /** Get the internally stored IP address
Christopher Haster 89:b1d417383c0d 63 * @return IP address of the interface or null if not yet connected
Christopher Haster 89:b1d417383c0d 64 */
Christopher Haster 89:b1d417383c0d 65 virtual const char *get_ip_address() = 0;
Christopher Haster 89:b1d417383c0d 66
Christopher Haster 89:b1d417383c0d 67 /** Get the internally stored MAC address
Christopher Haster 89:b1d417383c0d 68 * @return MAC address of the interface
Christopher Haster 89:b1d417383c0d 69 */
Christopher Haster 89:b1d417383c0d 70 virtual const char *get_mac_address() = 0;
Christopher Haster 89:b1d417383c0d 71
Christopher Haster 89:b1d417383c0d 72 /** Get the current status of the interface
Christopher Haster 89:b1d417383c0d 73 * @return true if connected
Christopher Haster 89:b1d417383c0d 74 */
Christopher Haster 89:b1d417383c0d 75 virtual bool is_connected() {
Christopher Haster 89:b1d417383c0d 76 return get_ip_address() != NULL;
Christopher Haster 89:b1d417383c0d 77 }
Christopher Haster 89:b1d417383c0d 78
Christopher Haster 89:b1d417383c0d 79 /** Looks up the specified host's IP address
Christopher Haster 89:b1d417383c0d 80 * @param name Hostname to lookup
Christopher Haster 89:b1d417383c0d 81 * @param dest Destination for IP address, must have space for SocketAddress::IP_SIZE
Christopher Haster 89:b1d417383c0d 82 * @return 0 on success, negative on failure
Christopher Haster 89:b1d417383c0d 83 */
Christopher Haster 89:b1d417383c0d 84 virtual int gethostbyname(const char *name, char *dest);
Christopher Haster 89:b1d417383c0d 85
Christopher Haster 89:b1d417383c0d 86 protected:
Christopher Haster 89:b1d417383c0d 87 friend class Socket;
Christopher Haster 89:b1d417383c0d 88 friend class UDPSocket;
Christopher Haster 89:b1d417383c0d 89 friend class TCPSocket;
Christopher Haster 89:b1d417383c0d 90 friend class TCPServer;
Christopher Haster 89:b1d417383c0d 91
Christopher Haster 89:b1d417383c0d 92 /** Create a socket
Christopher Haster 89:b1d417383c0d 93 * @param proto The type of socket to open, TCP or UDP
Christopher Haster 89:b1d417383c0d 94 * @return The alocated socket or null on failure
Christopher Haster 89:b1d417383c0d 95 */
Christopher Haster 89:b1d417383c0d 96 virtual void *socket_create(nsapi_protocol_t proto) = 0;
Christopher Haster 89:b1d417383c0d 97
Christopher Haster 89:b1d417383c0d 98 /** Destroy a socket
Christopher Haster 89:b1d417383c0d 99 * @param socket Previously allocated socket
Christopher Haster 89:b1d417383c0d 100 */
Christopher Haster 89:b1d417383c0d 101 virtual void socket_destroy(void *handle) = 0;
Christopher Haster 89:b1d417383c0d 102
Christopher Haster 89:b1d417383c0d 103 /** Set socket options
Christopher Haster 89:b1d417383c0d 104 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 105 * @param optname Option ID
Christopher Haster 89:b1d417383c0d 106 * @param optval Option value
Christopher Haster 89:b1d417383c0d 107 * @param optlen Length of the option value
Christopher Haster 89:b1d417383c0d 108 * @return 0 on success, negative on failure
Christopher Haster 89:b1d417383c0d 109 */
Christopher Haster 89:b1d417383c0d 110 virtual int socket_set_option(void *handle, int optname, const void *optval, unsigned int optlen) = 0;
Christopher Haster 89:b1d417383c0d 111
Christopher Haster 89:b1d417383c0d 112 /** Get socket options
Christopher Haster 89:b1d417383c0d 113 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 114 * @param optname Option ID
Christopher Haster 89:b1d417383c0d 115 * @param optval Buffer pointer where to write the option value
Christopher Haster 89:b1d417383c0d 116 * @param optlen Length of the option value
Christopher Haster 89:b1d417383c0d 117 * @return 0 on success, negative on failure
Christopher Haster 89:b1d417383c0d 118 */
Christopher Haster 89:b1d417383c0d 119 virtual int socket_get_option(void *handle, int optname, void *optval, unsigned int *optlen) = 0;
Christopher Haster 89:b1d417383c0d 120
Christopher Haster 89:b1d417383c0d 121 /** Bind a server socket to a specific port
Christopher Haster 89:b1d417383c0d 122 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 123 * @param port The port to listen for incoming connections on
Christopher Haster 89:b1d417383c0d 124 * @return 0 on success, negative on failure.
Christopher Haster 89:b1d417383c0d 125 */
Christopher Haster 89:b1d417383c0d 126 virtual int socket_bind(void *handle, int port) = 0;
Christopher Haster 89:b1d417383c0d 127
Christopher Haster 89:b1d417383c0d 128 /** Start listening for incoming connections
Christopher Haster 89:b1d417383c0d 129 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 130 * @param backlog Number of pending connections that can be queued up at any
Christopher Haster 89:b1d417383c0d 131 * one time [Default: 1]
Christopher Haster 89:b1d417383c0d 132 * @return 0 on success, negative on failure
Christopher Haster 89:b1d417383c0d 133 */
Christopher Haster 89:b1d417383c0d 134 virtual int socket_listen(void *handle, int backlog) = 0;
Christopher Haster 89:b1d417383c0d 135
Christopher Haster 89:b1d417383c0d 136 /** Connects this TCP socket to the server
Christopher Haster 89:b1d417383c0d 137 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 138 * @param address SocketAddress to connect to
Christopher Haster 89:b1d417383c0d 139 * @return 0 on success, negative on failure
Christopher Haster 89:b1d417383c0d 140 */
Christopher Haster 89:b1d417383c0d 141 virtual int socket_connect(void *handle, const SocketAddress &address) = 0;
Christopher Haster 89:b1d417383c0d 142
Christopher Haster 89:b1d417383c0d 143 /** Check if the socket is connected
Christopher Haster 89:b1d417383c0d 144 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 145 * @return true if connected, false otherwise
Christopher Haster 89:b1d417383c0d 146 */
Christopher Haster 89:b1d417383c0d 147 virtual bool socket_is_connected(void *handle) = 0;
Christopher Haster 89:b1d417383c0d 148
Christopher Haster 89:b1d417383c0d 149 /** Accept a new connection.
Christopher Haster 89:b1d417383c0d 150 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 151 * @param socket A TCPSocket instance that will handle the incoming connection.
Christopher Haster 89:b1d417383c0d 152 * @return 0 on success, negative on failure.
Christopher Haster 89:b1d417383c0d 153 * @note This call is not-blocking, if this call would block, must
Christopher Haster 89:b1d417383c0d 154 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 89:b1d417383c0d 155 */
Christopher Haster 89:b1d417383c0d 156 virtual int socket_accept(void *handle, void **connection) = 0;
Christopher Haster 89:b1d417383c0d 157
Christopher Haster 89:b1d417383c0d 158 /** Send data to the remote host
Christopher Haster 89:b1d417383c0d 159 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 160 * @param data The buffer to send to the host
Christopher Haster 89:b1d417383c0d 161 * @param size The length of the buffer to send
Christopher Haster 89:b1d417383c0d 162 * @return Number of written bytes on success, negative on failure
Christopher Haster 89:b1d417383c0d 163 * @note This call is not-blocking, if this call would block, must
Christopher Haster 89:b1d417383c0d 164 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 89:b1d417383c0d 165 */
Christopher Haster 89:b1d417383c0d 166 virtual int socket_send(void *handle, const void *data, unsigned size) = 0;
Christopher Haster 89:b1d417383c0d 167
Christopher Haster 89:b1d417383c0d 168 /** Receive data from the remote host
Christopher Haster 89:b1d417383c0d 169 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 170 * @param data The buffer in which to store the data received from the host
Christopher Haster 89:b1d417383c0d 171 * @param size The maximum length of the buffer
Christopher Haster 89:b1d417383c0d 172 * @return Number of received bytes on success, negative on failure
Christopher Haster 89:b1d417383c0d 173 * @note This call is not-blocking, if this call would block, must
Christopher Haster 89:b1d417383c0d 174 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 89:b1d417383c0d 175 */
Christopher Haster 89:b1d417383c0d 176 virtual int socket_recv(void *handle, void *data, unsigned size) = 0;
Christopher Haster 89:b1d417383c0d 177
Christopher Haster 89:b1d417383c0d 178 /** Send a packet to a remote endpoint
Christopher Haster 89:b1d417383c0d 179 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 180 * @param address The remote SocketAddress
Christopher Haster 89:b1d417383c0d 181 * @param data The packet to be sent
Christopher Haster 89:b1d417383c0d 182 * @param size The length of the packet to be sent
Christopher Haster 89:b1d417383c0d 183 * @return the number of written bytes on success, negative on failure
Christopher Haster 89:b1d417383c0d 184 * @note This call is not-blocking, if this call would block, must
Christopher Haster 89:b1d417383c0d 185 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 89:b1d417383c0d 186 */
Christopher Haster 89:b1d417383c0d 187 virtual int socket_sendto(void *handle, const SocketAddress &address, const void *data, unsigned size) = 0;
Christopher Haster 89:b1d417383c0d 188
Christopher Haster 89:b1d417383c0d 189 /** Receive a packet from a remote endpoint
Christopher Haster 89:b1d417383c0d 190 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 191 * @param address Destination for the remote SocketAddress or null
Christopher Haster 89:b1d417383c0d 192 * @param buffer The buffer for storing the incoming packet data
Christopher Haster 89:b1d417383c0d 193 * If a packet is too long to fit in the supplied buffer,
Christopher Haster 89:b1d417383c0d 194 * excess bytes are discarded
Christopher Haster 89:b1d417383c0d 195 * @param size The length of the buffer
Christopher Haster 89:b1d417383c0d 196 * @return the number of received bytes on success, negative on failure
Christopher Haster 89:b1d417383c0d 197 * @note This call is not-blocking, if this call would block, must
Christopher Haster 89:b1d417383c0d 198 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 89:b1d417383c0d 199 */
Christopher Haster 89:b1d417383c0d 200 virtual int socket_recvfrom(void *handle, SocketAddress *address, void *buffer, unsigned size) = 0;
Christopher Haster 89:b1d417383c0d 201
Christopher Haster 89:b1d417383c0d 202 /** Close the socket
Christopher Haster 89:b1d417383c0d 203 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 204 */
Christopher Haster 91:cad29ce6a01c 205 virtual int socket_close(void *handle) = 0;
Christopher Haster 89:b1d417383c0d 206
Christopher Haster 89:b1d417383c0d 207 /** Register a callback on when a new connection is ready
Christopher Haster 89:b1d417383c0d 208 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 209 * @param callback Function to call when accept will succeed, may be called in
Christopher Haster 89:b1d417383c0d 210 * interrupt context.
Christopher Haster 89:b1d417383c0d 211 * @param id Argument to pass to callback
Christopher Haster 89:b1d417383c0d 212 */
Christopher Haster 89:b1d417383c0d 213 virtual void socket_attach_accept(void *handle, void (*callback)(void *), void *id) = 0;
Christopher Haster 89:b1d417383c0d 214
Christopher Haster 89:b1d417383c0d 215 /** Register a callback on when send is ready
Christopher Haster 89:b1d417383c0d 216 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 217 * @param callback Function to call when accept will succeed, may be called in
Christopher Haster 89:b1d417383c0d 218 * interrupt context.
Christopher Haster 89:b1d417383c0d 219 * @param id Argument to pass to callback
Christopher Haster 89:b1d417383c0d 220 */
Christopher Haster 89:b1d417383c0d 221 virtual void socket_attach_send(void *handle, void (*callback)(void *), void *id) = 0;
Christopher Haster 89:b1d417383c0d 222
Christopher Haster 89:b1d417383c0d 223 /** Register a callback on when recv is ready
Christopher Haster 89:b1d417383c0d 224 * @param handle Socket handle
Christopher Haster 89:b1d417383c0d 225 * @param callback Function to call when accept will succeed, may be called in
Christopher Haster 89:b1d417383c0d 226 * interrupt context.
Christopher Haster 89:b1d417383c0d 227 * @param id Argument to pass to callback
Christopher Haster 89:b1d417383c0d 228 */
Christopher Haster 89:b1d417383c0d 229 virtual void socket_attach_recv(void *handle, void (*callback)(void *), void *id) = 0;
Christopher Haster 89:b1d417383c0d 230 };
Christopher Haster 89:b1d417383c0d 231
Christopher Haster 89:b1d417383c0d 232 #endif