psock.h

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 uIP TCP/IP stack
00030  *
00031  * Author: Adam Dunkels <adam@sics.se>
00032  *
00033  * $Id: psock.h,v 1.3 2006/06/12 08:00:30 adam Exp $
00034  */
00035 
00036 /**
00037  * \defgroup psock Protosockets library
00038  * @{
00039  *
00040  * The protosocket library provides an interface to the uIP stack that is
00041  * similar to the traditional BSD socket interface. Unlike programs
00042  * written for the ordinary uIP event-driven interface, programs
00043  * written with the protosocket library are executed in a sequential
00044  * fashion and does not have to be implemented as explicit state
00045  * machines.
00046  *
00047  * Protosockets only work with TCP connections.
00048  *
00049  * The protosocket library uses \ref pt protothreads to provide
00050  * sequential control flow. This makes the protosockets lightweight in
00051  * terms of memory, but also means that protosockets inherits the
00052  * functional limitations of protothreads. Each protosocket lives only
00053  * within a single function. Automatic variables (stack variables) are
00054  * not retained across a protosocket library function call.
00055  *
00056  * \note Because the protosocket library uses protothreads, local
00057  * variables will not always be saved across a call to a protosocket
00058  * library function. It is therefore advised that local variables are
00059  * used with extreme care.
00060  *
00061  * The protosocket library provides functions for sending data without
00062  * having to deal with retransmissions and acknowledgements, as well
00063  * as functions for reading data without having to deal with data
00064  * being split across more than one TCP segment.
00065  *
00066  * Because each protosocket runs as a protothread, the protosocket has to be
00067  * started with a call to PSOCK_BEGIN() at the start of the function
00068  * in which the protosocket is used. Similarly, the protosocket protothread can
00069  * be terminated by a call to PSOCK_EXIT().
00070  *
00071  */
00072 
00073 /**
00074  * \file
00075  * Protosocket library header file
00076  * \author
00077  * Adam Dunkels <adam@sics.se>
00078  *
00079  */
00080 
00081 #ifndef __PSOCK_H__
00082 #define __PSOCK_H__
00083 
00084 #include "uipopt.h"
00085 #include "pt.h"
00086 
00087  /*
00088  * The structure that holds the state of a buffer.
00089  *
00090  * This structure holds the state of a uIP buffer. The structure has
00091  * no user-visible elements, but is used through the functions
00092  * provided by the library.
00093  *
00094  */
00095 struct psock_buf {
00096   u8_t *ptr;
00097   unsigned short left;
00098 };
00099 
00100 /**
00101  * The representation of a protosocket.
00102  *
00103  * The protosocket structrure is an opaque structure with no user-visible
00104  * elements.
00105  */
00106 struct psock {
00107   struct pt pt, psockpt; /* Protothreads - one that's using the psock
00108                 functions, and one that runs inside the
00109                 psock functions. */
00110   const u8_t *sendptr;   /* Pointer to the next data to be sent. */
00111   u8_t *readptr;         /* Pointer to the next data to be read. */
00112   
00113   char *bufptr;          /* Pointer to the buffer used for buffering
00114                 incoming data. */
00115   
00116   u16_t sendlen;         /* The number of bytes left to be sent. */
00117   u16_t readlen;         /* The number of bytes left to be read. */
00118 
00119   struct psock_buf buf;  /* The structure holding the state of the
00120                 input buffer. */
00121   unsigned int bufsize;  /* The size of the input buffer. */
00122   
00123   unsigned char state;   /* The state of the protosocket. */
00124 };
00125 
00126 void psock_init(struct psock *psock, char *buffer, unsigned int buffersize);
00127 /**
00128  * Initialize a protosocket.
00129  *
00130  * This macro initializes a protosocket and must be called before the
00131  * protosocket is used. The initialization also specifies the input buffer
00132  * for the protosocket.
00133  *
00134  * \param psock (struct psock *) A pointer to the protosocket to be
00135  * initialized
00136  *
00137  * \param buffer (char *) A pointer to the input buffer for the
00138  * protosocket.
00139  *
00140  * \param buffersize (unsigned int) The size of the input buffer.
00141  *
00142  * \hideinitializer
00143  */
00144 #define PSOCK_INIT(psock, buffer, buffersize) \
00145   psock_init(psock, buffer, buffersize)
00146 
00147 /**
00148  * Start the protosocket protothread in a function.
00149  *
00150  * This macro starts the protothread associated with the protosocket and
00151  * must come before other protosocket calls in the function it is used.
00152  *
00153  * \param psock (struct psock *) A pointer to the protosocket to be
00154  * started.
00155  *
00156  * \hideinitializer
00157  */
00158 #define PSOCK_BEGIN(psock) PT_BEGIN(&((psock)->pt))
00159 
00160 PT_THREAD(psock_send(struct psock *psock, const char *buf, unsigned int len));
00161 /**
00162  * Send data.
00163  *
00164  * This macro sends data over a protosocket. The protosocket protothread blocks
00165  * until all data has been sent and is known to have been received by
00166  * the remote end of the TCP connection.
00167  *
00168  * \param psock (struct psock *) A pointer to the protosocket over which
00169  * data is to be sent.
00170  *
00171  * \param data (char *) A pointer to the data that is to be sent.
00172  *
00173  * \param datalen (unsigned int) The length of the data that is to be
00174  * sent.
00175  *
00176  * \hideinitializer
00177  */
00178 #define PSOCK_SEND(psock, data, datalen)        \
00179     PT_WAIT_THREAD(&((psock)->pt), psock_send(psock, data, datalen))
00180 
00181 /**
00182  * \brief      Send a null-terminated string.
00183  * \param psock Pointer to the protosocket.
00184  * \param str  The string to be sent.
00185  *
00186  *             This function sends a null-terminated string over the
00187  *             protosocket.
00188  *
00189  * \hideinitializer
00190  */
00191 #define PSOCK_SEND_STR(psock, str)              \
00192     PT_WAIT_THREAD(&((psock)->pt), psock_send(psock, str, strlen(str)))
00193 
00194 PT_THREAD(psock_generator_send(struct psock *psock,
00195                 unsigned short (*f)(void *), void *arg));
00196 
00197 /**
00198  * \brief      Generate data with a function and send it
00199  * \param psock Pointer to the protosocket.
00200  * \param generator Pointer to the generator function
00201  * \param arg   Argument to the generator function
00202  *
00203  *             This function generates data and sends it over the
00204  *             protosocket. This can be used to dynamically generate
00205  *             data for a transmission, instead of generating the data
00206  *             in a buffer beforehand. This function reduces the need for
00207  *             buffer memory. The generator function is implemented by
00208  *             the application, and a pointer to the function is given
00209  *             as an argument with the call to PSOCK_GENERATOR_SEND().
00210  *
00211  *             The generator function should place the generated data
00212  *             directly in the uip_appdata buffer, and return the
00213  *             length of the generated data. The generator function is
00214  *             called by the protosocket layer when the data first is
00215  *             sent, and once for every retransmission that is needed.
00216  *
00217  * \hideinitializer
00218  */
00219 #define PSOCK_GENERATOR_SEND(psock, generator, arg)     \
00220     PT_WAIT_THREAD(&((psock)->pt),                  \
00221            psock_generator_send(psock, generator, arg))
00222 
00223 
00224 /**
00225  * Close a protosocket.
00226  *
00227  * This macro closes a protosocket and can only be called from within the
00228  * protothread in which the protosocket lives.
00229  *
00230  * \param psock (struct psock *) A pointer to the protosocket that is to
00231  * be closed.
00232  *
00233  * \hideinitializer
00234  */
00235 #define PSOCK_CLOSE(psock) uip_close()
00236 
00237 PT_THREAD(psock_readbuf_len(struct psock *psock, u16_t len));
00238 /**
00239  * Read data until the buffer is full.
00240  *
00241  * This macro will block waiting for data and read the data into the
00242  * input buffer specified with the call to PSOCK_INIT(). Data is read
00243  * until the buffer is full..
00244  *
00245  * \param psock (struct psock *) A pointer to the protosocket from which
00246  * data should be read.
00247  *
00248  * \hideinitializer
00249  */
00250 /*
00251 #define PSOCK_READBUF(psock)                \
00252   PT_WAIT_THREAD(&((psock)->pt), psock_readbuf_len(psock, 1))
00253 */
00254 
00255 
00256 /**
00257  * Read data until at least len bytes have been read.
00258  *
00259  * This macro will block waiting for data and read the data into the
00260  * input buffer specified with the call to PSOCK_INIT(). Data is read
00261  * until the buffer is full or len bytes have been read.
00262  *
00263  * \param psock (struct psock *) A pointer to the protosocket from which
00264  * data should be read.
00265  * \param len (uint16_t) The minimum number of bytes to read.
00266  *
00267  * \hideinitializer
00268  */
00269 #define PSOCK_READBUF_LEN(psock, len)           \
00270   PT_WAIT_THREAD(&((psock)->pt), psock_readbuf_len(psock, len))
00271 
00272 PT_THREAD(psock_readto(struct psock *psock, unsigned char c));
00273 /**
00274  * Read data up to a specified character.
00275  *
00276  * This macro will block waiting for data and read the data into the
00277  * input buffer specified with the call to PSOCK_INIT(). Data is only
00278  * read until the specified character appears in the data stream.
00279  *
00280  * \param psock (struct psock *) A pointer to the protosocket from which
00281  * data should be read.
00282  *
00283  * \param c (char) The character at which to stop reading.
00284  *
00285  * \hideinitializer
00286  */
00287 #define PSOCK_READTO(psock, c)              \
00288   PT_WAIT_THREAD(&((psock)->pt), psock_readto(psock, c))
00289 
00290 /**
00291  * The length of the data that was previously read.
00292  *
00293  * This macro returns the length of the data that was previously read
00294  * using PSOCK_READTO() or PSOCK_READ().
00295  *
00296  * \param psock (struct psock *) A pointer to the protosocket holding the data.
00297  *
00298  * \hideinitializer
00299  */
00300 #define PSOCK_DATALEN(psock) psock_datalen(psock)
00301 
00302 u16_t psock_datalen(struct psock *psock);
00303 
00304 /**
00305  * Exit the protosocket's protothread.
00306  *
00307  * This macro terminates the protothread of the protosocket and should
00308  * almost always be used in conjunction with PSOCK_CLOSE().
00309  *
00310  * \sa PSOCK_CLOSE_EXIT()
00311  *
00312  * \param psock (struct psock *) A pointer to the protosocket.
00313  *
00314  * \hideinitializer
00315  */
00316 #define PSOCK_EXIT(psock) PT_EXIT(&((psock)->pt))
00317 
00318 /**
00319  * Close a protosocket and exit the protosocket's protothread.
00320  *
00321  * This macro closes a protosocket and exits the protosocket's protothread.
00322  *
00323  * \param psock (struct psock *) A pointer to the protosocket.
00324  *
00325  * \hideinitializer
00326  */
00327 #define PSOCK_CLOSE_EXIT(psock)     \
00328   do {                      \
00329     PSOCK_CLOSE(psock);         \
00330     PSOCK_EXIT(psock);          \
00331   } while(0)
00332 
00333 /**
00334  * Declare the end of a protosocket's protothread.
00335  *
00336  * This macro is used for declaring that the protosocket's protothread
00337  * ends. It must always be used together with a matching PSOCK_BEGIN()
00338  * macro.
00339  *
00340  * \param psock (struct psock *) A pointer to the protosocket.
00341  *
00342  * \hideinitializer
00343  */
00344 #define PSOCK_END(psock) PT_END(&((psock)->pt))
00345 
00346 char psock_newdata(struct psock *s);
00347 
00348 /**
00349  * Check if new data has arrived on a protosocket.
00350  *
00351  * This macro is used in conjunction with the PSOCK_WAIT_UNTIL()
00352  * macro to check if data has arrived on a protosocket.
00353  *
00354  * \param psock (struct psock *) A pointer to the protosocket.
00355  *
00356  * \hideinitializer
00357  */
00358 #define PSOCK_NEWDATA(psock) psock_newdata(psock)
00359 
00360 /**
00361  * Wait until a condition is true.
00362  *
00363  * This macro blocks the protothread until the specified condition is
00364  * true. The macro PSOCK_NEWDATA() can be used to check if new data
00365  * arrives when the protosocket is waiting.
00366  *
00367  * Typically, this macro is used as follows:
00368  *
00369  \code
00370  PT_THREAD(thread(struct psock *s, struct timer *t))
00371  {
00372    PSOCK_BEGIN(s);
00373 
00374    PSOCK_WAIT_UNTIL(s, PSOCK_NEWDATA(s) || timer_expired(t));
00375    
00376    if(PSOCK_NEWDATA(s)) {
00377      PSOCK_READTO(s, '\n');
00378    } else {
00379      handle_timed_out(s);
00380    }
00381    
00382    PSOCK_END(s);
00383  }
00384  \endcode
00385  *
00386  * \param psock (struct psock *) A pointer to the protosocket.
00387  * \param condition The condition to wait for.
00388  *
00389  * \hideinitializer
00390  */
00391 #define PSOCK_WAIT_UNTIL(psock, condition)    \
00392   PT_WAIT_UNTIL(&((psock)->pt), (condition));
00393 
00394 #define PSOCK_WAIT_THREAD(psock, condition)   \
00395   PT_WAIT_THREAD(&((psock)->pt), (condition))
00396 
00397 #endif /* __PSOCK_H__ */
00398 
00399 /** @} */