Contiki 2.6

tcpip.h

Go to the documentation of this file.
00001 /**
00002  * \addtogroup uip
00003  * @{
00004  */
00005 
00006 /**
00007  * \defgroup tcpip The Contiki/uIP interface
00008  * @{
00009  *
00010  * TCP/IP support in Contiki is implemented using the uIP TCP/IP
00011  * stack. For sending and receiving data, Contiki uses the functions
00012  * provided by the uIP module, but Contiki adds a set of functions for
00013  * connection management. The connection management functions make
00014  * sure that the uIP TCP/IP connections are connected to the correct
00015  * process.
00016  *
00017  * Contiki also includes an optional protosocket library that provides
00018  * an API similar to the BSD socket API.
00019  *
00020  * \sa \ref uip "The uIP TCP/IP stack"
00021  * \sa \ref psock "Protosockets library"
00022  *
00023  */
00024 
00025 /**
00026  * \file
00027  *          Header for the Contiki/uIP interface.
00028  * \author  Adam Dunkels <adam@sics.se>
00029  * \author  Mathilde Durvy <mdurvy@cisco.com> (IPv6 related code)
00030  * \author  Julien Abeille <jabeille@cisco.com> (IPv6 related code)
00031  */
00032 
00033 /*
00034  * Copyright (c) 2004, Swedish Institute of Computer Science.
00035  * All rights reserved.
00036  *
00037  * Redistribution and use in source and binary forms, with or without
00038  * modification, are permitted provided that the following conditions
00039  * are met:
00040  * 1. Redistributions of source code must retain the above copyright
00041  *    notice, this list of conditions and the following disclaimer.
00042  * 2. Redistributions in binary form must reproduce the above copyright
00043  *    notice, this list of conditions and the following disclaimer in the
00044  *    documentation and/or other materials provided with the distribution.
00045  * 3. Neither the name of the Institute nor the names of its contributors
00046  *    may be used to endorse or promote products derived from this software
00047  *    without specific prior written permission.
00048  *
00049  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00050  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00051  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00052  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00053  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00054  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00055  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00056  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00057  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00058  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00059  * SUCH DAMAGE.
00060  *
00061  * This file is part of the Contiki operating system.
00062  *
00063  * Author: Adam Dunkels <adam@sics.se>
00064  *
00065  * $Id: tcpip.h,v 1.17 2010/10/19 18:29:04 adamdunkels Exp $
00066  */
00067 #ifndef __TCPIP_H__
00068 #define __TCPIP_H__
00069 
00070 #include "contiki.h"
00071 
00072 struct uip_conn;
00073 
00074 struct tcpip_uipstate {
00075   struct process *p;
00076   void *state;
00077 };
00078 
00079 #define UIP_APPCALL tcpip_uipcall
00080 #define UIP_UDP_APPCALL tcpip_uipcall
00081 #define UIP_ICMP6_APPCALL tcpip_icmp6_call
00082 
00083 /*#define UIP_APPSTATE_SIZE sizeof(struct tcpip_uipstate)*/
00084 
00085 typedef struct tcpip_uipstate uip_udp_appstate_t;
00086 typedef struct tcpip_uipstate uip_tcp_appstate_t;
00087 typedef struct tcpip_uipstate uip_icmp6_appstate_t;
00088 #include "net/uip.h"
00089 void tcpip_uipcall(void);
00090 
00091 /**
00092  * \name TCP functions
00093  * @{
00094  */
00095 
00096 /**
00097  * Attach a TCP connection to the current process
00098  *
00099  * This function attaches the current process to a TCP
00100  * connection. Each TCP connection must be attached to a process in
00101  * order for the process to be able to receive and send
00102  * data. Additionally, this function can add a pointer with connection
00103  * state to the connection.
00104  *
00105  * \param conn A pointer to the TCP connection.
00106  *
00107  * \param appstate An opaque pointer that will be passed to the
00108  * process whenever an event occurs on the connection.
00109  *
00110  */
00111 CCIF void tcp_attach(struct uip_conn *conn,
00112                      void *appstate);
00113 #define tcp_markconn(conn, appstate) tcp_attach(conn, appstate)
00114 
00115 /**
00116  * Open a TCP port.
00117  *
00118  * This function opens a TCP port for listening. When a TCP connection
00119  * request occurs for the port, the process will be sent a tcpip_event
00120  * with the new connection request.
00121  *
00122  * \note Port numbers must always be given in network byte order. The
00123  * functions UIP_HTONS() and uip_htons() can be used to convert port numbers
00124  * from host byte order to network byte order.
00125  *
00126  * \param port The port number in network byte order.
00127  *
00128  */
00129 CCIF void tcp_listen(uint16_t port);
00130 
00131 /**
00132  * Close a listening TCP port.
00133  *
00134  * This function closes a listening TCP port.
00135  *
00136  * \note Port numbers must always be given in network byte order. The
00137  * functions UIP_HTONS() and uip_htons() can be used to convert port numbers
00138  * from host byte order to network byte order.
00139  *
00140  * \param port The port number in network byte order.
00141  *
00142  */
00143 CCIF void tcp_unlisten(uint16_t port);
00144 
00145 /**
00146  * Open a TCP connection to the specified IP address and port.
00147  *
00148  * This function opens a TCP connection to the specified port at the
00149  * host specified with an IP address. Additionally, an opaque pointer
00150  * can be attached to the connection. This pointer will be sent
00151  * together with uIP events to the process.
00152  *
00153  * \note The port number must be provided in network byte order so a
00154  * conversion with UIP_HTONS() usually is necessary.
00155  *
00156  * \note This function will only create the connection. The connection
00157  * is not opened directly. uIP will try to open the connection the
00158  * next time the uIP stack is scheduled by Contiki.
00159  *
00160  * \param ripaddr Pointer to the IP address of the remote host.
00161  * \param port Port number in network byte order.
00162  * \param appstate Pointer to application defined data.
00163  *
00164  * \return A pointer to the newly created connection, or NULL if
00165  * memory could not be allocated for the connection.
00166  *
00167  */
00168 CCIF struct uip_conn *tcp_connect(uip_ipaddr_t *ripaddr, uint16_t port,
00169                                   void *appstate);
00170 
00171 /**
00172  * Cause a specified TCP connection to be polled.
00173  *
00174  * This function causes uIP to poll the specified TCP connection. The
00175  * function is used when the application has data that is to be sent
00176  * immediately and do not wish to wait for the periodic uIP polling
00177  * mechanism.
00178  *
00179  * \param conn A pointer to the TCP connection that should be polled.
00180  *
00181  */
00182 void tcpip_poll_tcp(struct uip_conn *conn);
00183 
00184 /** @} */
00185 
00186 /**
00187  * \name UDP functions
00188  * @{
00189  */
00190 
00191 struct uip_udp_conn;
00192 /**
00193  * Attach the current process to a UDP connection
00194  *
00195  * This function attaches the current process to a UDP
00196  * connection. Each UDP connection must have a process attached to it
00197  * in order for the process to be able to receive and send data over
00198  * the connection. Additionally, this function can add a pointer with
00199  * connection state to the connection.
00200  *
00201  * \param conn A pointer to the UDP connection.
00202  *
00203  * \param appstate An opaque pointer that will be passed to the
00204  * process whenever an event occurs on the connection.
00205  *
00206  */
00207 void udp_attach(struct uip_udp_conn *conn,
00208                 void *appstate);
00209 #define udp_markconn(conn, appstate) udp_attach(conn, appstate)
00210 
00211 /**
00212  * Create a new UDP connection.
00213  *
00214  * This function creates a new UDP connection with the specified
00215  * remote endpoint.
00216  *
00217  * \note The port number must be provided in network byte order so a
00218  * conversion with UIP_HTONS() usually is necessary.
00219  *
00220  * \sa udp_bind()
00221  *
00222  * \param ripaddr Pointer to the IP address of the remote host.
00223  * \param port Port number in network byte order.
00224  * \param appstate Pointer to application defined data.
00225  *
00226  * \return A pointer to the newly created connection, or NULL if
00227  * memory could not be allocated for the connection.
00228  */
00229 CCIF struct uip_udp_conn *udp_new(const uip_ipaddr_t *ripaddr, uint16_t port,
00230                                   void *appstate);
00231 
00232 /**
00233  * Create a new UDP broadcast connection.
00234  *
00235  * This function creates a new (link-local) broadcast UDP connection
00236  * to a specified port.
00237  *
00238  * \param port Port number in network byte order.
00239  * \param appstate Pointer to application defined data.
00240  *
00241  * \return A pointer to the newly created connection, or NULL if
00242  * memory could not be allocated for the connection.
00243  */
00244 struct uip_udp_conn *udp_broadcast_new(uint16_t port, void *appstate);
00245 
00246 /**
00247  * Bind a UDP connection to a local port.
00248  *
00249  * This function binds a UDP connection to a specified local port.
00250  *
00251  * When a connection is created with udp_new(), it gets a local port
00252  * number assigned automatically. If the application needs to bind the
00253  * connection to a specified local port, this function should be used.
00254  *
00255  * \note The port number must be provided in network byte order so a
00256  * conversion with UIP_HTONS() usually is necessary.
00257  *
00258  * \param conn A pointer to the UDP connection that is to be bound.
00259  * \param port The port number in network byte order to which to bind
00260  * the connection.
00261  */
00262 #define udp_bind(conn, port) uip_udp_bind(conn, port)
00263 
00264 /**
00265  * Cause a specified UDP connection to be polled.
00266  *
00267  * This function causes uIP to poll the specified UDP connection. The
00268  * function is used when the application has data that is to be sent
00269  * immediately and do not wish to wait for the periodic uIP polling
00270  * mechanism.
00271  *
00272  * \param conn A pointer to the UDP connection that should be polled.
00273  *
00274  */
00275 CCIF void tcpip_poll_udp(struct uip_udp_conn *conn);
00276 
00277 /** @} */
00278  
00279 /**
00280  * \name ICMPv6 functions
00281  * @{
00282  */
00283 
00284 #if UIP_CONF_ICMP6
00285 
00286 /**
00287  * The ICMP6 event.
00288  *
00289  * This event is posted to a process whenever a uIP ICMP event has occurred.
00290  */
00291 CCIF extern process_event_t tcpip_icmp6_event;
00292 
00293 /**
00294  * \brief register an ICMPv6 callback
00295  * \return 0 if success, 1 if failure (one application already registered)
00296  *
00297  * This function just registers a process to be polled when
00298  * an ICMPv6 message is received.
00299  * If no application registers, some ICMPv6 packets will be
00300  * processed by the "kernel" as usual (NS, NA, RS, RA, Echo request),
00301  * others will be dropped.
00302  * If an application registers here, it will be polled with a
00303  * process_post_synch every time an ICMPv6 packet is received.
00304  */
00305 uint8_t icmp6_new(void *appstate);
00306 
00307 /**
00308  * This function is called at reception of an ICMPv6 packet
00309  * If an application registered as an ICMPv6 listener (with
00310  * icmp6_new), it will be called through a process_post_synch()
00311  */
00312 void tcpip_icmp6_call(uint8_t type);
00313 #endif /*UIP_CONF_ICMP6*/
00314 
00315 /** @} */
00316 /**
00317  * The uIP event.
00318  *
00319  * This event is posted to a process whenever a uIP event has occurred.
00320  */
00321 CCIF extern process_event_t tcpip_event;
00322 
00323 /**
00324  * \name TCP/IP packet processing
00325  * @{
00326  */
00327 
00328 /**
00329  * \brief      Deliver an incoming packet to the TCP/IP stack
00330  *
00331  *             This function is called by network device drivers to
00332  *             deliver an incoming packet to the TCP/IP stack. The
00333  *             incoming packet must be present in the uip_buf buffer,
00334  *             and the length of the packet must be in the global
00335  *             uip_len variable.
00336  */
00337 CCIF void tcpip_input(void);
00338 
00339 /**
00340  * \brief Output packet to layer 2
00341  * The eventual parameter is the MAC address of the destination.
00342  */
00343 #if UIP_CONF_IPV6
00344 uint8_t tcpip_output(uip_lladdr_t *);
00345 void tcpip_set_outputfunc(uint8_t (* f)(uip_lladdr_t *));
00346 #else
00347 uint8_t tcpip_output(void);
00348 void tcpip_set_outputfunc(uint8_t (* f)(void));
00349 #endif
00350 
00351 /**
00352  * \brief This function does address resolution and then calls tcpip_output
00353  */
00354 #if UIP_CONF_IPV6
00355 void tcpip_ipv6_output(void);
00356 #endif
00357 
00358 /**
00359  * \brief Is forwarding generally enabled?
00360  */
00361 extern unsigned char tcpip_do_forwarding;
00362 
00363 /*
00364  * Are we at the moment forwarding the contents of uip_buf[]?
00365  */
00366 extern unsigned char tcpip_is_forwarding;
00367 
00368 
00369 #define tcpip_set_forwarding(forwarding) tcpip_do_forwarding = (forwarding)
00370 
00371 /** @} */
00372 
00373 PROCESS_NAME(tcpip_process);
00374 
00375 #endif /* __TCPIP_H__ */
00376 
00377 /** @} */
00378 /** @} */