Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
api.h
00001 /** 00002 * @file 00003 * netconn API (to be used from non-TCPIP threads) 00004 */ 00005 00006 /* 00007 * Copyright (c) 2001-2004 Swedish Institute of Computer Science. 00008 * All rights reserved. 00009 * 00010 * Redistribution and use in source and binary forms, with or without modification, 00011 * are permitted provided that the following conditions are met: 00012 * 00013 * 1. Redistributions of source code must retain the above copyright notice, 00014 * this list of conditions and the following disclaimer. 00015 * 2. Redistributions in binary form must reproduce the above copyright notice, 00016 * this list of conditions and the following disclaimer in the documentation 00017 * and/or other materials provided with the distribution. 00018 * 3. The name of the author may not be used to endorse or promote products 00019 * derived from this software without specific prior written permission. 00020 * 00021 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 00022 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 00023 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 00024 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00025 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 00026 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 00027 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 00028 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 00029 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 00030 * OF SUCH DAMAGE. 00031 * 00032 * This file is part of the lwIP TCP/IP stack. 00033 * 00034 * Author: Adam Dunkels <adam@sics.se> 00035 * 00036 */ 00037 #ifndef LWIP_HDR_API_H 00038 #define LWIP_HDR_API_H 00039 00040 #include "lwip/opt.h" 00041 00042 #if LWIP_NETCONN || LWIP_SOCKET /* don't build if not configured for use in lwipopts.h */ 00043 /* Note: Netconn API is always available when sockets are enabled - 00044 * sockets are implemented on top of them */ 00045 00046 #include "lwip/arch.h" 00047 #include "lwip/netbuf.h" 00048 #include "lwip/sys.h" 00049 #include "lwip/ip_addr.h" 00050 #include "lwip/err.h" 00051 00052 #ifdef __cplusplus 00053 extern "C" { 00054 #endif 00055 00056 /* Throughout this file, IP addresses and port numbers are expected to be in 00057 * the same byte order as in the corresponding pcb. 00058 */ 00059 00060 /* Flags for netconn_write (u8_t) */ 00061 #define NETCONN_NOFLAG 0x00 00062 #define NETCONN_NOCOPY 0x00 /* Only for source code compatibility */ 00063 #define NETCONN_COPY 0x01 00064 #define NETCONN_MORE 0x02 00065 #define NETCONN_DONTBLOCK 0x04 00066 00067 /* Flags for struct netconn.flags (u8_t) */ 00068 /** Should this netconn avoid blocking? */ 00069 #define NETCONN_FLAG_NON_BLOCKING 0x02 00070 /** Was the last connect action a non-blocking one? */ 00071 #define NETCONN_FLAG_IN_NONBLOCKING_CONNECT 0x04 00072 /** If a nonblocking write has been rejected before, poll_tcp needs to 00073 check if the netconn is writable again */ 00074 #define NETCONN_FLAG_CHECK_WRITESPACE 0x10 00075 #if LWIP_IPV6 00076 /** If this flag is set then only IPv6 communication is allowed on the 00077 netconn. As per RFC#3493 this features defaults to OFF allowing 00078 dual-stack usage by default. */ 00079 #define NETCONN_FLAG_IPV6_V6ONLY 0x20 00080 #endif /* LWIP_IPV6 */ 00081 00082 00083 /* Helpers to process several netconn_types by the same code */ 00084 #define NETCONNTYPE_GROUP(t) ((t)&0xF0) 00085 #define NETCONNTYPE_DATAGRAM(t) ((t)&0xE0) 00086 #if LWIP_IPV6 00087 #define NETCONN_TYPE_IPV6 0x08 00088 #define NETCONNTYPE_ISIPV6(t) (((t)&NETCONN_TYPE_IPV6) != 0) 00089 #define NETCONNTYPE_ISUDPLITE(t) (((t)&0xF3) == NETCONN_UDPLITE) 00090 #define NETCONNTYPE_ISUDPNOCHKSUM(t) (((t)&0xF3) == NETCONN_UDPNOCHKSUM) 00091 #else /* LWIP_IPV6 */ 00092 #define NETCONNTYPE_ISIPV6(t) (0) 00093 #define NETCONNTYPE_ISUDPLITE(t) ((t) == NETCONN_UDPLITE) 00094 #define NETCONNTYPE_ISUDPNOCHKSUM(t) ((t) == NETCONN_UDPNOCHKSUM) 00095 #endif /* LWIP_IPV6 */ 00096 00097 /** @ingroup netconn_common 00098 * Protocol family and type of the netconn 00099 */ 00100 enum netconn_type { 00101 NETCONN_INVALID = 0, 00102 /** TCP IPv4 */ 00103 NETCONN_TCP = 0x10, 00104 #if LWIP_IPV6 00105 /** TCP IPv6 */ 00106 NETCONN_TCP_IPV6 = NETCONN_TCP | NETCONN_TYPE_IPV6 /* 0x18 */, 00107 #endif /* LWIP_IPV6 */ 00108 /** UDP IPv4 */ 00109 NETCONN_UDP = 0x20, 00110 /** UDP IPv4 lite */ 00111 NETCONN_UDPLITE = 0x21, 00112 /** UDP IPv4 no checksum */ 00113 NETCONN_UDPNOCHKSUM = 0x22, 00114 00115 #if LWIP_IPV6 00116 /** UDP IPv6 (dual-stack by default, unless you call @ref netconn_set_ipv6only) */ 00117 NETCONN_UDP_IPV6 = NETCONN_UDP | NETCONN_TYPE_IPV6 /* 0x28 */, 00118 /** UDP IPv6 lite (dual-stack by default, unless you call @ref netconn_set_ipv6only) */ 00119 NETCONN_UDPLITE_IPV6 = NETCONN_UDPLITE | NETCONN_TYPE_IPV6 /* 0x29 */, 00120 /** UDP IPv6 no checksum (dual-stack by default, unless you call @ref netconn_set_ipv6only) */ 00121 NETCONN_UDPNOCHKSUM_IPV6 = NETCONN_UDPNOCHKSUM | NETCONN_TYPE_IPV6 /* 0x2a */, 00122 #endif /* LWIP_IPV6 */ 00123 00124 /** Raw connection IPv4 */ 00125 NETCONN_RAW = 0x40 00126 #if LWIP_IPV6 00127 /** Raw connection IPv6 (dual-stack by default, unless you call @ref netconn_set_ipv6only) */ 00128 , NETCONN_RAW_IPV6 = NETCONN_RAW | NETCONN_TYPE_IPV6 /* 0x48 */ 00129 #endif /* LWIP_IPV6 */ 00130 }; 00131 00132 /** Current state of the netconn. Non-TCP netconns are always 00133 * in state NETCONN_NONE! */ 00134 enum netconn_state { 00135 NETCONN_NONE, 00136 NETCONN_WRITE, 00137 NETCONN_LISTEN, 00138 NETCONN_CONNECT, 00139 NETCONN_CLOSE 00140 }; 00141 00142 /** Used to inform the callback function about changes 00143 * 00144 * Event explanation: 00145 * 00146 * In the netconn implementation, there are three ways to block a client: 00147 * 00148 * - accept mbox (sys_arch_mbox_fetch(&conn->acceptmbox, &accept_ptr, 0); in netconn_accept()) 00149 * - receive mbox (sys_arch_mbox_fetch(&conn->recvmbox, &buf, 0); in netconn_recv_data()) 00150 * - send queue is full (sys_arch_sem_wait(LWIP_API_MSG_SEM(msg), 0); in lwip_netconn_do_write()) 00151 * 00152 * The events have to be seen as events signaling the state of these mboxes/semaphores. For non-blocking 00153 * connections, you need to know in advance whether a call to a netconn function call would block or not, 00154 * and these events tell you about that. 00155 * 00156 * RCVPLUS events say: Safe to perform a potentially blocking call call once more. 00157 * They are counted in sockets - three RCVPLUS events for accept mbox means you are safe 00158 * to call netconn_accept 3 times without being blocked. 00159 * Same thing for receive mbox. 00160 * 00161 * RCVMINUS events say: Your call to to a possibly blocking function is "acknowledged". 00162 * Socket implementation decrements the counter. 00163 * 00164 * For TX, there is no need to count, its merely a flag. SENDPLUS means you may send something. 00165 * SENDPLUS occurs when enough data was delivered to peer so netconn_send() can be called again. 00166 * A SENDMINUS event occurs when the next call to a netconn_send() would be blocking. 00167 */ 00168 enum netconn_evt { 00169 NETCONN_EVT_RCVPLUS, 00170 NETCONN_EVT_RCVMINUS, 00171 NETCONN_EVT_SENDPLUS, 00172 NETCONN_EVT_SENDMINUS, 00173 NETCONN_EVT_ERROR 00174 }; 00175 00176 #if LWIP_IGMP || (LWIP_IPV6 && LWIP_IPV6_MLD) 00177 /** Used for netconn_join_leave_group() */ 00178 enum netconn_igmp { 00179 NETCONN_JOIN, 00180 NETCONN_LEAVE 00181 }; 00182 #endif /* LWIP_IGMP || (LWIP_IPV6 && LWIP_IPV6_MLD) */ 00183 00184 #if LWIP_DNS 00185 /* Used for netconn_gethostbyname_addrtype(), these should match the DNS_ADDRTYPE defines in dns.h */ 00186 #define NETCONN_DNS_DEFAULT NETCONN_DNS_IPV4_IPV6 00187 #define NETCONN_DNS_IPV4 0 00188 #define NETCONN_DNS_IPV6 1 00189 #define NETCONN_DNS_IPV4_IPV6 2 /* try to resolve IPv4 first, try IPv6 if IPv4 fails only */ 00190 #define NETCONN_DNS_IPV6_IPV4 3 /* try to resolve IPv6 first, try IPv4 if IPv6 fails only */ 00191 #endif /* LWIP_DNS */ 00192 00193 /* forward-declare some structs to avoid to include their headers */ 00194 struct ip_pcb; 00195 struct tcp_pcb; 00196 struct udp_pcb; 00197 struct raw_pcb; 00198 struct netconn; 00199 struct api_msg; 00200 00201 /** A callback prototype to inform about events for a netconn */ 00202 typedef void (* netconn_callback)(struct netconn *, enum netconn_evt, u16_t len); 00203 00204 /** A netconn descriptor */ 00205 struct netconn { 00206 /** type of the netconn (TCP, UDP or RAW) */ 00207 enum netconn_type type; 00208 /** current state of the netconn */ 00209 enum netconn_state state; 00210 /** the lwIP internal protocol control block */ 00211 union { 00212 struct ip_pcb *ip; 00213 struct tcp_pcb *tcp; 00214 struct udp_pcb *udp; 00215 struct raw_pcb *raw; 00216 } pcb; 00217 /** the last error this netconn had */ 00218 err_t last_err; 00219 #if !LWIP_NETCONN_SEM_PER_THREAD 00220 /** sem that is used to synchronously execute functions in the core context */ 00221 sys_sem_t op_completed; 00222 #endif 00223 /** mbox where received packets are stored until they are fetched 00224 by the netconn application thread (can grow quite big) */ 00225 sys_mbox_t recvmbox; 00226 #if LWIP_TCP 00227 /** mbox where new connections are stored until processed 00228 by the application thread */ 00229 sys_mbox_t acceptmbox; 00230 #endif /* LWIP_TCP */ 00231 /** only used for socket layer */ 00232 #if LWIP_SOCKET 00233 int socket; 00234 #endif /* LWIP_SOCKET */ 00235 #if LWIP_SO_SNDTIMEO 00236 /** timeout to wait for sending data (which means enqueueing data for sending 00237 in internal buffers) in milliseconds */ 00238 s32_t send_timeout; 00239 #endif /* LWIP_SO_RCVTIMEO */ 00240 #if LWIP_SO_RCVTIMEO 00241 /** timeout in milliseconds to wait for new data to be received 00242 (or connections to arrive for listening netconns) */ 00243 int recv_timeout; 00244 #endif /* LWIP_SO_RCVTIMEO */ 00245 #if LWIP_SO_RCVBUF 00246 /** maximum amount of bytes queued in recvmbox 00247 not used for TCP: adjust TCP_WND instead! */ 00248 int recv_bufsize; 00249 /** number of bytes currently in recvmbox to be received, 00250 tested against recv_bufsize to limit bytes on recvmbox 00251 for UDP and RAW, used for FIONREAD */ 00252 int recv_avail; 00253 #endif /* LWIP_SO_RCVBUF */ 00254 #if LWIP_SO_LINGER 00255 /** values <0 mean linger is disabled, values > 0 are seconds to linger */ 00256 s16_t linger; 00257 #endif /* LWIP_SO_LINGER */ 00258 /** flags holding more netconn-internal state, see NETCONN_FLAG_* defines */ 00259 u8_t flags; 00260 #if LWIP_TCP 00261 /** TCP: when data passed to netconn_write doesn't fit into the send buffer, 00262 this temporarily stores how much is already sent. */ 00263 size_t write_offset; 00264 /** TCP: when data passed to netconn_write doesn't fit into the send buffer, 00265 this temporarily stores the message. 00266 Also used during connect and close. */ 00267 struct api_msg *current_msg; 00268 #endif /* LWIP_TCP */ 00269 /** A callback function that is informed about events for this netconn */ 00270 netconn_callback callback; 00271 }; 00272 00273 /** Register an Network connection event */ 00274 #define API_EVENT(c,e,l) if (c->callback) { \ 00275 (*c->callback)(c, e, l); \ 00276 } 00277 00278 /** Set conn->last_err to err but don't overwrite fatal errors */ 00279 #define NETCONN_SET_SAFE_ERR(conn, err) do { if ((conn) != NULL) { \ 00280 SYS_ARCH_DECL_PROTECT(netconn_set_safe_err_lev); \ 00281 SYS_ARCH_PROTECT(netconn_set_safe_err_lev); \ 00282 if (!ERR_IS_FATAL((conn)->last_err)) { \ 00283 (conn)->last_err = err; \ 00284 } \ 00285 SYS_ARCH_UNPROTECT(netconn_set_safe_err_lev); \ 00286 }} while(0); 00287 00288 /* Network connection functions: */ 00289 00290 /** @ingroup netconn_common 00291 * Create new netconn connection 00292 * @param t @ref netconn_type */ 00293 #define netconn_new(t) netconn_new_with_proto_and_callback(t, 0, NULL) 00294 #define netconn_new_with_callback(t, c) netconn_new_with_proto_and_callback(t, 0, c) 00295 struct netconn *netconn_new_with_proto_and_callback(enum netconn_type t, u8_t proto, 00296 netconn_callback callback); 00297 err_t netconn_delete(struct netconn *conn); 00298 /** Get the type of a netconn (as enum netconn_type). */ 00299 #define netconn_type(conn) (conn->type) 00300 00301 err_t netconn_getaddr(struct netconn *conn, ip_addr_t *addr, 00302 u16_t *port, u8_t local); 00303 /** @ingroup netconn_common */ 00304 #define netconn_peer(c,i,p) netconn_getaddr(c,i,p,0) 00305 /** @ingroup netconn_common */ 00306 #define netconn_addr(c,i,p) netconn_getaddr(c,i,p,1) 00307 00308 err_t netconn_bind(struct netconn *conn, const ip_addr_t *addr, u16_t port); 00309 err_t netconn_connect(struct netconn *conn, const ip_addr_t *addr, u16_t port); 00310 err_t netconn_disconnect (struct netconn *conn); 00311 err_t netconn_listen_with_backlog(struct netconn *conn, u8_t backlog); 00312 /** @ingroup netconn_tcp */ 00313 #define netconn_listen(conn) netconn_listen_with_backlog(conn, TCP_DEFAULT_LISTEN_BACKLOG) 00314 err_t netconn_accept(struct netconn *conn, struct netconn **new_conn); 00315 err_t netconn_recv(struct netconn *conn, struct netbuf **new_buf); 00316 err_t netconn_recv_tcp_pbuf(struct netconn *conn, struct pbuf **new_buf); 00317 err_t netconn_sendto(struct netconn *conn, struct netbuf *buf, 00318 const ip_addr_t *addr, u16_t port); 00319 err_t netconn_send(struct netconn *conn, struct netbuf *buf); 00320 err_t netconn_write_partly(struct netconn *conn, const void *dataptr, size_t size, 00321 u8_t apiflags, size_t *bytes_written); 00322 /** @ingroup netconn_tcp */ 00323 #define netconn_write(conn, dataptr, size, apiflags) \ 00324 netconn_write_partly(conn, dataptr, size, apiflags, NULL) 00325 err_t netconn_close(struct netconn *conn); 00326 err_t netconn_shutdown(struct netconn *conn, u8_t shut_rx, u8_t shut_tx); 00327 00328 #if LWIP_IGMP || (LWIP_IPV6 && LWIP_IPV6_MLD) 00329 err_t netconn_join_leave_group(struct netconn *conn, const ip_addr_t *multiaddr, 00330 const ip_addr_t *netif_addr, enum netconn_igmp join_or_leave); 00331 #endif /* LWIP_IGMP || (LWIP_IPV6 && LWIP_IPV6_MLD) */ 00332 #if LWIP_DNS 00333 #if LWIP_IPV4 && LWIP_IPV6 00334 err_t netconn_gethostbyname_addrtype(const char *name, ip_addr_t *addr, u8_t dns_addrtype); 00335 #define netconn_gethostbyname(name, addr) netconn_gethostbyname_addrtype(name, addr, NETCONN_DNS_DEFAULT) 00336 #else /* LWIP_IPV4 && LWIP_IPV6 */ 00337 err_t netconn_gethostbyname(const char *name, ip_addr_t *addr); 00338 #define netconn_gethostbyname_addrtype(name, addr, dns_addrtype) netconn_gethostbyname(name, addr) 00339 #endif /* LWIP_IPV4 && LWIP_IPV6 */ 00340 #endif /* LWIP_DNS */ 00341 00342 #define netconn_err(conn) ((conn)->last_err) 00343 #define netconn_recv_bufsize(conn) ((conn)->recv_bufsize) 00344 00345 /** Set the blocking status of netconn calls (@todo: write/send is missing) */ 00346 #define netconn_set_nonblocking(conn, val) do { if(val) { \ 00347 (conn)->flags |= NETCONN_FLAG_NON_BLOCKING; \ 00348 } else { \ 00349 (conn)->flags &= ~ NETCONN_FLAG_NON_BLOCKING; }} while(0) 00350 /** Get the blocking status of netconn calls (@todo: write/send is missing) */ 00351 #define netconn_is_nonblocking(conn) (((conn)->flags & NETCONN_FLAG_NON_BLOCKING) != 0) 00352 00353 #if LWIP_IPV6 00354 /** @ingroup netconn_common 00355 * TCP: Set the IPv6 ONLY status of netconn calls (see NETCONN_FLAG_IPV6_V6ONLY) 00356 */ 00357 #define netconn_set_ipv6only(conn, val) do { if(val) { \ 00358 (conn)->flags |= NETCONN_FLAG_IPV6_V6ONLY; \ 00359 } else { \ 00360 (conn)->flags &= ~ NETCONN_FLAG_IPV6_V6ONLY; }} while(0) 00361 /** @ingroup netconn_common 00362 * TCP: Get the IPv6 ONLY status of netconn calls (see NETCONN_FLAG_IPV6_V6ONLY) 00363 */ 00364 #define netconn_get_ipv6only(conn) (((conn)->flags & NETCONN_FLAG_IPV6_V6ONLY) != 0) 00365 #endif /* LWIP_IPV6 */ 00366 00367 #if LWIP_SO_SNDTIMEO 00368 /** Set the send timeout in milliseconds */ 00369 #define netconn_set_sendtimeout(conn, timeout) ((conn)->send_timeout = (timeout)) 00370 /** Get the send timeout in milliseconds */ 00371 #define netconn_get_sendtimeout(conn) ((conn)->send_timeout) 00372 #endif /* LWIP_SO_SNDTIMEO */ 00373 #if LWIP_SO_RCVTIMEO 00374 /** Set the receive timeout in milliseconds */ 00375 #define netconn_set_recvtimeout(conn, timeout) ((conn)->recv_timeout = (timeout)) 00376 /** Get the receive timeout in milliseconds */ 00377 #define netconn_get_recvtimeout(conn) ((conn)->recv_timeout) 00378 #endif /* LWIP_SO_RCVTIMEO */ 00379 #if LWIP_SO_RCVBUF 00380 /** Set the receive buffer in bytes */ 00381 #define netconn_set_recvbufsize(conn, recvbufsize) ((conn)->recv_bufsize = (recvbufsize)) 00382 /** Get the receive buffer in bytes */ 00383 #define netconn_get_recvbufsize(conn) ((conn)->recv_bufsize) 00384 #endif /* LWIP_SO_RCVBUF*/ 00385 00386 #if LWIP_NETCONN_SEM_PER_THREAD 00387 void netconn_thread_init(void); 00388 void netconn_thread_cleanup(void); 00389 #else /* LWIP_NETCONN_SEM_PER_THREAD */ 00390 #define netconn_thread_init() 00391 #define netconn_thread_cleanup() 00392 #endif /* LWIP_NETCONN_SEM_PER_THREAD */ 00393 00394 #ifdef __cplusplus 00395 } 00396 #endif 00397 00398 #endif /* LWIP_NETCONN || LWIP_SOCKET */ 00399 00400 #endif /* LWIP_HDR_API_H */
Generated on Tue Aug 9 2022 00:37:00 by
