lib/liblwip/include/lwip/api.h

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