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 (at) 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_RCVTIMEO 163 /** timeout to wait for new data to be received 164 (or connections to arrive for listening netconns) */ 165 int recv_timeout; 166 #endif /* LWIP_SO_RCVTIMEO */ 167 #if LWIP_SO_RCVBUF 168 /** maximum amount of bytes queued in recvmbox 169 not used for TCP: adjust TCP_WND instead! */ 170 int recv_bufsize; 171 /** number of bytes currently in recvmbox to be received, 172 tested against recv_bufsize to limit bytes on recvmbox 173 for UDP and RAW, used for FIONREAD */ 174 s16_t recv_avail; 175 #endif /* LWIP_SO_RCVBUF */ 176 /** flags holding more netconn-internal state, see NETCONN_FLAG_* defines */ 177 u8_t flags; 178 #if LWIP_TCP 179 /** TCP: when data passed to netconn_write doesn't fit into the send buffer, 180 this temporarily stores how much is already sent. */ 181 size_t write_offset; 182 /** TCP: when data passed to netconn_write doesn't fit into the send buffer, 183 this temporarily stores the message. 184 Also used during connect and close. */ 185 struct api_msg_msg *current_msg; 186 #endif /* LWIP_TCP */ 187 /** A callback function that is informed about events for this netconn */ 188 netconn_callback callback; 189 }; 190 191 /** Register an Network connection event */ 192 #define API_EVENT(c,e,l) if (c->callback) { \ 193 (*c->callback)(c, e, l); \ 194 } 195 196 /** Set conn->last_err to err but don't overwrite fatal errors */ 197 #define NETCONN_SET_SAFE_ERR(conn, err) do { \ 198 SYS_ARCH_DECL_PROTECT(lev); \ 199 SYS_ARCH_PROTECT(lev); \ 200 if (!ERR_IS_FATAL((conn)->last_err)) { \ 201 (conn)->last_err = err; \ 202 } \ 203 SYS_ARCH_UNPROTECT(lev); \ 204 } while(0); 205 206 /* Network connection functions: */ 207 #define netconn_new(t) netconn_new_with_proto_and_callback(t, 0, NULL) 208 #define netconn_new_with_callback(t, c) netconn_new_with_proto_and_callback(t, 0, c) 209 struct 210 netconn *netconn_new_with_proto_and_callback(enum netconn_type t, u8_t proto, 211 netconn_callback callback); 212 err_t netconn_delete(struct netconn *conn); 213 /** Get the type of a netconn (as enum netconn_type). */ 214 #define netconn_type(conn) (conn->type) 215 216 err_t netconn_getaddr(struct netconn *conn, ip_addr_t *addr, 217 u16_t *port, u8_t local); 218 #define netconn_peer(c,i,p) netconn_getaddr(c,i,p,0) 219 #define netconn_addr(c,i,p) netconn_getaddr(c,i,p,1) 220 221 err_t netconn_bind(struct netconn *conn, ip_addr_t *addr, u16_t port); 222 err_t netconn_connect(struct netconn *conn, ip_addr_t *addr, u16_t port); 223 err_t netconn_disconnect (struct netconn *conn); 224 err_t netconn_listen_with_backlog(struct netconn *conn, u8_t backlog); 225 #define netconn_listen(conn) netconn_listen_with_backlog(conn, TCP_DEFAULT_LISTEN_BACKLOG) 226 err_t netconn_accept(struct netconn *conn, struct netconn **new_conn); 227 err_t netconn_recv(struct netconn *conn, struct netbuf **new_buf); 228 err_t netconn_recv_tcp_pbuf(struct netconn *conn, struct pbuf **new_buf); 229 void netconn_recved(struct netconn *conn, u32_t length); 230 err_t netconn_sendto(struct netconn *conn, struct netbuf *buf, 231 ip_addr_t *addr, u16_t port); 232 err_t netconn_send(struct netconn *conn, struct netbuf *buf); 233 err_t netconn_write(struct netconn *conn, const void *dataptr, size_t size, 234 u8_t apiflags); 235 err_t netconn_close(struct netconn *conn); 236 err_t netconn_shutdown(struct netconn *conn, u8_t shut_rx, u8_t shut_tx); 237 238 #if LWIP_IGMP 239 err_t netconn_join_leave_group(struct netconn *conn, ip_addr_t *multiaddr, 240 ip_addr_t *netif_addr, enum netconn_igmp join_or_leave); 241 #endif /* LWIP_IGMP */ 242 #if LWIP_DNS 243 err_t netconn_gethostbyname(const char *name, ip_addr_t *addr); 244 #endif /* LWIP_DNS */ 245 246 #define netconn_err(conn) ((conn)->last_err) 247 #define netconn_recv_bufsize(conn) ((conn)->recv_bufsize) 248 249 /** Set the blocking status of netconn calls (@todo: write/send is missing) */ 250 #define netconn_set_nonblocking(conn, val) do { if(val) { \ 251 (conn)->flags |= NETCONN_FLAG_NON_BLOCKING; \ 252 } else { \ 253 (conn)->flags &= ~ NETCONN_FLAG_NON_BLOCKING; }} while(0) 254 /** Get the blocking status of netconn calls (@todo: write/send is missing) */ 255 #define netconn_is_nonblocking(conn) (((conn)->flags & NETCONN_FLAG_NON_BLOCKING) != 0) 256 257 /** TCP: Set the no-auto-recved status of netconn calls (see NETCONN_FLAG_NO_AUTO_RECVED) */ 258 #define netconn_set_noautorecved(conn, val) do { if(val) { \ 259 (conn)->flags |= NETCONN_FLAG_NO_AUTO_RECVED; \ 260 } else { \ 261 (conn)->flags &= ~ NETCONN_FLAG_NO_AUTO_RECVED; }} while(0) 262 /** TCP: Get the no-auto-recved status of netconn calls (see NETCONN_FLAG_NO_AUTO_RECVED) */ 263 #define netconn_get_noautorecved(conn) (((conn)->flags & NETCONN_FLAG_NO_AUTO_RECVED) != 0) 264 265 #if LWIP_SO_RCVTIMEO 266 /** Set the receive timeout in milliseconds */ 267 #define netconn_set_recvtimeout(conn, timeout) ((conn)->recv_timeout = (timeout)) 268 /** Get the receive timeout in milliseconds */ 269 #define netconn_get_recvtimeout(conn) ((conn)->recv_timeout) 270 #endif /* LWIP_SO_RCVTIMEO */ 271 #if LWIP_SO_RCVBUF 272 /** Set the receive buffer in bytes */ 273 #define netconn_set_recvbufsize(conn, recvbufsize) ((conn)->recv_bufsize = (recvbufsize)) 274 /** Get the receive buffer in bytes */ 275 #define netconn_get_recvbufsize(conn) ((conn)->recv_bufsize) 276 #endif /* LWIP_SO_RCVBUF*/ 277 278 #ifdef __cplusplus 279 } 280 #endif 281 282 #endif /* LWIP_NETCONN */ 283 284 #endif /* __LWIP_API_H__ */ 285
