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