Contiki 2.6
|
00001 /* 00002 * Copyright (c) 2004, Swedish Institute of Computer Science. 00003 * All rights reserved. 00004 * 00005 * Redistribution and use in source and binary forms, with or without 00006 * modification, are permitted provided that the following conditions 00007 * are met: 00008 * 1. Redistributions of source code must retain the above copyright 00009 * notice, this list of conditions and the following disclaimer. 00010 * 2. Redistributions in binary form must reproduce the above copyright 00011 * notice, this list of conditions and the following disclaimer in the 00012 * documentation and/or other materials provided with the distribution. 00013 * 3. Neither the name of the Institute nor the names of its contributors 00014 * may be used to endorse or promote products derived from this software 00015 * without specific prior written permission. 00016 * 00017 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 00018 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 00019 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 00020 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 00021 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00022 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 00023 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 00024 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 00025 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 00026 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 00027 * SUCH DAMAGE. 00028 * 00029 * This file is part of the Contiki operating system. 00030 * 00031 * Author: Adam Dunkels <adam@sics.se> 00032 * 00033 * $Id: psock.h,v 1.8 2010/06/15 14:19:22 nifi Exp $ 00034 */ 00035 00036 /** 00037 * \addtogroup uip 00038 * @{ 00039 */ 00040 00041 /** 00042 * \defgroup psock Protosockets library 00043 * @{ 00044 * 00045 * The protosocket library provides an interface to the uIP stack that is 00046 * similar to the traditional BSD socket interface. Unlike programs 00047 * written for the ordinary uIP event-driven interface, programs 00048 * written with the protosocket library are executed in a sequential 00049 * fashion and does not have to be implemented as explicit state 00050 * machines. 00051 * 00052 * Protosockets only work with TCP connections. 00053 * 00054 * The protosocket library uses \ref pt protothreads to provide 00055 * sequential control flow. This makes the protosockets lightweight in 00056 * terms of memory, but also means that protosockets inherits the 00057 * functional limitations of protothreads. Each protosocket lives only 00058 * within a single function block. Automatic variables (stack 00059 * variables) are not necessarily retained across a protosocket 00060 * library function call. 00061 * 00062 * \note Because the protosocket library uses protothreads, local variables 00063 * will not always be saved across a call to a protosocket library 00064 * function. It is therefore advised that local variables are used 00065 * with extreme care. 00066 * 00067 * The protosocket library provides functions for sending data without 00068 * having to deal with retransmissions and acknowledgements, as well 00069 * as functions for reading data without having to deal with data 00070 * being split across more than one TCP segment. 00071 * 00072 * Because each protosocket runs as a protothread, the protosocket has to be 00073 * started with a call to PSOCK_BEGIN() at the start of the function 00074 * in which the protosocket is used. Similarly, the protosocket protothread can 00075 * be terminated by a call to PSOCK_EXIT(). 00076 * 00077 */ 00078 00079 /** 00080 * \file 00081 * Protosocket library header file 00082 * \author 00083 * Adam Dunkels <adam@sics.se> 00084 * 00085 */ 00086 00087 #ifndef __PSOCK_H__ 00088 #define __PSOCK_H__ 00089 00090 #include "contiki.h" 00091 #include "contiki-lib.h" 00092 #include "contiki-net.h" 00093 00094 /* 00095 * The structure that holds the state of a buffer. 00096 * 00097 * This structure holds the state of a uIP buffer. The structure has 00098 * no user-visible elements, but is used through the functions 00099 * provided by the library. 00100 * 00101 */ 00102 struct psock_buf { 00103 uint8_t *ptr; 00104 unsigned short left; 00105 }; 00106 00107 /** 00108 * The representation of a protosocket. 00109 * 00110 * The protosocket structrure is an opaque structure with no user-visible 00111 * elements. 00112 */ 00113 struct psock { 00114 struct pt pt, psockpt; /* Protothreads - one that's using the psock 00115 functions, and one that runs inside the 00116 psock functions. */ 00117 const uint8_t *sendptr; /* Pointer to the next data to be sent. */ 00118 uint8_t *readptr; /* Pointer to the next data to be read. */ 00119 00120 uint8_t *bufptr; /* Pointer to the buffer used for buffering 00121 incoming data. */ 00122 00123 uint16_t sendlen; /* The number of bytes left to be sent. */ 00124 uint16_t readlen; /* The number of bytes left to be read. */ 00125 00126 struct psock_buf buf; /* The structure holding the state of the 00127 input buffer. */ 00128 unsigned int bufsize; /* The size of the input buffer. */ 00129 00130 unsigned char state; /* The state of the protosocket. */ 00131 }; 00132 00133 void psock_init(struct psock *psock, uint8_t *buffer, unsigned int buffersize); 00134 /** 00135 * Initialize a protosocket. 00136 * 00137 * This macro initializes a protosocket and must be called before the 00138 * protosocket is used. The initialization also specifies the input buffer 00139 * for the protosocket. 00140 * 00141 * \param psock (struct psock *) A pointer to the protosocket to be 00142 * initialized 00143 * 00144 * \param buffer (uint8_t *) A pointer to the input buffer for the 00145 * protosocket. 00146 * 00147 * \param buffersize (unsigned int) The size of the input buffer. 00148 * 00149 * \hideinitializer 00150 */ 00151 #define PSOCK_INIT(psock, buffer, buffersize) \ 00152 psock_init(psock, buffer, buffersize) 00153 00154 /** 00155 * Start the protosocket protothread in a function. 00156 * 00157 * This macro starts the protothread associated with the protosocket and 00158 * must come before other protosocket calls in the function it is used. 00159 * 00160 * \param psock (struct psock *) A pointer to the protosocket to be 00161 * started. 00162 * 00163 * \hideinitializer 00164 */ 00165 #define PSOCK_BEGIN(psock) PT_BEGIN(&((psock)->pt)) 00166 00167 PT_THREAD(psock_send(struct psock *psock, const uint8_t *buf, unsigned int len)); 00168 /** 00169 * Send data. 00170 * 00171 * This macro sends data over a protosocket. The protosocket protothread blocks 00172 * until all data has been sent and is known to have been received by 00173 * the remote end of the TCP connection. 00174 * 00175 * \param psock (struct psock *) A pointer to the protosocket over which 00176 * data is to be sent. 00177 * 00178 * \param data (uint8_t *) A pointer to the data that is to be sent. 00179 * 00180 * \param datalen (unsigned int) The length of the data that is to be 00181 * sent. 00182 * 00183 * \hideinitializer 00184 */ 00185 #define PSOCK_SEND(psock, data, datalen) \ 00186 PT_WAIT_THREAD(&((psock)->pt), psock_send(psock, data, datalen)) 00187 00188 /** 00189 * \brief Send a null-terminated string. 00190 * \param psock Pointer to the protosocket. 00191 * \param str The string to be sent. 00192 * 00193 * This function sends a null-terminated string over the 00194 * protosocket. 00195 * 00196 * \hideinitializer 00197 */ 00198 #define PSOCK_SEND_STR(psock, str) \ 00199 PT_WAIT_THREAD(&((psock)->pt), psock_send(psock, (uint8_t *)str, strlen(str))) 00200 00201 PT_THREAD(psock_generator_send(struct psock *psock, 00202 unsigned short (*f)(void *), void *arg)); 00203 00204 /** 00205 * \brief Generate data with a function and send it 00206 * \param psock Pointer to the protosocket. 00207 * \param generator Pointer to the generator function 00208 * \param arg Argument to the generator function 00209 * 00210 * This function generates data and sends it over the 00211 * protosocket. This can be used to dynamically generate 00212 * data for a transmission, instead of generating the data 00213 * in a buffer beforehand. This function reduces the need for 00214 * buffer memory. The generator function is implemented by 00215 * the application, and a pointer to the function is given 00216 * as an argument with the call to PSOCK_GENERATOR_SEND(). 00217 * 00218 * The generator function should place the generated data 00219 * directly in the uip_appdata buffer, and return the 00220 * length of the generated data. The generator function is 00221 * called by the protosocket layer when the data first is 00222 * sent, and once for every retransmission that is needed. 00223 * 00224 * \hideinitializer 00225 */ 00226 #define PSOCK_GENERATOR_SEND(psock, generator, arg) \ 00227 PT_WAIT_THREAD(&((psock)->pt), \ 00228 psock_generator_send(psock, generator, arg)) 00229 00230 00231 /** 00232 * Close a protosocket. 00233 * 00234 * This macro closes a protosocket and can only be called from within the 00235 * protothread in which the protosocket lives. 00236 * 00237 * \param psock (struct psock *) A pointer to the protosocket that is to 00238 * be closed. 00239 * 00240 * \hideinitializer 00241 */ 00242 #define PSOCK_CLOSE(psock) uip_close() 00243 00244 PT_THREAD(psock_readbuf_len(struct psock *psock, uint16_t len)); 00245 /** 00246 * Read data until the buffer is full. 00247 * 00248 * This macro will block waiting for data and read the data into the 00249 * input buffer specified with the call to PSOCK_INIT(). Data is read 00250 * until the buffer is full.. 00251 * 00252 * \param psock (struct psock *) A pointer to the protosocket from which 00253 * data should be read. 00254 * 00255 * \hideinitializer 00256 */ 00257 #define PSOCK_READBUF(psock) \ 00258 PT_WAIT_THREAD(&((psock)->pt), psock_readbuf_len(psock, 1)) 00259 00260 00261 /** 00262 * Read data until at least len bytes have been read. 00263 * 00264 * This macro will block waiting for data and read the data into the 00265 * input buffer specified with the call to PSOCK_INIT(). Data is read 00266 * until the buffer is full or len bytes have been read. 00267 * 00268 * \param psock (struct psock *) A pointer to the protosocket from which 00269 * data should be read. 00270 * \param len (uint16_t) The minimum number of bytes to read. 00271 * 00272 * \hideinitializer 00273 */ 00274 #define PSOCK_READBUF_LEN(psock, len) \ 00275 PT_WAIT_THREAD(&((psock)->pt), psock_readbuf_len(psock, len)) 00276 00277 PT_THREAD(psock_readto(struct psock *psock, unsigned char c)); 00278 /** 00279 * Read data up to a specified character. 00280 * 00281 * This macro will block waiting for data and read the data into the 00282 * input buffer specified with the call to PSOCK_INIT(). Data is only 00283 * read until the specified character appears in the data stream. 00284 * 00285 * \param psock (struct psock *) A pointer to the protosocket from which 00286 * data should be read. 00287 * 00288 * \param c (char) The character at which to stop reading. 00289 * 00290 * \hideinitializer 00291 */ 00292 #define PSOCK_READTO(psock, c) \ 00293 PT_WAIT_THREAD(&((psock)->pt), psock_readto(psock, c)) 00294 00295 /** 00296 * The length of the data that was previously read. 00297 * 00298 * This macro returns the length of the data that was previously read 00299 * using PSOCK_READTO() or PSOCK_READ(). 00300 * 00301 * \param psock (struct psock *) A pointer to the protosocket holding the data. 00302 * 00303 * \hideinitializer 00304 */ 00305 #define PSOCK_DATALEN(psock) psock_datalen(psock) 00306 00307 uint16_t psock_datalen(struct psock *psock); 00308 00309 /** 00310 * Exit the protosocket's protothread. 00311 * 00312 * This macro terminates the protothread of the protosocket and should 00313 * almost always be used in conjunction with PSOCK_CLOSE(). 00314 * 00315 * \sa PSOCK_CLOSE_EXIT() 00316 * 00317 * \param psock (struct psock *) A pointer to the protosocket. 00318 * 00319 * \hideinitializer 00320 */ 00321 #define PSOCK_EXIT(psock) PT_EXIT(&((psock)->pt)) 00322 00323 /** 00324 * Close a protosocket and exit the protosocket's protothread. 00325 * 00326 * This macro closes a protosocket and exits the protosocket's protothread. 00327 * 00328 * \param psock (struct psock *) A pointer to the protosocket. 00329 * 00330 * \hideinitializer 00331 */ 00332 #define PSOCK_CLOSE_EXIT(psock) \ 00333 do { \ 00334 PSOCK_CLOSE(psock); \ 00335 PSOCK_EXIT(psock); \ 00336 } while(0) 00337 00338 /** 00339 * Declare the end of a protosocket's protothread. 00340 * 00341 * This macro is used for declaring that the protosocket's protothread 00342 * ends. It must always be used together with a matching PSOCK_BEGIN() 00343 * macro. 00344 * 00345 * \param psock (struct psock *) A pointer to the protosocket. 00346 * 00347 * \hideinitializer 00348 */ 00349 #define PSOCK_END(psock) PT_END(&((psock)->pt)) 00350 00351 char psock_newdata(struct psock *s); 00352 00353 /** 00354 * Check if new data has arrived on a protosocket. 00355 * 00356 * This macro is used in conjunction with the PSOCK_WAIT_UNTIL() 00357 * macro to check if data has arrived on a protosocket. 00358 * 00359 * \param psock (struct psock *) A pointer to the protosocket. 00360 * 00361 * \hideinitializer 00362 */ 00363 #define PSOCK_NEWDATA(psock) psock_newdata(psock) 00364 00365 /** 00366 * Wait until a condition is true. 00367 * 00368 * This macro blocks the protothread until the specified condition is 00369 * true. The macro PSOCK_NEWDATA() can be used to check if new data 00370 * arrives when the protosocket is waiting. 00371 * 00372 * Typically, this macro is used as follows: 00373 * 00374 \code 00375 PT_THREAD(thread(struct psock *s, struct timer *t)) 00376 { 00377 PSOCK_BEGIN(s); 00378 00379 PSOCK_WAIT_UNTIL(s, PSOCK_NEWDATA(s) || timer_expired(t)); 00380 00381 if(PSOCK_NEWDATA(s)) { 00382 PSOCK_READTO(s, '\n'); 00383 } else { 00384 handle_timed_out(s); 00385 } 00386 00387 PSOCK_END(s); 00388 } 00389 \endcode 00390 * 00391 * \param psock (struct psock *) A pointer to the protosocket. 00392 * \param condition The condition to wait for. 00393 * 00394 * \hideinitializer 00395 */ 00396 #define PSOCK_WAIT_UNTIL(psock, condition) \ 00397 PT_WAIT_UNTIL(&((psock)->pt), (condition)); 00398 00399 #define PSOCK_WAIT_THREAD(psock, condition) \ 00400 PT_WAIT_THREAD(&((psock)->pt), (condition)) 00401 00402 #endif /* __PSOCK_H__ */ 00403 00404 /** @} */ 00405 /** @} */