uIP 1.0: uip/psock.h Source 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 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(struct psock *psock));
+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 #define PSOCK_READBUF(psock)                            \
+00251   PT_WAIT_THREAD(&((psock)->pt), psock_readbuf(psock))
+00252 
+00253 PT_THREAD(psock_readto(struct psock *psock, unsigned char c));
+00254 /**
+00255  * Read data up to a specified character.
+00256  *
+00257  * This macro will block waiting for data and read the data into the
+00258  * input buffer specified with the call to PSOCK_INIT(). Data is only
+00259  * read until the specifieed character appears in the data stream.
+00260  *
+00261  * \param psock (struct psock *) A pointer to the protosocket from which
+00262  * data should be read.
+00263  *
+00264  * \param c (char) The character at which to stop reading.
+00265  *
+00266  * \hideinitializer
+00267  */
+00268 #define PSOCK_READTO(psock, c)                          \
+00269   PT_WAIT_THREAD(&((psock)->pt), psock_readto(psock, c))
+00270 
+00271 /**
+00272  * The length of the data that was previously read.
+00273  *
+00274  * This macro returns the length of the data that was previously read
+00275  * using PSOCK_READTO() or PSOCK_READ().
+00276  *
+00277  * \param psock (struct psock *) A pointer to the protosocket holding the data.
+00278  *
+00279  * \hideinitializer
+00280  */
+00281 #define PSOCK_DATALEN(psock) psock_datalen(psock)
+00282 
+00283 u16_t psock_datalen(struct psock *psock);
+00284 
+00285 /**
+00286  * Exit the protosocket's protothread.
+00287  *
+00288  * This macro terminates the protothread of the protosocket and should
+00289  * almost always be used in conjunction with PSOCK_CLOSE().
+00290  *
+00291  * \sa PSOCK_CLOSE_EXIT()
+00292  *
+00293  * \param psock (struct psock *) A pointer to the protosocket.
+00294  *
+00295  * \hideinitializer
+00296  */
+00297 #define PSOCK_EXIT(psock) PT_EXIT(&((psock)->pt))
+00298 
+00299 /**
+00300  * Close a protosocket and exit the protosocket's protothread.
+00301  *
+00302  * This macro closes a protosocket and exits the protosocket's protothread.
+00303  *
+00304  * \param psock (struct psock *) A pointer to the protosocket.
+00305  *
+00306  * \hideinitializer
+00307  */
+00308 #define PSOCK_CLOSE_EXIT(psock)         \
+00309   do {                                          \
+00310     PSOCK_CLOSE(psock);                 \
+00311     PSOCK_EXIT(psock);                  \
+00312   } while(0)
+00313 
+00314 /**
+00315  * Declare the end of a protosocket's protothread.
+00316  *
+00317  * This macro is used for declaring that the protosocket's protothread
+00318  * ends. It must always be used together with a matching PSOCK_BEGIN()
+00319  * macro.
+00320  *
+00321  * \param psock (struct psock *) A pointer to the protosocket.
+00322  *
+00323  * \hideinitializer
+00324  */
+00325 #define PSOCK_END(psock) PT_END(&((psock)->pt))
+00326 
+00327 char psock_newdata(struct psock *s);
+00328 
+00329 /**
+00330  * Check if new data has arrived on a protosocket.
+00331  *
+00332  * This macro is used in conjunction with the PSOCK_WAIT_UNTIL()
+00333  * macro to check if data has arrived on a protosocket.
+00334  *
+00335  * \param psock (struct psock *) A pointer to the protosocket.
+00336  *
+00337  * \hideinitializer
+00338  */
+00339 #define PSOCK_NEWDATA(psock) psock_newdata(psock)
+00340 
+00341 /**
+00342  * Wait until a condition is true.
+00343  *
+00344  * This macro blocks the protothread until the specified condition is
+00345  * true. The macro PSOCK_NEWDATA() can be used to check if new data
+00346  * arrives when the protosocket is waiting.
+00347  *
+00348  * Typically, this macro is used as follows:
+00349  *
+00350  \code
+00351  PT_THREAD(thread(struct psock *s, struct timer *t))
+00352  {
+00353    PSOCK_BEGIN(s);
+00354 
+00355    PSOCK_WAIT_UNTIL(s, PSOCK_NEWADATA(s) || timer_expired(t));
+00356    
+00357    if(PSOCK_NEWDATA(s)) {
+00358      PSOCK_READTO(s, '\n');
+00359    } else {
+00360      handle_timed_out(s);
+00361    }
+00362    
+00363    PSOCK_END(s);
+00364  }
+00365  \endcode
+00366  *
+00367  * \param psock (struct psock *) A pointer to the protosocket.
+00368  * \param condition The condition to wait for.
+00369  *
+00370  * \hideinitializer
+00371  */
+00372 #define PSOCK_WAIT_UNTIL(psock, condition)    \
+00373   PT_WAIT_UNTIL(&((psock)->pt), (condition));
+00374 
+00375 #define PSOCK_WAIT_THREAD(psock, condition)   \
+00376   PT_WAIT_THREAD(&((psock)->pt), (condition))
+00377 
+00378 #endif /* __PSOCK_H__ */
+00379 
+00380 /** @} */
+