Contiki 2.6

psock.h

Go to the documentation of this file.
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 /** @} */