1 /* 2 * Copyright (c) 2001-2004 Swedish Institute of Computer Science. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without modification, 6 * are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, 9 * this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright notice, 11 * this list of conditions and the following disclaimer in the documentation 12 * and/or other materials provided with the distribution. 13 * 3. The name of the author may not be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 19 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 20 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 21 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 24 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 25 * OF SUCH DAMAGE. 26 * 27 * This file is part of the lwIP TCP/IP stack. 28 * 29 * Author: Adam Dunkels <adam@sics.se> 30 * 31 */ 32 #ifndef __LWIP_API_H__ 33 #define __LWIP_API_H__ 34 35 #include "lwip/opt.h" 36 37 #if LWIP_NETCONN /* don't build if not configured for use in lwipopts.h */ 38 39 #include <stddef.h> /* for size_t */ 40 41 #include "lwip/netbuf.h" 42 #include "lwip/sys.h" 43 #include "lwip/ip_addr.h" 44 #include "lwip/err.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /* Throughout this file, IP addresses and port numbers are expected to be in 51 * the same byte order as in the corresponding pcb. 52 */ 53 54 /* Flags for netconn_write (u8_t) */ 55 #define NETCONN_NOFLAG 0x00 56 #define NETCONN_NOCOPY 0x00 /* Only for source code compatibility */ 57 #define NETCONN_COPY 0x01 58 #define NETCONN_MORE 0x02 59 #define NETCONN_DONTBLOCK 0x04 60 61 /* Flags for struct netconn.flags (u8_t) */ 62 /** TCP: when data passed to netconn_write doesn't fit into the send buffer, 63 this temporarily stores whether to wake up the original application task 64 if data couldn't be sent in the first try. */ 65 #define NETCONN_FLAG_WRITE_DELAYED 0x01 66 /** Should this netconn avoid blocking? */ 67 #define NETCONN_FLAG_NON_BLOCKING 0x02 68 /** Was the last connect action a non-blocking one? */ 69 #define NETCONN_FLAG_IN_NONBLOCKING_CONNECT 0x04 70 /** If this is set, a TCP netconn must call netconn_recved() to update 71 the TCP receive window (done automatically if not set). */ 72 #define NETCONN_FLAG_NO_AUTO_RECVED 0x08 73 /** If a nonblocking write has been rejected before, poll_tcp needs to 74 check if the netconn is writable again */ 75 #define NETCONN_FLAG_CHECK_WRITESPACE 0x10 76 77 78 /* Helpers to process several netconn_types by the same code */ 79 #define NETCONNTYPE_GROUP(t) (t&0xF0) 80 #define NETCONNTYPE_DATAGRAM(t) (t&0xE0) 81 82 /** Protocol family and type of the netconn */ 83 enum netconn_type { 84 NETCONN_INVALID = 0, 85 /* NETCONN_TCP Group */ 86 NETCONN_TCP = 0x10, 87 /* NETCONN_UDP Group */ 88 NETCONN_UDP = 0x20, 89 NETCONN_UDPLITE = 0x21, 90 NETCONN_UDPNOCHKSUM= 0x22, 91 /* NETCONN_RAW Group */ 92 NETCONN_RAW = 0x40 93 }; 94 95 /** Current state of the netconn. Non-TCP netconns are always 96 * in state NETCONN_NONE! */ 97 enum netconn_state { 98 NETCONN_NONE, 99 NETCONN_WRITE, 100 NETCONN_LISTEN, 101 NETCONN_CONNECT, 102 NETCONN_CLOSE 103 }; 104 105 /** Use to inform the callback function about changes */ 106 enum netconn_evt { 107 NETCONN_EVT_RCVPLUS, 108 NETCONN_EVT_RCVMINUS, 109 NETCONN_EVT_SENDPLUS, 110 NETCONN_EVT_SENDMINUS, 111 NETCONN_EVT_ERROR 112 }; 113 114 #if LWIP_IGMP 115 /** Used for netconn_join_leave_group() */ 116 enum netconn_igmp { 117 NETCONN_JOIN, 118 NETCONN_LEAVE 119 }; 120 #endif /* LWIP_IGMP */ 121 122 /* forward-declare some structs to avoid to include their headers */ 123 struct ip_pcb; 124 struct tcp_pcb; 125 struct udp_pcb; 126 struct raw_pcb; 127 struct netconn; 128 struct api_msg_msg; 129 130 /** A callback prototype to inform about events for a netconn */ 131 typedef void (* netconn_callback)(struct netconn *, enum netconn_evt, u16_t len); 132 133 /** A netconn descriptor */ 134 struct netconn { 135 /** type of the netconn (TCP, UDP or RAW) */ 136 enum netconn_type type; 137 /** current state of the netconn */ 138 enum netconn_state state; 139 /** the lwIP internal protocol control block */ 140 union { 141 struct ip_pcb *ip; 142 struct tcp_pcb *tcp; 143 struct udp_pcb *udp; 144 struct raw_pcb *raw; 145 } pcb; 146 /** the last error this netconn had */ 147 err_t last_err; 148 /** sem that is used to synchroneously execute functions in the core context */ 149 sys_sem_t op_completed; 150 /** mbox where received packets are stored until they are fetched 151 by the netconn application thread (can grow quite big) */ 152 sys_mbox_t recvmbox; 153 #if LWIP_TCP 154 /** mbox where new connections are stored until processed 155 by the application thread */ 156 sys_mbox_t acceptmbox; 157 #endif /* LWIP_TCP */ 158 /** only used for socket layer */ 159 #if LWIP_SOCKET 160 int socket; 161 #endif /* LWIP_SOCKET */ 162 #if LWIP_SO_SNDTIMEO 163 /** timeout to wait for sending data (which means enqueueing data for sending 164 in internal buffers) */ 165 s32_t send_timeout; 166 #endif /* LWIP_SO_RCVTIMEO */ 167 #if LWIP_SO_RCVTIMEO 168 /** timeout to wait for new data to be received 169 (or connections to arrive for listening netconns) */ 170 int recv_timeout; 171 #endif /* LWIP_SO_RCVTIMEO */ 172 #if LWIP_SO_RCVBUF 173 /** maximum amount of bytes queued in recvmbox 174 not used for TCP: adjust TCP_WND instead! */ 175 int recv_bufsize; 176 /** number of bytes currently in recvmbox to be received, 177 tested against recv_bufsize to limit bytes on recvmbox 178 for UDP and RAW, used for FIONREAD */ 179 s16_t recv_avail; 180 #endif /* LWIP_SO_RCVBUF */ 181 /** flags holding more netconn-internal state, see NETCONN_FLAG_* defines */ 182 u8_t flags; 183 #if LWIP_TCP 184 /** TCP: when data passed to netconn_write doesn't fit into the send buffer, 185 this temporarily stores how much is already sent. */ 186 size_t write_offset; 187 /** TCP: when data passed to netconn_write doesn't fit into the send buffer, 188 this temporarily stores the message. 189 Also used during connect and close. */ 190 struct api_msg_msg *current_msg; 191 #endif /* LWIP_TCP */ 192 /** A callback function that is informed about events for this netconn */ 193 netconn_callback callback; 194 }; 195 196 /** Register an Network connection event */ 197 #define API_EVENT(c,e,l) if (c->callback) { \ 198 (*c->callback)(c, e, l); \ 199 } 200 201 /** Set conn->last_err to err but don't overwrite fatal errors */ 202 #define NETCONN_SET_SAFE_ERR(conn, err) do { \ 203 SYS_ARCH_DECL_PROTECT(lev); \ 204 SYS_ARCH_PROTECT(lev); \ 205 if (!ERR_IS_FATAL((conn)->last_err)) { \ 206 (conn)->last_err = err; \ 207 } \ 208 SYS_ARCH_UNPROTECT(lev); \ 209 } while(0); 210 211 /* Network connection functions: */ 212 #define netconn_new(t) netconn_new_with_proto_and_callback(t, 0, NULL) 213 #define netconn_new_with_callback(t, c) netconn_new_with_proto_and_callback(t, 0, c) 214 struct 215 netconn *netconn_new_with_proto_and_callback(enum netconn_type t, u8_t proto, 216 netconn_callback callback); 217 err_t netconn_delete(struct netconn *conn); 218 /** Get the type of a netconn (as enum netconn_type). */ 219 #define netconn_type(conn) (conn->type) 220 221 err_t netconn_getaddr(struct netconn *conn, ip_addr_t *addr, 222 u16_t *port, u8_t local); 223 #define netconn_peer(c,i,p) netconn_getaddr(c,i,p,0) 224 #define netconn_addr(c,i,p) netconn_getaddr(c,i,p,1) 225 226 err_t netconn_bind(struct netconn *conn, ip_addr_t *addr, u16_t port); 227 err_t netconn_connect(struct netconn *conn, ip_addr_t *addr, u16_t port); 228 err_t netconn_disconnect (struct netconn *conn); 229 err_t netconn_listen_with_backlog(struct netconn *conn, u8_t backlog); 230 #define netconn_listen(conn) netconn_listen_with_backlog(conn, TCP_DEFAULT_LISTEN_BACKLOG) 231 err_t netconn_accept(struct netconn *conn, struct netconn **new_conn); 232 err_t netconn_recv(struct netconn *conn, struct netbuf **new_buf); 233 err_t netconn_recv_tcp_pbuf(struct netconn *conn, struct pbuf **new_buf); 234 void netconn_recved(struct netconn *conn, u32_t length); 235 err_t netconn_sendto(struct netconn *conn, struct netbuf *buf, 236 ip_addr_t *addr, u16_t port); 237 err_t netconn_send(struct netconn *conn, struct netbuf *buf); 238 err_t netconn_write_partly(struct netconn *conn, const void *dataptr, size_t size, 239 u8_t apiflags, size_t *bytes_written); 240 #define netconn_write(conn, dataptr, size, apiflags) \ 241 netconn_write_partly(conn, dataptr, size, apiflags, NULL) 242 err_t netconn_close(struct netconn *conn); 243 err_t netconn_shutdown(struct netconn *conn, u8_t shut_rx, u8_t shut_tx); 244 245 #if LWIP_IGMP 246 err_t netconn_join_leave_group(struct netconn *conn, ip_addr_t *multiaddr, 247 ip_addr_t *netif_addr, enum netconn_igmp join_or_leave); 248 #endif /* LWIP_IGMP */ 249 #if LWIP_DNS 250 err_t netconn_gethostbyname(const char *name, ip_addr_t *addr); 251 #endif /* LWIP_DNS */ 252 253 #define netconn_err(conn) ((conn)->last_err) 254 #define netconn_recv_bufsize(conn) ((conn)->recv_bufsize) 255 256 /** Set the blocking status of netconn calls (@todo: write/send is missing) */ 257 #define netconn_set_nonblocking(conn, val) do { if(val) { \ 258 (conn)->flags |= NETCONN_FLAG_NON_BLOCKING; \ 259 } else { \ 260 (conn)->flags &= ~ NETCONN_FLAG_NON_BLOCKING; }} while(0) 261 /** Get the blocking status of netconn calls (@todo: write/send is missing) */ 262 #define netconn_is_nonblocking(conn) (((conn)->flags & NETCONN_FLAG_NON_BLOCKING) != 0) 263 264 /** TCP: Set the no-auto-recved status of netconn calls (see NETCONN_FLAG_NO_AUTO_RECVED) */ 265 #define netconn_set_noautorecved(conn, val) do { if(val) { \ 266 (conn)->flags |= NETCONN_FLAG_NO_AUTO_RECVED; \ 267 } else { \ 268 (conn)->flags &= ~ NETCONN_FLAG_NO_AUTO_RECVED; }} while(0) 269 /** TCP: Get the no-auto-recved status of netconn calls (see NETCONN_FLAG_NO_AUTO_RECVED) */ 270 #define netconn_get_noautorecved(conn) (((conn)->flags & NETCONN_FLAG_NO_AUTO_RECVED) != 0) 271 272 #if LWIP_SO_SNDTIMEO 273 /** Set the send timeout in milliseconds */ 274 #define netconn_set_sendtimeout(conn, timeout) ((conn)->send_timeout = (timeout)) 275 /** Get the send timeout in milliseconds */ 276 #define netconn_get_sendtimeout(conn) ((conn)->send_timeout) 277 #endif /* LWIP_SO_SNDTIMEO */ 278 #if LWIP_SO_RCVTIMEO 279 /** Set the receive timeout in milliseconds */ 280 #define netconn_set_recvtimeout(conn, timeout) ((conn)->recv_timeout = (timeout)) 281 /** Get the receive timeout in milliseconds */ 282 #define netconn_get_recvtimeout(conn) ((conn)->recv_timeout) 283 #endif /* LWIP_SO_RCVTIMEO */ 284 #if LWIP_SO_RCVBUF 285 /** Set the receive buffer in bytes */ 286 #define netconn_set_recvbufsize(conn, recvbufsize) ((conn)->recv_bufsize = (recvbufsize)) 287 /** Get the receive buffer in bytes */ 288 #define netconn_get_recvbufsize(conn) ((conn)->recv_bufsize) 289 #endif /* LWIP_SO_RCVBUF*/ 290 291 #ifdef __cplusplus 292 } 293 #endif 294 295 #endif /* LWIP_NETCONN */ 296 297 #endif /* __LWIP_API_H__ */ 298