Contiki-NG
udp-socket.h
1 /*
2  * Copyright (c) 2012-2014, Thingsquare, http://www.thingsquare.com/.
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 copyright holder nor the names of its
14  * contributors may be used to endorse or promote products derived
15  * from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
21  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28  * OF THE POSSIBILITY OF SUCH DAMAGE.
29  *
30  */
31 
32 #ifndef UDP_SOCKET_H
33 #define UDP_SOCKET_H
34 
35 #include "net/ipv6/uip.h"
36 
37 struct udp_socket;
38 
39 /**
40  * \brief A UDP socket callback function
41  * \param c A pointer to the struct udp_socket that received the data
42  * \param ptr An opaque pointer that was specified when the UDP socket was registered with udp_socket_register()
43  * \param source_addr The IP address from which the datagram was sent
44  * \param source_port The UDP port number, in host byte order, from which the datagram was sent
45  * \param dest_addr The IP address that this datagram was sent to
46  * \param dest_port The UDP port number, in host byte order, that the datagram was sent to
47  * \param data A pointer to the data contents of the UDP datagram
48  * \param datalen The length of the data being pointed to by the data pointer
49  *
50  * Each UDP socket has a callback function that is
51  * registered as part of the call to
52  * udp_socket_register(). The callback function gets
53  * called every time a UDP packet is received.
54  */
55 typedef void (* udp_socket_input_callback_t)(struct udp_socket *c,
56  void *ptr,
57  const uip_ipaddr_t *source_addr,
58  uint16_t source_port,
59  const uip_ipaddr_t *dest_addr,
60  uint16_t dest_port,
61  const uint8_t *data,
62  uint16_t datalen);
63 
64 struct udp_socket {
65  udp_socket_input_callback_t input_callback;
66  void *ptr;
67 
68  struct process *p;
69 
70  struct uip_udp_conn *udp_conn;
71 
72 };
73 
74 /**
75  * \brief Register a UDP socket
76  * \param c A pointer to the struct udp_socket that should be registered
77  * \param ptr An opaque pointer that will be passed to callbacks
78  * \param receive_callback A function pointer to the callback function that will be called when data arrives
79  * \retval -1 The registration failed
80  * \retval 1 The registration succeeded
81  *
82  * This function registers the UDP socket with the
83  * system. A UDP socket must be registered before any data
84  * can be sent or received over the socket.
85  *
86  * The caller must allocate memory for the struct
87  * udp_socket that is to be registered.
88  *
89  * A UDP socket can begin to receive data by calling
90  * udp_socket_bind().
91  *
92  */
93 int udp_socket_register(struct udp_socket *c,
94  void *ptr,
95  udp_socket_input_callback_t receive_callback);
96 
97 /**
98  * \brief Bind a UDP socket to a local port
99  * \param c A pointer to the struct udp_socket that should be bound to a local port
100  * \param local_port The UDP port number, in host byte order, to bind the UDP socket to
101  * \retval -1 Binding the UDP socket to the local port failed
102  * \retval 1 Binding the UDP socket to the local port succeeded
103  *
104  * This function binds the UDP socket to a local port so
105  * that it will begin to receive data that arrives on the
106  * specified port. A UDP socket will receive data
107  * addressed to the specified port number on any IP
108  * address of the host.
109  *
110  * A UDP socket that is bound to a local port will use
111  * this port number as a source port in outgoing UDP
112  * messages.
113  *
114  */
115 int udp_socket_bind(struct udp_socket *c,
116  uint16_t local_port);
117 
118 /**
119  * \brief Bind a UDP socket to a remote address and port
120  * \param c A pointer to the struct udp_socket that should be connected
121  * \param remote_addr The IP address of the remote host, or NULL if the UDP socket should only be connected to a specific port
122  * \param remote_port The UDP port number, in host byte order, to which the UDP socket should be connected
123  * \retval -1 Connecting the UDP socket failed
124  * \retval 1 Connecting the UDP socket succeeded
125  *
126  * This function connects the UDP socket to a specific
127  * remote port and optional remote IP address. When a UDP
128  * socket is connected to a remote port and address, it
129  * will only receive packets that are sent from the remote
130  * port and address. When sending data over a connected
131  * UDP socket, the data will be sent to the connected
132  * remote address.
133  *
134  * A UDP socket can be connected to a remote port, but not
135  * a remote IP address, by providing a NULL parameter as
136  * the remote_addr parameter. This lets the UDP socket
137  * receive data from any IP address on the specified port.
138  *
139  */
140 int udp_socket_connect(struct udp_socket *c,
141  uip_ipaddr_t *remote_addr,
142  uint16_t remote_port);
143 /**
144  * \brief Send data on a UDP socket
145  * \param c A pointer to the struct udp_socket on which the data should be sent
146  * \param data A pointer to the data that should be sent
147  * \param datalen The length of the data to be sent
148  * \return The number of bytes sent, or -1 if an error occurred
149  *
150  * This function sends data over a UDP socket. The UDP
151  * socket must have been connected to a remote address and
152  * port with udp_socket_connect().
153  *
154  */
155 int udp_socket_send(struct udp_socket *c,
156  const void *data, uint16_t datalen);
157 
158 /**
159  * \brief Send data on a UDP socket to a specific address and port
160  * \param c A pointer to the struct udp_socket on which the data should be sent
161  * \param data A pointer to the data that should be sent
162  * \param datalen The length of the data to be sent
163  * \param addr The IP address to which the data should be sent
164  * \param port The UDP port number, in host byte order, to which the data should be sent
165  * \return The number of bytes sent, or -1 if an error occurred
166  *
167  * This function sends data over a UDP socket to a
168  * specific address and port.
169  *
170  * The UDP socket does not have to be connected to use
171  * this function.
172  *
173  */
174 int udp_socket_sendto(struct udp_socket *c,
175  const void *data, uint16_t datalen,
176  const uip_ipaddr_t *addr, uint16_t port);
177 
178 /**
179  * \brief Close a UDP socket
180  * \param c A pointer to the struct udp_socket to be closed
181  * \retval -1 If closing the UDP socket failed
182  * \retval 1 If closing the UDP socket succeeded
183  *
184  * This function closes a UDP socket that has previously
185  * been registered with udp_socket_register(). All
186  * registered UDP sockets must be closed before exiting
187  * the process that registered them, or undefined behavior
188  * may occur.
189  *
190  */
191 int udp_socket_close(struct udp_socket *c);
192 
193 #endif /* UDP_SOCKET_H */
static uip_ds6_addr_t * addr
Pointer to a nbr cache entry.
Definition: uip-nd6.c:107
Header file for the uIP TCP/IP stack.
Representation of a uIP UDP connection.
Definition: uip.h:1375