Contiki-NG
psock.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2004, Swedish Institute of Computer Science.
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  *
32  *
33  */
34
35 /**
37  * @{
38  */
39
40 /**
41  * \defgroup psock Protosockets library
42  * @{
43  *
44  * The protosocket library provides an interface to the uIP stack that is
45  * similar to the traditional BSD socket interface. Unlike programs
46  * written for the ordinary uIP event-driven interface, programs
47  * written with the protosocket library are executed in a sequential
48  * fashion and does not have to be implemented as explicit state
49  * machines.
50  *
51  * Protosockets only work with TCP connections.
52  *
53  * The protosocket library uses \ref pt protothreads to provide
54  * sequential control flow. This makes the protosockets lightweight in
55  * terms of memory, but also means that protosockets inherits the
56  * functional limitations of protothreads. Each protosocket lives only
57  * within a single function block. Automatic variables (stack
58  * variables) are not necessarily retained across a protosocket
59  * library function call.
60  *
61  * \note Because the protosocket library uses protothreads, local variables
62  * will not always be saved across a call to a protosocket library
63  * function. It is therefore advised that local variables are used
64  * with extreme care.
65  *
66  * The protosocket library provides functions for sending data without
67  * having to deal with retransmissions and acknowledgements, as well
68  * as functions for reading data without having to deal with data
69  * being split across more than one TCP segment.
70  *
71  * Because each protosocket runs as a protothread, the protosocket has to be
72  * started with a call to PSOCK_BEGIN() at the start of the function
73  * in which the protosocket is used. Similarly, the protosocket protothread can
74  * be terminated by a call to PSOCK_EXIT().
75  *
76  */
77
78 /**
79  * \file
80  * Protosocket library header file
81  * \author
83  *
84  */
85
86 #ifndef PSOCK_H_
87 #define PSOCK_H_
88
89 #include "contiki.h"
90 #include "contiki-lib.h"
91 #include "contiki-net.h"
92
93  /*
94  * The structure that holds the state of a buffer.
95  *
96  * This structure holds the state of a uIP buffer. The structure has
97  * no user-visible elements, but is used through the functions
98  * provided by the library.
99  *
100  */
101 struct psock_buf {
102  uint8_t *ptr;
103  unsigned short left;
104 };
105
106 /**
107  * The representation of a protosocket.
108  *
109  * The protosocket structure is an opaque structure with no user-visible
110  * elements.
111  */
112 struct psock {
113  struct pt pt, psockpt; /* Protothreads - one that's using the psock
114  functions, and one that runs inside the
115  psock functions. */
116  const uint8_t *sendptr; /* Pointer to the next data to be sent. */
117  uint8_t *readptr; /* Pointer to the next data to be read. */
118
119  uint8_t *bufptr; /* Pointer to the buffer used for buffering
120  incoming data. */
121
122  uint16_t sendlen; /* The number of bytes left to be sent. */
123  uint16_t readlen; /* The number of bytes left to be read. */
124
125  struct psock_buf buf; /* The structure holding the state of the
126  input buffer. */
127  unsigned int bufsize; /* The size of the input buffer. */
128
129  unsigned char state; /* The state of the protosocket. */
130 };
131
132 void psock_init(struct psock *psock, uint8_t *buffer, unsigned int buffersize);
133 /**
134  * Initialize a protosocket.
135  *
136  * This macro initializes a protosocket and must be called before the
137  * protosocket is used. The initialization also specifies the input buffer
138  * for the protosocket.
139  *
140  * \param psock (struct psock *) A pointer to the protosocket to be
141  * initialized
142  *
143  * \param buffer (uint8_t *) A pointer to the input buffer for the
144  * protosocket.
145  *
146  * \param buffersize (unsigned int) The size of the input buffer.
147  *
148  * \hideinitializer
149  */
150 #define PSOCK_INIT(psock, buffer, buffersize) \
151  psock_init(psock, buffer, buffersize)
152
153 /**
154  * Start the protosocket protothread in a function.
155  *
156  * This macro starts the protothread associated with the protosocket and
157  * must come before other protosocket calls in the function it is used.
158  *
159  * \param psock (struct psock *) A pointer to the protosocket to be
160  * started.
161  *
162  * \hideinitializer
163  */
164 #define PSOCK_BEGIN(psock) PT_BEGIN(&((psock)->pt))
165
166 PT_THREAD(psock_send(struct psock *psock, const uint8_t *buf, unsigned int len));
167 /**
168  * Send data.
169  *
170  * This macro sends data over a protosocket. The protosocket protothread blocks
171  * until all data has been sent and is known to have been received by
172  * the remote end of the TCP connection.
173  *
174  * \param psock (struct psock *) A pointer to the protosocket over which
175  * data is to be sent.
176  *
177  * \param data (uint8_t *) A pointer to the data that is to be sent.
178  *
179  * \param datalen (unsigned int) The length of the data that is to be
180  * sent.
181  *
182  * \hideinitializer
183  */
184 #define PSOCK_SEND(psock, data, datalen) \
186
187 /**
188  * \brief Send a null-terminated string.
189  * \param psock Pointer to the protosocket.
190  * \param str The string to be sent.
191  *
192  * This function sends a null-terminated string over the
193  * protosocket.
194  *
195  * \hideinitializer
196  */
197 #define PSOCK_SEND_STR(psock, str) \
198  PT_WAIT_THREAD(&((psock)->pt), psock_send(psock, (uint8_t *)str, strlen(str)))
199
201  unsigned short (*f)(void *), void *arg));
202
203 /**
204  * \brief Generate data with a function and send it
205  * \param psock Pointer to the protosocket.
206  * \param generator Pointer to the generator function
207  * \param arg Argument to the generator function
208  *
209  * This function generates data and sends it over the
210  * protosocket. This can be used to dynamically generate
211  * data for a transmission, instead of generating the data
212  * in a buffer beforehand. This function reduces the need for
213  * buffer memory. The generator function is implemented by
214  * the application, and a pointer to the function is given
215  * as an argument with the call to PSOCK_GENERATOR_SEND().
216  *
217  * The generator function should place the generated data
218  * directly in the uip_appdata buffer, and return the
219  * length of the generated data. The generator function is
220  * called by the protosocket layer when the data first is
221  * sent, and once for every retransmission that is needed.
222  *
223  * \hideinitializer
224  */
225 #define PSOCK_GENERATOR_SEND(psock, generator, arg) \
227  psock_generator_send(psock, generator, arg))
228
229
230 /**
231  * Close a protosocket.
232  *
233  * This macro closes a protosocket and can only be called from within the
234  * protothread in which the protosocket lives.
235  *
236  * \param psock (struct psock *) A pointer to the protosocket that is to
237  * be closed.
238  *
239  * \hideinitializer
240  */
241 #define PSOCK_CLOSE(psock) uip_close()
242
244 /**
245  * Read data until the buffer is full.
246  *
247  * This macro will block waiting for data and read the data into the
248  * input buffer specified with the call to PSOCK_INIT(). Data is read
249  * until the buffer is full..
250  *
251  * \param psock (struct psock *) A pointer to the protosocket from which
252  * data should be read.
253  *
254  * \hideinitializer
255  */
258
259
260 /**
261  * Read data until at least len bytes have been read.
262  *
263  * This macro will block waiting for data and read the data into the
264  * input buffer specified with the call to PSOCK_INIT(). Data is read
265  * until the buffer is full or len bytes have been read.
266  *
267  * \param psock (struct psock *) A pointer to the protosocket from which
268  * data should be read.
269  * \param len (uint16_t) The minimum number of bytes to read.
270  *
271  * \hideinitializer
272  */
275
277 /**
278  * Read data up to a specified character.
279  *
280  * This macro will block waiting for data and read the data into the
281  * input buffer specified with the call to PSOCK_INIT(). Data is only
282  * read until the specified character appears in the data stream.
283  *
284  * \param psock (struct psock *) A pointer to the protosocket from which
285  * data should be read.
286  *
287  * \param c (char) The character at which to stop reading.
288  *
289  * \hideinitializer
290  */
293
294 /**
295  * The length of the data that was previously read.
296  *
297  * This macro returns the length of the data that was previously read
299  *
300  * \param psock (struct psock *) A pointer to the protosocket holding the data.
301  *
302  * \hideinitializer
303  */
304 #define PSOCK_DATALEN(psock) psock_datalen(psock)
305
306 uint16_t psock_datalen(struct psock *psock);
307
308 /**
309  * Exit the protosocket's protothread.
310  *
311  * This macro terminates the protothread of the protosocket and should
312  * almost always be used in conjunction with PSOCK_CLOSE().
313  *
314  * \sa PSOCK_CLOSE_EXIT()
315  *
316  * \param psock (struct psock *) A pointer to the protosocket.
317  *
318  * \hideinitializer
319  */
320 #define PSOCK_EXIT(psock) PT_EXIT(&((psock)->pt))
321
322 /**
323  * Close a protosocket and exit the protosocket's protothread.
324  *
325  * This macro closes a protosocket and exits the protosocket's protothread.
326  *
327  * \param psock (struct psock *) A pointer to the protosocket.
328  *
329  * \hideinitializer
330  */
331 #define PSOCK_CLOSE_EXIT(psock) \
332  do { \
333  PSOCK_CLOSE(psock); \
334  PSOCK_EXIT(psock); \
335  } while(0)
336
337 /**
338  * Declare the end of a protosocket's protothread.
339  *
340  * This macro is used for declaring that the protosocket's protothread
341  * ends. It must always be used together with a matching PSOCK_BEGIN()
342  * macro.
343  *
344  * \param psock (struct psock *) A pointer to the protosocket.
345  *
346  * \hideinitializer
347  */
348 #define PSOCK_END(psock) PT_END(&((psock)->pt))
349
350 char psock_newdata(struct psock *s);
351
352 /**
353  * Check if new data has arrived on a protosocket.
354  *
355  * This macro is used in conjunction with the PSOCK_WAIT_UNTIL()
356  * macro to check if data has arrived on a protosocket.
357  *
358  * \param psock (struct psock *) A pointer to the protosocket.
359  *
360  * \hideinitializer
361  */
362 #define PSOCK_NEWDATA(psock) psock_newdata(psock)
363
364 /**
365  * Wait until a condition is true.
366  *
367  * This macro blocks the protothread until the specified condition is
368  * true. The macro PSOCK_NEWDATA() can be used to check if new data
369  * arrives when the protosocket is waiting.
370  *
371  * Typically, this macro is used as follows:
372  *
373  \code
375  {
376  PSOCK_BEGIN(s);
377
378  PSOCK_WAIT_UNTIL(s, PSOCK_NEWDATA(s) || timer_expired(t));
379
380  if(PSOCK_NEWDATA(s)) {
382  } else {
383  handle_timed_out(s);
384  }
385
386  PSOCK_END(s);
387  }
388  \endcode
389  *
390  * \param psock (struct psock *) A pointer to the protosocket.
391  * \param condition The condition to wait for.
392  *
393  * \hideinitializer
394  */
395 #define PSOCK_WAIT_UNTIL(psock, condition) \
396  PT_WAIT_UNTIL(&((psock)->pt), (condition));
397