| 1 | //***************************************************************************** |
|---|
| 2 | // |
|---|
| 3 | //! \file socket.h |
|---|
| 4 | //! \brief SOCKET APIs Header file. |
|---|
| 5 | //! \details SOCKET APIs like as berkeley socket api. |
|---|
| 6 | //! \version 1.0.2 |
|---|
| 7 | //! \date 2013/10/21 |
|---|
| 8 | //! \par Revision history |
|---|
| 9 | //! <2015/02/05> Notice |
|---|
| 10 | //! The version history is not updated after this point. |
|---|
| 11 | //! Download the latest version directly from GitHub. Please visit the our GitHub repository for ioLibrary. |
|---|
| 12 | //! >> https://github.com/Wiznet/ioLibrary_Driver |
|---|
| 13 | //! <2014/05/01> V1.0.2. Refer to M20140501 |
|---|
| 14 | //! 1. Modify the comment : SO_REMAINED -> PACK_REMAINED |
|---|
| 15 | //! 2. Add the comment as zero byte udp data reception in getsockopt(). |
|---|
| 16 | //! <2013/10/21> 1st Release |
|---|
| 17 | //! \author MidnightCow |
|---|
| 18 | //! \copyright |
|---|
| 19 | //! |
|---|
| 20 | //! Copyright (c) 2013, WIZnet Co., LTD. |
|---|
| 21 | //! All rights reserved. |
|---|
| 22 | //! |
|---|
| 23 | //! Redistribution and use in source and binary forms, with or without |
|---|
| 24 | //! modification, are permitted provided that the following conditions |
|---|
| 25 | //! are met: |
|---|
| 26 | //! |
|---|
| 27 | //! * Redistributions of source code must retain the above copyright |
|---|
| 28 | //! notice, this list of conditions and the following disclaimer. |
|---|
| 29 | //! * Redistributions in binary form must reproduce the above copyright |
|---|
| 30 | //! notice, this list of conditions and the following disclaimer in the |
|---|
| 31 | //! documentation and/or other materials provided with the distribution. |
|---|
| 32 | //! * Neither the name of the <ORGANIZATION> nor the names of its |
|---|
| 33 | //! contributors may be used to endorse or promote products derived |
|---|
| 34 | //! from this software without specific prior written permission. |
|---|
| 35 | //! |
|---|
| 36 | //! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
|---|
| 37 | //! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
|---|
| 38 | //! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
|---|
| 39 | //! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE |
|---|
| 40 | //! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
|---|
| 41 | //! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
|---|
| 42 | //! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
|---|
| 43 | //! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
|---|
| 44 | //! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
|---|
| 45 | //! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF |
|---|
| 46 | //! THE POSSIBILITY OF SUCH DAMAGE. |
|---|
| 47 | // |
|---|
| 48 | //***************************************************************************** |
|---|
| 49 | /** |
|---|
| 50 | * @defgroup WIZnet_socket_APIs 1. WIZnet socket APIs |
|---|
| 51 | * @brief WIZnet socket APIs are based on Berkeley socket APIs, thus it has much similar name and interface. |
|---|
| 52 | * But there is a little bit of difference. |
|---|
| 53 | * @details |
|---|
| 54 | * <b> Comparison between WIZnet and Berkeley SOCKET APIs </b> |
|---|
| 55 | * <table> |
|---|
| 56 | * <tr> <td><b>API</b></td> <td><b>WIZnet</b></td> <td><b>Berkeley</b></td> </tr> |
|---|
| 57 | * <tr> <td>socket()</td> <td>O</td> <td>O</td> </tr> |
|---|
| 58 | * <tr> <td><b>bind()</b></td> <td>X</td> <td>O</td> </tr> |
|---|
| 59 | * <tr> <td><b>listen()</b></td> <td>O</td> <td>O</td> </tr> |
|---|
| 60 | * <tr> <td><b>connect()</b></td> <td>O</td> <td>O</td> </tr> |
|---|
| 61 | * <tr> <td><b>accept()</b></td> <td>X</td> <td>O</td> </tr> |
|---|
| 62 | * <tr> <td><b>recv()</b></td> <td>O</td> <td>O</td> </tr> |
|---|
| 63 | * <tr> <td><b>send()</b></td> <td>O</td> <td>O</td> </tr> |
|---|
| 64 | * <tr> <td><b>recvfrom()</b></td> <td>O</td> <td>O</td> </tr> |
|---|
| 65 | * <tr> <td><b>sendto()</b></td> <td>O</td> <td>O</td> </tr> |
|---|
| 66 | * <tr> <td><b>closesocket()</b></td> <td>O<br>close() & disconnect()</td> <td>O</td> </tr> |
|---|
| 67 | * </table> |
|---|
| 68 | * There are @b bind() and @b accept() functions in @b Berkeley SOCKET API but, |
|---|
| 69 | * not in @b WIZnet SOCKET API. Because socket() of WIZnet is not only creating a SOCKET but also binding a local port number, |
|---|
| 70 | * and listen() of WIZnet is not only listening to connection request from client but also accepting the connection request. \n |
|---|
| 71 | * When you program "TCP SERVER" with Berkeley SOCKET API, you can use only one listen port. |
|---|
| 72 | * When the listen SOCKET accepts a connection request from a client, it keeps listening. |
|---|
| 73 | * After accepting the connection request, a new SOCKET is created and the new SOCKET is used in communication with the client. \n |
|---|
| 74 | * Following figure shows network flow diagram by Berkeley SOCKET API. |
|---|
| 75 | * @image html Berkeley_SOCKET.jpg "<Berkeley SOCKET API>" |
|---|
| 76 | * But, When you program "TCP SERVER" with WIZnet SOCKET API, you can use as many as 8 listen SOCKET with same port number. \n |
|---|
| 77 | * Because there's no accept() in WIZnet SOCKET APIs, when the listen SOCKET accepts a connection request from a client, |
|---|
| 78 | * it is changed in order to communicate with the client. |
|---|
| 79 | * And the changed SOCKET is not listening any more and is dedicated for communicating with the client. \n |
|---|
| 80 | * If there're many listen SOCKET with same listen port number and a client requests a connection, |
|---|
| 81 | * the SOCKET which has the smallest SOCKET number accepts the request and is changed as communication SOCKET. \n |
|---|
| 82 | * Following figure shows network flow diagram by WIZnet SOCKET API. |
|---|
| 83 | * @image html WIZnet_SOCKET.jpg "<WIZnet SOCKET API>" |
|---|
| 84 | */ |
|---|
| 85 | #ifndef _SOCKET_H_ |
|---|
| 86 | #define _SOCKET_H_ |
|---|
| 87 | #ifdef __cplusplus |
|---|
| 88 | extern "C" { |
|---|
| 89 | #endif |
|---|
| 90 | |
|---|
| 91 | #include "wizchip_conf.h" |
|---|
| 92 | |
|---|
| 93 | #define SOCKET uint8_t ///< SOCKET type define for legacy driver |
|---|
| 94 | |
|---|
| 95 | #define SOCK_OK 1 ///< Result is OK about socket process. |
|---|
| 96 | #define SOCK_BUSY 0 ///< Socket is busy on processing the operation. Valid only Non-block IO Mode. |
|---|
| 97 | #define SOCK_FATAL -1000 ///< Result is fatal error about socket process. |
|---|
| 98 | |
|---|
| 99 | #define SOCK_ERROR 0 |
|---|
| 100 | #define SOCKERR_SOCKNUM (SOCK_ERROR - 1) ///< Invalid socket number |
|---|
| 101 | #define SOCKERR_SOCKOPT (SOCK_ERROR - 2) ///< Invalid socket option |
|---|
| 102 | #define SOCKERR_SOCKINIT (SOCK_ERROR - 3) ///< Socket is not initialized or SIPR is Zero IP address when Sn_MR_TCP |
|---|
| 103 | #define SOCKERR_SOCKCLOSED (SOCK_ERROR - 4) ///< Socket unexpectedly closed. |
|---|
| 104 | #define SOCKERR_SOCKMODE (SOCK_ERROR - 5) ///< Invalid socket mode for socket operation. |
|---|
| 105 | #define SOCKERR_SOCKFLAG (SOCK_ERROR - 6) ///< Invalid socket flag |
|---|
| 106 | #define SOCKERR_SOCKSTATUS (SOCK_ERROR - 7) ///< Invalid socket status for socket operation. |
|---|
| 107 | #define SOCKERR_ARG (SOCK_ERROR - 10) ///< Invalid argument. |
|---|
| 108 | #define SOCKERR_PORTZERO (SOCK_ERROR - 11) ///< Port number is zero |
|---|
| 109 | #define SOCKERR_IPINVALID (SOCK_ERROR - 12) ///< Invalid IP address |
|---|
| 110 | #define SOCKERR_TIMEOUT (SOCK_ERROR - 13) ///< Timeout occurred |
|---|
| 111 | #define SOCKERR_DATALEN (SOCK_ERROR - 14) ///< Data length is zero or greater than buffer max size. |
|---|
| 112 | #define SOCKERR_BUFFER (SOCK_ERROR - 15) ///< Socket buffer is not enough for data communication. |
|---|
| 113 | |
|---|
| 114 | #define SOCKFATAL_PACKLEN (SOCK_FATAL - 1) ///< Invalid packet length. Fatal Error. |
|---|
| 115 | |
|---|
| 116 | /* |
|---|
| 117 | * SOCKET FLAG |
|---|
| 118 | */ |
|---|
| 119 | #define SF_ETHER_OWN (Sn_MR_MFEN) ///< In @ref Sn_MR_MACRAW, Receive only the packet as broadcast, multicast and own packet |
|---|
| 120 | #define SF_IGMP_VER2 (Sn_MR_MC) ///< In @ref Sn_MR_UDP with \ref SF_MULTI_ENABLE, Select IGMP version 2. |
|---|
| 121 | #define SF_TCP_NODELAY (Sn_MR_ND) ///< In @ref Sn_MR_TCP, Use to nodelayed ack. |
|---|
| 122 | #define SF_MULTI_ENABLE (Sn_MR_MULTI) ///< In @ref Sn_MR_UDP, Enable multicast mode. |
|---|
| 123 | |
|---|
| 124 | #if _WIZCHIP_ == 5500 |
|---|
| 125 | #define SF_BROAD_BLOCK (Sn_MR_BCASTB) ///< In @ref Sn_MR_UDP or @ref Sn_MR_MACRAW, Block broadcast packet. Valid only in W5500 |
|---|
| 126 | #define SF_MULTI_BLOCK (Sn_MR_MMB) ///< In @ref Sn_MR_MACRAW, Block multicast packet. Valid only in W5500 |
|---|
| 127 | #define SF_IPv6_BLOCK (Sn_MR_MIP6B) ///< In @ref Sn_MR_MACRAW, Block IPv6 packet. Valid only in W5500 |
|---|
| 128 | #define SF_UNI_BLOCK (Sn_MR_UCASTB) ///< In @ref Sn_MR_UDP with \ref SF_MULTI_ENABLE. Valid only in W5500 |
|---|
| 129 | #endif |
|---|
| 130 | |
|---|
| 131 | //A201505 : For W5300 |
|---|
| 132 | #if _WIZCHIP_ == 5300 |
|---|
| 133 | #define SF_TCP_ALIGN 0x02 ///< Valid only \ref Sn_MR_TCP and W5300, refer to \ref Sn_MR_ALIGN |
|---|
| 134 | #endif |
|---|
| 135 | |
|---|
| 136 | #define SF_IO_NONBLOCK 0x01 ///< Socket nonblock io mode. It used parameter in \ref socket(). |
|---|
| 137 | |
|---|
| 138 | /* |
|---|
| 139 | * UDP & MACRAW Packet Infomation |
|---|
| 140 | */ |
|---|
| 141 | #define PACK_FIRST 0x80 ///< In Non-TCP packet, It indicates to start receiving a packet. (When W5300, This flag can be applied) |
|---|
| 142 | #define PACK_REMAINED 0x01 ///< In Non-TCP packet, It indicates to remain a packet to be received. (When W5300, This flag can be applied) |
|---|
| 143 | #define PACK_COMPLETED 0x00 ///< In Non-TCP packet, It indicates to complete to receive a packet. (When W5300, This flag can be applied) |
|---|
| 144 | //A20150601 : For Integrating with W5300 |
|---|
| 145 | #define PACK_FIFOBYTE 0x02 ///< Valid only W5300, It indicate to have read already the Sn_RX_FIFOR. |
|---|
| 146 | // |
|---|
| 147 | |
|---|
| 148 | /** |
|---|
| 149 | * @ingroup WIZnet_socket_APIs |
|---|
| 150 | * @brief Open a socket. |
|---|
| 151 | * @details Initializes the socket with 'sn' passed as parameter and open. |
|---|
| 152 | * |
|---|
| 153 | * @param sn Socket number. It should be <b>0 ~ @ref \_WIZCHIP_SOCK_NUM_</b>. |
|---|
| 154 | * @param protocol Protocol type to operate such as TCP, UDP and MACRAW. |
|---|
| 155 | * @param port Port number to be bined. |
|---|
| 156 | * @param flag Socket flags as \ref SF_ETHER_OWN, \ref SF_IGMP_VER2, \ref SF_TCP_NODELAY, \ref SF_MULTI_ENABLE, \ref SF_IO_NONBLOCK and so on.\n |
|---|
| 157 | * Valid flags only in W5500 : @ref SF_BROAD_BLOCK, @ref SF_MULTI_BLOCK, @ref SF_IPv6_BLOCK, and @ref SF_UNI_BLOCK. |
|---|
| 158 | * @sa Sn_MR |
|---|
| 159 | * |
|---|
| 160 | * @return @b Success : The socket number @b 'sn' passed as parameter\n |
|---|
| 161 | * @b Fail :\n @ref SOCKERR_SOCKNUM - Invalid socket number\n |
|---|
| 162 | * @ref SOCKERR_SOCKMODE - Not support socket mode as TCP, UDP, and so on. \n |
|---|
| 163 | * @ref SOCKERR_SOCKFLAG - Invaild socket flag. |
|---|
| 164 | */ |
|---|
| 165 | int8_t socket(uint8_t sn, uint8_t protocol, uint16_t port, uint8_t flag); |
|---|
| 166 | |
|---|
| 167 | /** |
|---|
| 168 | * @ingroup WIZnet_socket_APIs |
|---|
| 169 | * @brief Close a socket. |
|---|
| 170 | * @details It closes the socket with @b'sn' passed as parameter. |
|---|
| 171 | * |
|---|
| 172 | * @param sn Socket number. It should be <b>0 ~ @ref \_WIZCHIP_SOCK_NUM_</b>. |
|---|
| 173 | * |
|---|
| 174 | * @return @b Success : @ref SOCK_OK \n |
|---|
| 175 | * @b Fail : @ref SOCKERR_SOCKNUM - Invalid socket number |
|---|
| 176 | */ |
|---|
| 177 | int8_t close(uint8_t sn); |
|---|
| 178 | |
|---|
| 179 | /** |
|---|
| 180 | * @ingroup WIZnet_socket_APIs |
|---|
| 181 | * @brief Listen to a connection request from a client. |
|---|
| 182 | * @details It is listening to a connection request from a client. |
|---|
| 183 | * If connection request is accepted successfully, the connection is established. Socket sn is used in passive(server) mode. |
|---|
| 184 | * |
|---|
| 185 | * @param sn Socket number. It should be <b>0 ~ @ref \_WIZCHIP_SOCK_NUM_</b>. |
|---|
| 186 | * @return @b Success : @ref SOCK_OK \n |
|---|
| 187 | * @b Fail :\n @ref SOCKERR_SOCKINIT - Socket is not initialized \n |
|---|
| 188 | * @ref SOCKERR_SOCKCLOSED - Socket closed unexpectedly. |
|---|
| 189 | */ |
|---|
| 190 | int8_t listen(uint8_t sn); |
|---|
| 191 | |
|---|
| 192 | /** |
|---|
| 193 | * @ingroup WIZnet_socket_APIs |
|---|
| 194 | * @brief Try to connect a server. |
|---|
| 195 | * @details It requests connection to the server with destination IP address and port number passed as parameter.\n |
|---|
| 196 | * @note It is valid only in TCP client mode. |
|---|
| 197 | * In block io mode, it does not return until connection is completed. |
|---|
| 198 | * In Non-block io mode, it return @ref SOCK_BUSY immediately. |
|---|
| 199 | * |
|---|
| 200 | * @param sn Socket number. It should be <b>0 ~ @ref \_WIZCHIP_SOCK_NUM_</b>. |
|---|
| 201 | * @param addr Pointer variable of destination IP address. It should be allocated 4 bytes. |
|---|
| 202 | * @param port Destination port number. |
|---|
| 203 | * |
|---|
| 204 | * @return @b Success : @ref SOCK_OK \n |
|---|
| 205 | * @b Fail :\n @ref SOCKERR_SOCKNUM - Invalid socket number\n |
|---|
| 206 | * @ref SOCKERR_SOCKMODE - Invalid socket mode\n |
|---|
| 207 | * @ref SOCKERR_SOCKINIT - Socket is not initialized\n |
|---|
| 208 | * @ref SOCKERR_IPINVALID - Wrong server IP address\n |
|---|
| 209 | * @ref SOCKERR_PORTZERO - Server port zero\n |
|---|
| 210 | * @ref SOCKERR_TIMEOUT - Timeout occurred during request connection\n |
|---|
| 211 | * @ref SOCK_BUSY - In non-block io mode, it returned immediately\n |
|---|
| 212 | */ |
|---|
| 213 | int8_t connect(uint8_t sn, uint8_t * addr, uint16_t port); |
|---|
| 214 | |
|---|
| 215 | /** |
|---|
| 216 | * @ingroup WIZnet_socket_APIs |
|---|
| 217 | * @brief Try to disconnect a connection socket. |
|---|
| 218 | * @details It sends request message to disconnect the TCP socket 'sn' passed as parameter to the server or client. |
|---|
| 219 | * @note It is valid only in TCP server or client mode. \n |
|---|
| 220 | * In block io mode, it does not return until disconnection is completed. \n |
|---|
| 221 | * In Non-block io mode, it return @ref SOCK_BUSY immediately. \n |
|---|
| 222 | |
|---|
| 223 | * @param sn Socket number. It should be <b>0 ~ @ref \_WIZCHIP_SOCK_NUM_</b>. |
|---|
| 224 | * @return @b Success : @ref SOCK_OK \n |
|---|
| 225 | * @b Fail :\n @ref SOCKERR_SOCKNUM - Invalid socket number \n |
|---|
| 226 | * @ref SOCKERR_SOCKMODE - Invalid operation in the socket \n |
|---|
| 227 | * @ref SOCKERR_TIMEOUT - Timeout occurred \n |
|---|
| 228 | * @ref SOCK_BUSY - Socket is busy. |
|---|
| 229 | */ |
|---|
| 230 | int8_t disconnect(uint8_t sn); |
|---|
| 231 | |
|---|
| 232 | /** |
|---|
| 233 | * @ingroup WIZnet_socket_APIs |
|---|
| 234 | * @brief Send data to the connected peer in TCP socket. |
|---|
| 235 | * @details It is used to send outgoing data to the connected socket. |
|---|
| 236 | * @note It is valid only in TCP server or client mode. It can't send data greater than socket buffer size. \n |
|---|
| 237 | * In block io mode, It doesn't return until data send is completed - socket buffer size is greater than data. \n |
|---|
| 238 | * In non-block io mode, It return @ref SOCK_BUSY immediately when socket buffer is not enough. \n |
|---|
| 239 | * @param sn Socket number. It should be <b>0 ~ @ref \_WIZCHIP_SOCK_NUM_</b>. |
|---|
| 240 | * @param buf Pointer buffer containing data to be sent. |
|---|
| 241 | * @param len The byte length of data in buf. |
|---|
| 242 | * @return @b Success : The sent data size \n |
|---|
| 243 | * @b Fail : \n @ref SOCKERR_SOCKSTATUS - Invalid socket status for socket operation \n |
|---|
| 244 | * @ref SOCKERR_TIMEOUT - Timeout occurred \n |
|---|
| 245 | * @ref SOCKERR_SOCKMODE - Invalid operation in the socket \n |
|---|
| 246 | * @ref SOCKERR_SOCKNUM - Invalid socket number \n |
|---|
| 247 | * @ref SOCKERR_DATALEN - zero data length \n |
|---|
| 248 | * @ref SOCK_BUSY - Socket is busy. |
|---|
| 249 | */ |
|---|
| 250 | int32_t send(uint8_t sn, uint8_t * buf, uint16_t len); |
|---|
| 251 | |
|---|
| 252 | /** |
|---|
| 253 | * @ingroup WIZnet_socket_APIs |
|---|
| 254 | * @brief Receive data from the connected peer. |
|---|
| 255 | * @details It is used to read incoming data from the connected socket.\n |
|---|
| 256 | * It waits for data as much as the application wants to receive. |
|---|
| 257 | * @note It is valid only in TCP server or client mode. It can't receive data greater than socket buffer size. \n |
|---|
| 258 | * In block io mode, it doesn't return until data reception is completed - data is filled as <I>len</I> in socket buffer. \n |
|---|
| 259 | * In non-block io mode, it return @ref SOCK_BUSY immediately when <I>len</I> is greater than data size in socket buffer. \n |
|---|
| 260 | * |
|---|
| 261 | * @param sn Socket number. It should be <b>0 ~ @ref \_WIZCHIP_SOCK_NUM_</b>. |
|---|
| 262 | * @param buf Pointer buffer to read incoming data. |
|---|
| 263 | * @param len The max data length of data in buf. |
|---|
| 264 | * @return @b Success : The real received data size \n |
|---|
| 265 | * @b Fail :\n |
|---|
| 266 | * @ref SOCKERR_SOCKSTATUS - Invalid socket status for socket operation \n |
|---|
| 267 | * @ref SOCKERR_SOCKMODE - Invalid operation in the socket \n |
|---|
| 268 | * @ref SOCKERR_SOCKNUM - Invalid socket number \n |
|---|
| 269 | * @ref SOCKERR_DATALEN - zero data length \n |
|---|
| 270 | * @ref SOCK_BUSY - Socket is busy. |
|---|
| 271 | */ |
|---|
| 272 | int32_t recv(uint8_t sn, uint8_t * buf, uint16_t len); |
|---|
| 273 | |
|---|
| 274 | /** |
|---|
| 275 | * @ingroup WIZnet_socket_APIs |
|---|
| 276 | * @brief Sends datagram to the peer with destination IP address and port number passed as parameter. |
|---|
| 277 | * @details It sends datagram of UDP or MACRAW to the peer with destination IP address and port number passed as parameter.\n |
|---|
| 278 | * Even if the connectionless socket has been previously connected to a specific address, |
|---|
| 279 | * the address and port number parameters override the destination address for that particular datagram only. |
|---|
| 280 | * @note In block io mode, It doesn't return until data send is completed - socket buffer size is greater than <I>len</I>. |
|---|
| 281 | * In non-block io mode, It return @ref SOCK_BUSY immediately when socket buffer is not enough. |
|---|
| 282 | * |
|---|
| 283 | * @param sn Socket number. It should be <b>0 ~ @ref \_WIZCHIP_SOCK_NUM_</b>. |
|---|
| 284 | * @param buf Pointer buffer to send outgoing data. |
|---|
| 285 | * @param len The byte length of data in buf. |
|---|
| 286 | * @param addr Pointer variable of destination IP address. It should be allocated 4 bytes. |
|---|
| 287 | * @param port Destination port number. |
|---|
| 288 | * |
|---|
| 289 | * @return @b Success : The sent data size \n |
|---|
| 290 | * @b Fail :\n @ref SOCKERR_SOCKNUM - Invalid socket number \n |
|---|
| 291 | * @ref SOCKERR_SOCKMODE - Invalid operation in the socket \n |
|---|
| 292 | * @ref SOCKERR_SOCKSTATUS - Invalid socket status for socket operation \n |
|---|
| 293 | * @ref SOCKERR_DATALEN - zero data length \n |
|---|
| 294 | * @ref SOCKERR_IPINVALID - Wrong server IP address\n |
|---|
| 295 | * @ref SOCKERR_PORTZERO - Server port zero\n |
|---|
| 296 | * @ref SOCKERR_SOCKCLOSED - Socket unexpectedly closed \n |
|---|
| 297 | * @ref SOCKERR_TIMEOUT - Timeout occurred \n |
|---|
| 298 | * @ref SOCK_BUSY - Socket is busy. |
|---|
| 299 | */ |
|---|
| 300 | int32_t sendto(uint8_t sn, uint8_t * buf, uint16_t len, uint8_t * addr, uint16_t port); |
|---|
| 301 | |
|---|
| 302 | /** |
|---|
| 303 | * @ingroup WIZnet_socket_APIs |
|---|
| 304 | * @brief Receive datagram of UDP or MACRAW |
|---|
| 305 | * @details This function is an application I/F function which is used to receive the data in other then TCP mode. \n |
|---|
| 306 | * This function is used to receive UDP and MAC_RAW mode, and handle the header as well. |
|---|
| 307 | * This function can divide to received the packet data. |
|---|
| 308 | * On the MACRAW SOCKET, the addr and port parameters are ignored. |
|---|
| 309 | * @note In block io mode, it doesn't return until data reception is completed - data is filled as <I>len</I> in socket buffer |
|---|
| 310 | * In non-block io mode, it return @ref SOCK_BUSY immediately when <I>len</I> is greater than data size in socket buffer. |
|---|
| 311 | * |
|---|
| 312 | * @param sn Socket number. It should be <b>0 ~ @ref \_WIZCHIP_SOCK_NUM_</b>. |
|---|
| 313 | * @param buf Pointer buffer to read incoming data. |
|---|
| 314 | * @param len The max data length of data in buf. |
|---|
| 315 | * When the received packet size <= len, receives data as packet sized. |
|---|
| 316 | * When others, receives data as len. |
|---|
| 317 | * @param addr Pointer variable of destination IP address. It should be allocated 4 bytes. |
|---|
| 318 | * It is valid only when the first call recvfrom for receiving the packet. |
|---|
| 319 | * When it is valid, @ref packinfo[7] should be set as '1' after call @ref getsockopt(sn, SO_PACKINFO, &packinfo). |
|---|
| 320 | * @param port Pointer variable of destination port number. |
|---|
| 321 | * It is valid only when the first call recvform for receiving the packet. |
|---|
| 322 | * When it is valid, @ref packinfo[7] should be set as '1' after call @ref getsockopt(sn, SO_PACKINFO, &packinfo). |
|---|
| 323 | * |
|---|
| 324 | * @return @b Success : This function return real received data size for success.\n |
|---|
| 325 | * @b Fail : @ref SOCKERR_DATALEN - zero data length \n |
|---|
| 326 | * @ref SOCKERR_SOCKMODE - Invalid operation in the socket \n |
|---|
| 327 | * @ref SOCKERR_SOCKNUM - Invalid socket number \n |
|---|
| 328 | * @ref SOCKBUSY - Socket is busy. |
|---|
| 329 | */ |
|---|
| 330 | int32_t recvfrom(uint8_t sn, uint8_t * buf, uint16_t len, uint8_t * addr, uint16_t *port); |
|---|
| 331 | |
|---|
| 332 | |
|---|
| 333 | ///////////////////////////// |
|---|
| 334 | // SOCKET CONTROL & OPTION // |
|---|
| 335 | ///////////////////////////// |
|---|
| 336 | #define SOCK_IO_BLOCK 0 ///< Socket Block IO Mode in @ref setsockopt(). |
|---|
| 337 | #define SOCK_IO_NONBLOCK 1 ///< Socket Non-block IO Mode in @ref setsockopt(). |
|---|
| 338 | |
|---|
| 339 | /** |
|---|
| 340 | * @defgroup DATA_TYPE DATA TYPE |
|---|
| 341 | */ |
|---|
| 342 | |
|---|
| 343 | /** |
|---|
| 344 | * @ingroup DATA_TYPE |
|---|
| 345 | * @brief The kind of Socket Interrupt. |
|---|
| 346 | * @sa Sn_IR, Sn_IMR, setSn_IR(), getSn_IR(), setSn_IMR(), getSn_IMR() |
|---|
| 347 | */ |
|---|
| 348 | typedef enum |
|---|
| 349 | { |
|---|
| 350 | SIK_CONNECTED = (1 << 0), ///< connected |
|---|
| 351 | SIK_DISCONNECTED = (1 << 1), ///< disconnected |
|---|
| 352 | SIK_RECEIVED = (1 << 2), ///< data received |
|---|
| 353 | SIK_TIMEOUT = (1 << 3), ///< timeout occurred |
|---|
| 354 | SIK_SENT = (1 << 4), ///< send ok |
|---|
| 355 | //M20150410 : Remove the comma of last member |
|---|
| 356 | //SIK_ALL = 0x1F, ///< all interrupt |
|---|
| 357 | SIK_ALL = 0x1F ///< all interrupt |
|---|
| 358 | }sockint_kind; |
|---|
| 359 | |
|---|
| 360 | /** |
|---|
| 361 | * @ingroup DATA_TYPE |
|---|
| 362 | * @brief The type of @ref ctlsocket(). |
|---|
| 363 | */ |
|---|
| 364 | typedef enum |
|---|
| 365 | { |
|---|
| 366 | CS_SET_IOMODE, ///< set socket IO mode with @ref SOCK_IO_BLOCK or @ref SOCK_IO_NONBLOCK |
|---|
| 367 | CS_GET_IOMODE, ///< get socket IO mode |
|---|
| 368 | CS_GET_MAXTXBUF, ///< get the size of socket buffer allocated in TX memory |
|---|
| 369 | CS_GET_MAXRXBUF, ///< get the size of socket buffer allocated in RX memory |
|---|
| 370 | CS_CLR_INTERRUPT, ///< clear the interrupt of socket with @ref sockint_kind |
|---|
| 371 | CS_GET_INTERRUPT, ///< get the socket interrupt. refer to @ref sockint_kind |
|---|
| 372 | #if _WIZCHIP_ > 5100 |
|---|
| 373 | CS_SET_INTMASK, ///< set the interrupt mask of socket with @ref sockint_kind, Not supported in W5100 |
|---|
| 374 | CS_GET_INTMASK ///< get the masked interrupt of socket. refer to @ref sockint_kind, Not supported in W5100 |
|---|
| 375 | #endif |
|---|
| 376 | }ctlsock_type; |
|---|
| 377 | |
|---|
| 378 | |
|---|
| 379 | /** |
|---|
| 380 | * @ingroup DATA_TYPE |
|---|
| 381 | * @brief The type of socket option in @ref setsockopt() or @ref getsockopt() |
|---|
| 382 | */ |
|---|
| 383 | typedef enum |
|---|
| 384 | { |
|---|
| 385 | SO_FLAG, ///< Valid only in getsockopt(), For set flag of socket refer to <I>flag</I> in @ref socket(). |
|---|
| 386 | SO_TTL, ///< Set TTL. @ref Sn_TTL ( @ref setSn_TTL(), @ref getSn_TTL() ) |
|---|
| 387 | SO_TOS, ///< Set TOS. @ref Sn_TOS ( @ref setSn_TOS(), @ref getSn_TOS() ) |
|---|
| 388 | SO_MSS, ///< Set MSS. @ref Sn_MSSR ( @ref setSn_MSSR(), @ref getSn_MSSR() ) |
|---|
| 389 | SO_DESTIP, ///< Set the destination IP address. @ref Sn_DIPR ( @ref setSn_DIPR(), @ref getSn_DIPR() ) |
|---|
| 390 | SO_DESTPORT, ///< Set the destination Port number. @ref Sn_DPORT ( @ref setSn_DPORT(), @ref getSn_DPORT() ) |
|---|
| 391 | #if _WIZCHIP_ != 5100 |
|---|
| 392 | SO_KEEPALIVESEND, ///< Valid only in setsockopt. Manually send keep-alive packet in TCP mode, Not supported in W5100 |
|---|
| 393 | #if !( (_WIZCHIP_ == 5100) || (_WIZCHIP_ == 5200) ) |
|---|
| 394 | SO_KEEPALIVEAUTO, ///< Set/Get keep-alive auto transmission timer in TCP mode, Not supported in W5100, W5200 |
|---|
| 395 | #endif |
|---|
| 396 | #endif |
|---|
| 397 | SO_SENDBUF, ///< Valid only in getsockopt. Get the free data size of Socekt TX buffer. @ref Sn_TX_FSR, @ref getSn_TX_FSR() |
|---|
| 398 | SO_RECVBUF, ///< Valid only in getsockopt. Get the received data size in socket RX buffer. @ref Sn_RX_RSR, @ref getSn_RX_RSR() |
|---|
| 399 | SO_STATUS, ///< Valid only in getsockopt. Get the socket status. @ref Sn_SR, @ref getSn_SR() |
|---|
| 400 | SO_REMAINSIZE, ///< Valid only in getsockopt. Get the remained packet size in other then TCP mode. |
|---|
| 401 | SO_PACKINFO ///< Valid only in getsockopt. Get the packet information as @ref PACK_FIRST, @ref PACK_REMAINED, and @ref PACK_COMPLETED in other then TCP mode. |
|---|
| 402 | }sockopt_type; |
|---|
| 403 | |
|---|
| 404 | /** |
|---|
| 405 | * @ingroup WIZnet_socket_APIs |
|---|
| 406 | * @brief Control socket. |
|---|
| 407 | * @details Control IO mode, Interrupt & Mask of socket and get the socket buffer information. |
|---|
| 408 | * Refer to @ref ctlsock_type. |
|---|
| 409 | * @param sn socket number |
|---|
| 410 | * @param cstype type of control socket. refer to @ref ctlsock_type. |
|---|
| 411 | * @param arg Data type and value is determined according to @ref ctlsock_type. \n |
|---|
| 412 | * <table> |
|---|
| 413 | * <tr> <td> @b cstype </td> <td> @b data type</td><td>@b value</td></tr> |
|---|
| 414 | * <tr> <td> @ref CS_SET_IOMODE \n @ref CS_GET_IOMODE </td> <td> uint8_t </td><td>@ref SOCK_IO_BLOCK @ref SOCK_IO_NONBLOCK</td></tr> |
|---|
| 415 | * <tr> <td> @ref CS_GET_MAXTXBUF \n @ref CS_GET_MAXRXBUF </td> <td> uint16_t </td><td> 0 ~ 16K </td></tr> |
|---|
| 416 | * <tr> <td> @ref CS_CLR_INTERRUPT \n @ref CS_GET_INTERRUPT \n @ref CS_SET_INTMASK \n @ref CS_GET_INTMASK </td> <td> @ref sockint_kind </td><td> @ref SIK_CONNECTED, etc. </td></tr> |
|---|
| 417 | * </table> |
|---|
| 418 | * @return @b Success @ref SOCK_OK \n |
|---|
| 419 | * @b fail @ref SOCKERR_ARG - Invalid argument\n |
|---|
| 420 | */ |
|---|
| 421 | int8_t ctlsocket(uint8_t sn, ctlsock_type cstype, void* arg); |
|---|
| 422 | |
|---|
| 423 | /** |
|---|
| 424 | * @ingroup WIZnet_socket_APIs |
|---|
| 425 | * @brief set socket options |
|---|
| 426 | * @details Set socket option like as TTL, MSS, TOS, and so on. Refer to @ref sockopt_type. |
|---|
| 427 | * |
|---|
| 428 | * @param sn socket number |
|---|
| 429 | * @param sotype socket option type. refer to @ref sockopt_type |
|---|
| 430 | * @param arg Data type and value is determined according to <I>sotype</I>. \n |
|---|
| 431 | * <table> |
|---|
| 432 | * <tr> <td> @b sotype </td> <td> @b data type</td><td>@b value</td></tr> |
|---|
| 433 | * <tr> <td> @ref SO_TTL </td> <td> uint8_t </td><td> 0 ~ 255 </td> </tr> |
|---|
| 434 | * <tr> <td> @ref SO_TOS </td> <td> uint8_t </td><td> 0 ~ 255 </td> </tr> |
|---|
| 435 | * <tr> <td> @ref SO_MSS </td> <td> uint16_t </td><td> 0 ~ 65535 </td> </tr> |
|---|
| 436 | * <tr> <td> @ref SO_DESTIP </td> <td> uint8_t[4] </td><td> </td></tr> |
|---|
| 437 | * <tr> <td> @ref SO_DESTPORT </td> <td> uint16_t </td><td> 0 ~ 65535 </td></tr> |
|---|
| 438 | * <tr> <td> @ref SO_KEEPALIVESEND </td> <td> null </td><td> null </td></tr> |
|---|
| 439 | * <tr> <td> @ref SO_KEEPALIVEAUTO </td> <td> uint8_t </td><td> 0 ~ 255 </td></tr> |
|---|
| 440 | * </table> |
|---|
| 441 | * @return |
|---|
| 442 | * - @b Success : @ref SOCK_OK \n |
|---|
| 443 | * - @b Fail |
|---|
| 444 | * - @ref SOCKERR_SOCKNUM - Invalid Socket number \n |
|---|
| 445 | * - @ref SOCKERR_SOCKMODE - Invalid socket mode \n |
|---|
| 446 | * - @ref SOCKERR_SOCKOPT - Invalid socket option or its value \n |
|---|
| 447 | * - @ref SOCKERR_TIMEOUT - Timeout occurred when sending keep-alive packet \n |
|---|
| 448 | */ |
|---|
| 449 | int8_t setsockopt(uint8_t sn, sockopt_type sotype, void* arg); |
|---|
| 450 | |
|---|
| 451 | /** |
|---|
| 452 | * @ingroup WIZnet_socket_APIs |
|---|
| 453 | * @brief get socket options |
|---|
| 454 | * @details Get socket option like as FLAG, TTL, MSS, and so on. Refer to @ref sockopt_type |
|---|
| 455 | * @param sn socket number |
|---|
| 456 | * @param sotype socket option type. refer to @ref sockopt_type |
|---|
| 457 | * @param arg Data type and value is determined according to <I>sotype</I>. \n |
|---|
| 458 | * <table> |
|---|
| 459 | * <tr> <td> @b sotype </td> <td>@b data type</td><td>@b value</td></tr> |
|---|
| 460 | * <tr> <td> @ref SO_FLAG </td> <td> uint8_t </td><td> @ref SF_ETHER_OWN, etc... </td> </tr> |
|---|
| 461 | * <tr> <td> @ref SO_TOS </td> <td> uint8_t </td><td> 0 ~ 255 </td> </tr> |
|---|
| 462 | * <tr> <td> @ref SO_MSS </td> <td> uint16_t </td><td> 0 ~ 65535 </td> </tr> |
|---|
| 463 | * <tr> <td> @ref SO_DESTIP </td> <td> uint8_t[4] </td><td> </td></tr> |
|---|
| 464 | * <tr> <td> @ref SO_DESTPORT </td> <td> uint16_t </td><td> </td></tr> |
|---|
| 465 | * <tr> <td> @ref SO_KEEPALIVEAUTO </td> <td> uint8_t </td><td> 0 ~ 255 </td></tr> |
|---|
| 466 | * <tr> <td> @ref SO_SENDBUF </td> <td> uint16_t </td><td> 0 ~ 65535 </td></tr> |
|---|
| 467 | * <tr> <td> @ref SO_RECVBUF </td> <td> uint16_t </td><td> 0 ~ 65535 </td></tr> |
|---|
| 468 | * <tr> <td> @ref SO_STATUS </td> <td> uint8_t </td><td> @ref SOCK_ESTABLISHED, etc.. </td></tr> |
|---|
| 469 | * <tr> <td> @ref SO_REMAINSIZE </td> <td> uint16_t </td><td> 0~ 65535 </td></tr> |
|---|
| 470 | * <tr> <td> @ref SO_PACKINFO </td> <td> uint8_t </td><td> @ref PACK_FIRST, etc... </td></tr> |
|---|
| 471 | * </table> |
|---|
| 472 | * @return |
|---|
| 473 | * - @b Success : @ref SOCK_OK \n |
|---|
| 474 | * - @b Fail |
|---|
| 475 | * - @ref SOCKERR_SOCKNUM - Invalid Socket number \n |
|---|
| 476 | * - @ref SOCKERR_SOCKOPT - Invalid socket option or its value \n |
|---|
| 477 | * - @ref SOCKERR_SOCKMODE - Invalid socket mode \n |
|---|
| 478 | * @note |
|---|
| 479 | * The option as PACK_REMAINED and SO_PACKINFO is valid only in NON-TCP mode and after call @ref recvfrom(). \n |
|---|
| 480 | * When SO_PACKINFO value is PACK_FIRST and the return value of recvfrom() is zero, |
|---|
| 481 | * This means the zero byte UDP data(UDP Header only) received. |
|---|
| 482 | */ |
|---|
| 483 | int8_t getsockopt(uint8_t sn, sockopt_type sotype, void* arg); |
|---|
| 484 | |
|---|
| 485 | #ifdef __cplusplus |
|---|
| 486 | } |
|---|
| 487 | #endif |
|---|
| 488 | |
|---|
| 489 | #endif // _SOCKET_H_ |
|---|
