core/net/tcpip.h

   1 /**
   2  * \addtogroup uip
   3  * @{
   4  */
   5
   6 /**
   7  * \defgroup tcpip The Contiki/uIP interface
   8  * @{
   9  *
  10  * TCP/IP support in Contiki is implemented using the uIP TCP/IP
  11  * stack. For sending and receiving data, Contiki uses the functions
  12  * provided by the uIP module, but Contiki adds a set of functions for
  13  * connection management. The connection management functions make
  14  * sure that the uIP TCP/IP connections are connected to the correct
  15  * process.
  16  *
  17  * Contiki also includes an optional protosocket library that provides
  18  * an API similar to the BSD socket API.
  19  *
  20  * \sa \ref uip "The uIP TCP/IP stack"
  21  * \sa \ref psock "Protosockets library"
  22  *
  23  */
  24
  25 /**
  26  * \file
  27  *          Header for the Contiki/uIP interface.
  28  * \author  Adam Dunkels <adam@sics.se>
  29  * \author  Mathilde Durvy <mdurvy@cisco.com> (IPv6 related code)
  30  * \author  Julien Abeille <jabeille@cisco.com> (IPv6 related code)
  31  */
  32
  33 /*
  34  * Copyright (c) 2004, Swedish Institute of Computer Science.
  35  * All rights reserved.
  36  *
  37  * Redistribution and use in source and binary forms, with or without
  38  * modification, are permitted provided that the following conditions
  39  * are met:
  40  * 1. Redistributions of source code must retain the above copyright
  41  *    notice, this list of conditions and the following disclaimer.
  42  * 2. Redistributions in binary form must reproduce the above copyright
  43  *    notice, this list of conditions and the following disclaimer in the
  44  *    documentation and/or other materials provided with the distribution.
  45  * 3. Neither the name of the Institute nor the names of its contributors
  46  *    may be used to endorse or promote products derived from this software
  47  *    without specific prior written permission.
  48  *
  49  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  50  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  51  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  52  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  53  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  54  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  55  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  56  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  57  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  58  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  59  * SUCH DAMAGE.
  60  *
  61  * This file is part of the Contiki operating system.
  62  *
  63  * Author: Adam Dunkels <adam@sics.se>
  64  *
  65  * $Id: tcpip.h,v 1.16 2010/02/05 12:43:37 nifi Exp $
  66  */
  67 #ifndef __TCPIP_H__
  68 #define __TCPIP_H__
  69
  70 #include "contiki.h"
  71
  72 struct uip_conn;
  73
  74 struct tcpip_uipstate {
  75   struct process *p;
  76   void *state;
  77 };
  78
  79 #define UIP_APPCALL tcpip_uipcall
  80 #define UIP_UDP_APPCALL tcpip_uipcall
  81 #define UIP_ICMP6_APPCALL tcpip_icmp6_call
  82
  83 /*#define UIP_APPSTATE_SIZE sizeof(struct tcpip_uipstate)*/
  84
  85 typedef struct tcpip_uipstate uip_udp_appstate_t;
  86 typedef struct tcpip_uipstate uip_tcp_appstate_t;
  87 typedef struct tcpip_uipstate uip_icmp6_appstate_t;
  88 #include "net/uip.h"
  89 void tcpip_uipcall(void);
  90
  91 /**
  92  * \name TCP functions
  93  * @{
  94  */
  95
  96 /**
  97  * Attach a TCP connection to the current process
  98  *
  99  * This function attaches the current process to a TCP
 100  * connection. Each TCP connection must be attached to a process in
 101  * order for the process to be able to receive and send
 102  * data. Additionally, this function can add a pointer with connection
 103  * state to the connection.
 104  *
 105  * \param conn A pointer to the TCP connection.
 106  *
 107  * \param appstate An opaque pointer that will be passed to the
 108  * process whenever an event occurs on the connection.
 109  *
 110  */
 111 CCIF void tcp_attach(struct uip_conn *conn,
 112                      void *appstate);
 113 #define tcp_markconn(conn, appstate) tcp_attach(conn, appstate)
 114
 115 /**
 116  * Open a TCP port.
 117  *
 118  * This function opens a TCP port for listening. When a TCP connection
 119  * request occurs for the port, the process will be sent a tcpip_event
 120  * with the new connection request.
 121  *
 122  * \note Port numbers must always be given in network byte order. The
 123  * functions HTONS() and htons() can be used to convert port numbers
 124  * from host byte order to network byte order.
 125  *
 126  * \param port The port number in network byte order.
 127  *
 128  */
 129 CCIF void tcp_listen(u16_t port);
 130
 131 /**
 132  * Close a listening TCP port.
 133  *
 134  * This function closes a listening TCP port.
 135  *
 136  * \note Port numbers must always be given in network byte order. The
 137  * functions HTONS() and htons() can be used to convert port numbers
 138  * from host byte order to network byte order.
 139  *
 140  * \param port The port number in network byte order.
 141  *
 142  */
 143 CCIF void tcp_unlisten(u16_t port);
 144
 145 /**
 146  * Open a TCP connection to the specified IP address and port.
 147  *
 148  * This function opens a TCP connection to the specified port at the
 149  * host specified with an IP address. Additionally, an opaque pointer
 150  * can be attached to the connection. This pointer will be sent
 151  * together with uIP events to the process.
 152  *
 153  * \note The port number must be provided in network byte order so a
 154  * conversion with HTONS() usually is necessary.
 155  *
 156  * \note This function will only create the connection. The connection
 157  * is not opened directly. uIP will try to open the connection the
 158  * next time the uIP stack is scheduled by Contiki.
 159  *
 160  * \param ripaddr Pointer to the IP address of the remote host.
 161  * \param port Port number in network byte order.
 162  * \param appstate Pointer to application defined data.
 163  *
 164  * \return A pointer to the newly created connection, or NULL if
 165  * memory could not be allocated for the connection.
 166  *
 167  */
 168 CCIF struct uip_conn *tcp_connect(uip_ipaddr_t *ripaddr, u16_t port,
 169                                   void *appstate);
 170
 171 /**
 172  * Cause a specified TCP connection to be polled.
 173  *
 174  * This function causes uIP to poll the specified TCP connection. The
 175  * function is used when the application has data that is to be sent
 176  * immediately and do not wish to wait for the periodic uIP polling
 177  * mechanism.
 178  *
 179  * \param conn A pointer to the TCP connection that should be polled.
 180  *
 181  */
 182 void tcpip_poll_tcp(struct uip_conn *conn);
 183
 184 /** @} */
 185
 186 /**
 187  * \name UDP functions
 188  * @{
 189  */
 190
 191 struct uip_udp_conn;
 192 /**
 193  * Attach the current process to a UDP connection
 194  *
 195  * This function attaches the current process to a UDP
 196  * connection. Each UDP connection must have a process attached to it
 197  * in order for the process to be able to receive and send data over
 198  * the connection. Additionally, this function can add a pointer with
 199  * connection state to the connection.
 200  *
 201  * \param conn A pointer to the UDP connection.
 202  *
 203  * \param appstate An opaque pointer that will be passed to the
 204  * process whenever an event occurs on the connection.
 205  *
 206  */
 207 void udp_attach(struct uip_udp_conn *conn,
 208                 void *appstate);
 209 #define udp_markconn(conn, appstate) udp_attach(conn, appstate)
 210
 211 /**
 212  * Create a new UDP connection.
 213  *
 214  * This function creates a new UDP connection with the specified
 215  * remote endpoint.
 216  *
 217  * \note The port number must be provided in network byte order so a
 218  * conversion with HTONS() usually is necessary.
 219  *
 220  * \sa udp_bind()
 221  *
 222  * \param ripaddr Pointer to the IP address of the remote host.
 223  * \param port Port number in network byte order.
 224  * \param appstate Pointer to application defined data.
 225  *
 226  * \return A pointer to the newly created connection, or NULL if
 227  * memory could not be allocated for the connection.
 228  */
 229 CCIF struct uip_udp_conn *udp_new(const uip_ipaddr_t *ripaddr, u16_t port,
 230                                   void *appstate);
 231
 232 /**
 233  * Create a new UDP broadcast connection.
 234  *
 235  * This function creates a new (link-local) broadcast UDP connection
 236  * to a specified port.
 237  *
 238  * \param port Port number in network byte order.
 239  * \param appstate Pointer to application defined data.
 240  *
 241  * \return A pointer to the newly created connection, or NULL if
 242  * memory could not be allocated for the connection.
 243  */
 244 struct uip_udp_conn *udp_broadcast_new(u16_t port, void *appstate);
 245
 246 /**
 247  * Bind a UDP connection to a local port.
 248  *
 249  * This function binds a UDP connection to a specified local port.
 250  *
 251  * When a connection is created with udp_new(), it gets a local port
 252  * number assigned automatically. If the application needs to bind the
 253  * connection to a specified local port, this function should be used.
 254  *
 255  * \note The port number must be provided in network byte order so a
 256  * conversion with HTONS() usually is necessary.
 257  *
 258  * \param conn A pointer to the UDP connection that is to be bound.
 259  * \param port The port number in network byte order to which to bind
 260  * the connection.
 261  */
 262 #define udp_bind(conn, port) uip_udp_bind(conn, port)
 263
 264 /**
 265  * Cause a specified UDP connection to be polled.
 266  *
 267  * This function causes uIP to poll the specified UDP connection. The
 268  * function is used when the application has data that is to be sent
 269  * immediately and do not wish to wait for the periodic uIP polling
 270  * mechanism.
 271  *
 272  * \param conn A pointer to the UDP connection that should be polled.
 273  *
 274  */
 275 CCIF void tcpip_poll_udp(struct uip_udp_conn *conn);
 276
 277 /** @} */
 278
 279 /**
 280  * \name ICMPv6 functions
 281  * @{
 282  */
 283
 284 #if UIP_CONF_ICMP6
 285
 286 /**
 287  * The ICMP6 event.
 288  *
 289  * This event is posted to a process whenever a uIP ICMP event has occurred.
 290  */
 291 CCIF extern process_event_t tcpip_icmp6_event;
 292
 293 /**
 294  * \brief register an ICMPv6 callback
 295  * \return 0 if success, 1 if failure (one application already registered)
 296  *
 297  * This function just registers a process to be polled when
 298  * an ICMPv6 message is received.
 299  * If no application registers, some ICMPv6 packets will be
 300  * processed by the "kernel" as usual (NS, NA, RS, RA, Echo request),
 301  * others will be dropped.
 302  * If an application registers here, it will be polled with a
 303  * process_post_synch every time an ICMPv6 packet is received.
 304  */
 305 u8_t icmp6_new(void *appstate);
 306
 307 /**
 308  * This function is called at reception of an ICMPv6 packet
 309  * If an application registered as an ICMPv6 listener (with
 310  * icmp6_new), it will be called through a process_post_synch()
 311  */
 312 void tcpip_icmp6_call(u8_t type);
 313 #endif /*UIP_CONF_ICMP6*/
 314
 315 /** @} */
 316 /**
 317  * The uIP event.
 318  *
 319  * This event is posted to a process whenever a uIP event has occurred.
 320  */
 321 CCIF extern process_event_t tcpip_event;
 322
 323 /**
 324  * \name TCP/IP packet processing
 325  * @{
 326  */
 327
 328 /**
 329  * \brief      Deliver an incoming packet to the TCP/IP stack
 330  *
 331  *             This function is called by network device drivers to
 332  *             deliver an incoming packet to the TCP/IP stack. The
 333  *             incoming packet must be present in the uip_buf buffer,
 334  *             and the length of the packet must be in the global
 335  *             uip_len variable.
 336  */
 337 CCIF void tcpip_input(void);
 338
 339 /**
 340  * \brief Output packet to layer 2
 341  * The eventual parameter is the MAC address of the destination.
 342  */
 343 #if UIP_CONF_IPV6
 344 u8_t tcpip_output(uip_lladdr_t *);
 345 void tcpip_set_outputfunc(u8_t (* f)(uip_lladdr_t *));
 346 #else
 347 u8_t tcpip_output(void);
 348 void tcpip_set_outputfunc(u8_t (* f)(void));
 349 #endif
 350
 351 /**
 352  * \brief This function does address resolution and then calls tcpip_output
 353  */
 354 #if UIP_CONF_IPV6
 355 void tcpip_ipv6_output(void);
 356 #endif
 357
 358 /**
 359  * \brief Is forwarding generally enabled?
 360  */
 361 extern unsigned char tcpip_do_forwarding;
 362
 363 /*
 364  * Are we at the moment forwarding the contents of uip_buf[]?
 365  */
 366 extern unsigned char tcpip_is_forwarding;
 367
 368
 369 #define tcpip_set_forwarding(forwarding) tcpip_do_forwarding = (forwarding)
 370
 371 /** @} */
 372
 373 PROCESS_NAME(tcpip_process);
 374
 375 #endif /* __TCPIP_H__ */
 376
 377 /** @} */
 378 /** @} */