Dependents:   SimpleLCDClock readCard2Twitter_http AnalogClock_StepperMotor_NTP ServoCamV1

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers api.h Source File

api.h

00001 /*
00002  * Copyright (c) 2001-2004 Swedish Institute of Computer Science.
00003  * All rights reserved. 
00004  * 
00005  * Redistribution and use in source and binary forms, with or without modification, 
00006  * are permitted provided that the following conditions are met:
00007  *
00008  * 1. Redistributions of source code must retain the above copyright notice,
00009  *    this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright notice,
00011  *    this list of conditions and the following disclaimer in the documentation
00012  *    and/or other materials provided with the distribution.
00013  * 3. The name of the author may not be used to endorse or promote products
00014  *    derived from this software without specific prior written permission. 
00015  *
00016  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 
00017  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
00018  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
00019  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
00020  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
00021  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
00022  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
00023  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
00024  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
00025  * OF SUCH DAMAGE.
00026  *
00027  * This file is part of the lwIP TCP/IP stack.
00028  * 
00029  * Author: Adam Dunkels <adam@sics.se>
00030  *
00031  */
00032 #ifndef __LWIP_API_H__
00033 #define __LWIP_API_H__
00034 
00035 #include "lwip/opt.h"
00036 
00037 #if LWIP_NETCONN /* don't build if not configured for use in lwipopts.h */
00038 
00039 #include <stddef.h> /* for size_t */
00040 
00041 #include "lwip/netbuf.h"
00042 #include "lwip/sys.h"
00043 #include "lwip/ip_addr.h"
00044 #include "lwip/err.h"
00045 
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 
00050 /* Throughout this file, IP addresses and port numbers are expected to be in
00051  * the same byte order as in the corresponding pcb.
00052  */
00053 
00054 /* Flags for netconn_write (u8_t) */
00055 #define NETCONN_NOFLAG    0x00
00056 #define NETCONN_NOCOPY    0x00 /* Only for source code compatibility */
00057 #define NETCONN_COPY      0x01
00058 #define NETCONN_MORE      0x02
00059 #define NETCONN_DONTBLOCK 0x04
00060 
00061 /* Flags for struct netconn.flags (u8_t) */
00062 /** TCP: when data passed to netconn_write doesn't fit into the send buffer,
00063     this temporarily stores whether to wake up the original application task
00064     if data couldn't be sent in the first try. */
00065 #define NETCONN_FLAG_WRITE_DELAYED            0x01
00066 /** Should this netconn avoid blocking? */
00067 #define NETCONN_FLAG_NON_BLOCKING             0x02
00068 /** Was the last connect action a non-blocking one? */
00069 #define NETCONN_FLAG_IN_NONBLOCKING_CONNECT   0x04
00070 /** If this is set, a TCP netconn must call netconn_recved() to update
00071     the TCP receive window (done automatically if not set). */
00072 #define NETCONN_FLAG_NO_AUTO_RECVED           0x08
00073 /** If a nonblocking write has been rejected before, poll_tcp needs to
00074     check if the netconn is writable again */
00075 #define NETCONN_FLAG_CHECK_WRITESPACE         0x10
00076 
00077 
00078 /* Helpers to process several netconn_types by the same code */
00079 #define NETCONNTYPE_GROUP(t)    (t&0xF0)
00080 #define NETCONNTYPE_DATAGRAM(t) (t&0xE0)
00081 
00082 /** Protocol family and type of the netconn */
00083 enum netconn_type {
00084   NETCONN_INVALID    = 0,
00085   /* NETCONN_TCP Group */
00086   NETCONN_TCP        = 0x10,
00087   /* NETCONN_UDP Group */
00088   NETCONN_UDP        = 0x20,
00089   NETCONN_UDPLITE    = 0x21,
00090   NETCONN_UDPNOCHKSUM= 0x22,
00091   /* NETCONN_RAW Group */
00092   NETCONN_RAW        = 0x40
00093 };
00094 
00095 /** Current state of the netconn. Non-TCP netconns are always
00096  * in state NETCONN_NONE! */
00097 enum netconn_state {
00098   NETCONN_NONE,
00099   NETCONN_WRITE,
00100   NETCONN_LISTEN,
00101   NETCONN_CONNECT,
00102   NETCONN_CLOSE
00103 };
00104 
00105 /** Use to inform the callback function about changes */
00106 enum netconn_evt {
00107   NETCONN_EVT_RCVPLUS,
00108   NETCONN_EVT_RCVMINUS,
00109   NETCONN_EVT_SENDPLUS,
00110   NETCONN_EVT_SENDMINUS,
00111   NETCONN_EVT_ERROR
00112 };
00113 
00114 #if LWIP_IGMP
00115 /** Used for netconn_join_leave_group() */
00116 enum netconn_igmp {
00117   NETCONN_JOIN,
00118   NETCONN_LEAVE
00119 };
00120 #endif /* LWIP_IGMP */
00121 
00122 /* forward-declare some structs to avoid to include their headers */
00123 struct ip_pcb;
00124 struct tcp_pcb;
00125 struct udp_pcb;
00126 struct raw_pcb;
00127 struct netconn;
00128 struct api_msg_msg;
00129 
00130 /** A callback prototype to inform about events for a netconn */
00131 typedef void (* netconn_callback)(struct netconn *, enum netconn_evt, u16_t len);
00132 
00133 /** A netconn descriptor */
00134 struct netconn {
00135   /** type of the netconn (TCP, UDP or RAW) */
00136   enum netconn_type type;
00137   /** current state of the netconn */
00138   enum netconn_state state;
00139   /** the lwIP internal protocol control block */
00140   union {
00141     struct ip_pcb  *ip;
00142     struct tcp_pcb *tcp;
00143     struct udp_pcb *udp;
00144     struct raw_pcb *raw;
00145   } pcb;
00146   /** the last error this netconn had */
00147   err_t last_err;
00148   /** sem that is used to synchroneously execute functions in the core context */
00149   sys_sem_t op_completed;
00150   /** mbox where received packets are stored until they are fetched
00151       by the netconn application thread (can grow quite big) */
00152   sys_mbox_t recvmbox;
00153   /** mbox where new connections are stored until processed
00154       by the application thread */
00155   sys_mbox_t acceptmbox;
00156   /** only used for socket layer */
00157 #if LWIP_SOCKET
00158   int socket;
00159 #endif /* LWIP_SOCKET */
00160 #if LWIP_SO_RCVTIMEO
00161   /** timeout to wait for new data to be received
00162       (or connections to arrive for listening netconns) */
00163   int recv_timeout;
00164 #endif /* LWIP_SO_RCVTIMEO */
00165 #if LWIP_SO_RCVBUF
00166   /** maximum amount of bytes queued in recvmbox
00167       not used for TCP: adjust TCP_WND instead! */
00168   int recv_bufsize;
00169 #endif /* LWIP_SO_RCVBUF */
00170   /** number of bytes currently in recvmbox to be received,
00171       tested against recv_bufsize to limit bytes on recvmbox
00172       for UDP and RAW
00173       @todo: should only be necessary with LWIP_SO_RCVBUF==1 */
00174   s16_t recv_avail;
00175   /** flags holding more netconn-internal state, see NETCONN_FLAG_* defines */
00176   u8_t flags;
00177 #if LWIP_TCP
00178   /** TCP: when data passed to netconn_write doesn't fit into the send buffer,
00179       this temporarily stores how much is already sent. */
00180   size_t write_offset;
00181   /** TCP: when data passed to netconn_write doesn't fit into the send buffer,
00182       this temporarily stores the message.
00183       Also used during connect and close. */
00184   struct api_msg_msg *current_msg;
00185 #endif /* LWIP_TCP */
00186   /** A callback function that is informed about events for this netconn */
00187   netconn_callback callback;
00188 };
00189 
00190 /** Register an Network connection event */
00191 #define API_EVENT(c,e,l) if (c->callback) {         \
00192                            (*c->callback)(c, e, l); \
00193                          }
00194 
00195 /** Set conn->last_err to err but don't overwrite fatal errors */
00196 #define NETCONN_SET_SAFE_ERR(conn, err) do { \
00197   SYS_ARCH_DECL_PROTECT(lev); \
00198   SYS_ARCH_PROTECT(lev); \
00199   if (!ERR_IS_FATAL((conn)->last_err)) { \
00200     (conn)->last_err = err; \
00201   } \
00202   SYS_ARCH_UNPROTECT(lev); \
00203 } while(0);
00204 
00205 /* Network connection functions: */
00206 #define netconn_new(t)                  netconn_new_with_proto_and_callback(t, 0, NULL)
00207 #define netconn_new_with_callback(t, c) netconn_new_with_proto_and_callback(t, 0, c)
00208 struct
00209 netconn *netconn_new_with_proto_and_callback(enum netconn_type t, u8_t proto,
00210                                              netconn_callback callback);
00211 err_t   netconn_delete(struct netconn *conn);
00212 /** Get the type of a netconn (as enum netconn_type). */
00213 #define netconn_type(conn) (conn->type)
00214 
00215 err_t   netconn_getaddr(struct netconn *conn, ip_addr_t *addr,
00216                         u16_t *port, u8_t local);
00217 #define netconn_peer(c,i,p) netconn_getaddr(c,i,p,0)
00218 #define netconn_addr(c,i,p) netconn_getaddr(c,i,p,1)
00219 
00220 err_t   netconn_bind(struct netconn *conn, ip_addr_t *addr, u16_t port);
00221 err_t   netconn_connect(struct netconn *conn, ip_addr_t *addr, u16_t port);
00222 err_t   netconn_disconnect (struct netconn *conn);
00223 err_t   netconn_listen_with_backlog(struct netconn *conn, u8_t backlog);
00224 #define netconn_listen(conn) netconn_listen_with_backlog(conn, TCP_DEFAULT_LISTEN_BACKLOG)
00225 err_t   netconn_accept(struct netconn *conn, struct netconn **new_conn);
00226 err_t   netconn_recv(struct netconn *conn, struct netbuf **new_buf);
00227 err_t   netconn_recv_tcp_pbuf(struct netconn *conn, struct pbuf **new_buf);
00228 void    netconn_recved(struct netconn *conn, u32_t length);
00229 err_t   netconn_sendto(struct netconn *conn, struct netbuf *buf,
00230                        ip_addr_t *addr, u16_t port);
00231 err_t   netconn_send(struct netconn *conn, struct netbuf *buf);
00232 err_t   netconn_write(struct netconn *conn, const void *dataptr, size_t size,
00233                       u8_t apiflags);
00234 err_t   netconn_close(struct netconn *conn);
00235 
00236 #if LWIP_IGMP
00237 err_t   netconn_join_leave_group(struct netconn *conn, ip_addr_t *multiaddr,
00238                                  ip_addr_t *netif_addr, enum netconn_igmp join_or_leave);
00239 #endif /* LWIP_IGMP */
00240 #if LWIP_DNS
00241 err_t   netconn_gethostbyname(const char *name, ip_addr_t *addr);
00242 #endif /* LWIP_DNS */
00243 
00244 #define netconn_err(conn)               ((conn)->last_err)
00245 #define netconn_recv_bufsize(conn)      ((conn)->recv_bufsize)
00246 
00247 /** Set the blocking status of netconn calls (@todo: write/send is missing) */
00248 #define netconn_set_nonblocking(conn, val)  do { if(val) { \
00249   (conn)->flags |= NETCONN_FLAG_NON_BLOCKING; \
00250 } else { \
00251   (conn)->flags &= ~ NETCONN_FLAG_NON_BLOCKING; }} while(0)
00252 /** Get the blocking status of netconn calls (@todo: write/send is missing) */
00253 #define netconn_is_nonblocking(conn)        (((conn)->flags & NETCONN_FLAG_NON_BLOCKING) != 0)
00254 
00255 /** TCP: Set the no-auto-recved status of netconn calls (see NETCONN_FLAG_NO_AUTO_RECVED) */
00256 #define netconn_set_noautorecved(conn, val)  do { if(val) { \
00257   (conn)->flags |= NETCONN_FLAG_NO_AUTO_RECVED; \
00258 } else { \
00259   (conn)->flags &= ~ NETCONN_FLAG_NO_AUTO_RECVED; }} while(0)
00260 /** TCP: Get the no-auto-recved status of netconn calls (see NETCONN_FLAG_NO_AUTO_RECVED) */
00261 #define netconn_get_noautorecved(conn)        (((conn)->flags & NETCONN_FLAG_NO_AUTO_RECVED) != 0)
00262 
00263 #if LWIP_SO_RCVTIMEO
00264 /** Set the receive timeout in miliseconds */
00265 #define netconn_set_recvtimeout(conn, timeout)      ((conn)->recv_timeout = (timeout))
00266 /** Get the receive timeout in miliseconds */
00267 #define netconn_get_recvtimeout(conn)               ((conn)->recv_timeout)
00268 #endif /* LWIP_SO_RCVTIMEO */
00269 #if LWIP_SO_RCVBUF
00270 /** Set the receive buffer in bytes */
00271 #define netconn_set_recvbufsize(conn, recvbufsize)  ((conn)->recv_bufsize = (recvbufsize))
00272 /** Get the receive buffer in bytes */
00273 #define netconn_get_recvbufsize(conn)               ((conn)->recv_bufsize)
00274 #endif /* LWIP_SO_RCVBUF*/
00275 
00276 #ifdef __cplusplus
00277 }
00278 #endif
00279 
00280 #endif /* LWIP_NETCONN */
00281 
00282 #endif /* __LWIP_API_H__ */