# uip/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 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 /** @} */