C:/asm/STM32-ethernet/ENC28J60prj/uip-master/uip/psock.h

См. документацию.

/*
 * Copyright (c) 2004, Swedish Institute of Computer Science.
 * Все права зарезервированы. *
 * Повторное распространение, использование в исходном и двоичном виде,
 * с модификацией или без - разрешается, если выполняются следующие
 * условия:
 * 1. Распространение исходного кода должно сохранить вышеуказанную пометку
 *    копирайта, этот список условий и следующую правовую оговорку.
 * 2. Распространение исходного кода должно сохранить вышеуказанную пометку
 *    копирайта, этот список условий и следующую правовую оговорку в
 *    документации и/или других материалах, которые будут предоставлены
 *    вместе с распространяемыми материалами.
 * 3. Имя автора не может использоваться, чтобы подтвердить или продвинуть
 *    продукты, написанные с использованием этого программного обеспечения
 *    без специального на то разрешения.
 *
 * ЭТО ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ АВТОРОМ ``КАК ЕСТЬ'', БЕЗ
 * КАКОЙ-ЛИБО ЛЮБОЙ РАСШИРЕННОЙ ИЛИ ПОДРАЗУМЕВАЕМОЙ ГАРАНТИИ, ВКЛЮЧАЯ,
 * НО НЕ ОГРАНИЧИВАЯСЬ ЭТИМ, ГАРАНТИИ ВЫСОКОГО СПРОСА И ПРИГОДНОСТИ
 * ДЛЯ КОНКРЕТНОЙ ЦЕЛИ. АВТОР НИ ПРИ КАКИХ УСЛОВИЯХ НЕ ОТВЕТСТВЕНЕН
 * ЗА ЛЮБЫЕ УБЫТКИ - ПРЯМЫЕ, КОСВЕННЫЕ, СЛУЧАЙНЫЕ, СПЕЦИАЛЬНЫЕ, ОБРАЗЦОВЫЕ
 * ИЛИ ПОСЛЕДОВАТЕЛЬНЫЕ (ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ЭТИМ, ТРЕБОВАНИЯ
 * ЗАМЕНЫ ТОВАРА ИЛИ СЕРВИСА; ПОТЕРИ ИСПОЛЬЗОВАНИЯ, ДАННЫХ ИЛИ ВЫГОДЫ;
 * ИЛИ ПРЕКРАЩЕНИЕ БИЗНЕСА), ОДНАКО ВЫЗВАННЫЕ ПО ЛЮБОЙ ТЕОРИИ ОТВЕТСТВЕННОСТИ,
 * ЛИБО В КОНТРАКТЕ, ПРЯМОЙ ОТВЕТСТВЕННОСТИ, ЛИБО В НАРУШЕНИИ ЗАКОННЫХ ПРАВ
 * (ВКЛЮЧАЯ ТАК ИЛИ ИНАЧЕ НЕБРЕЖНОСТЬ), ВОЗНИКАЮЩИЕ ВСЕГДА ИЗ ИСПОЛЬЗОВАНИЯ
 * ЭТОГО ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ, ДАЖЕ ЕСЛИ БЫЛО ПРЕДУПРЕЖДЕНИЕ О ВОЗМОЖНОСТИ
 * ТАКОГО ПОВРЕЖДЕНИЯ.
 *
 * Этот файл является частью стека uIP TCP/IP.
 *
 * Author: Adam Dunkels <adam@sics.se>
 *
 * $Id: psock.h,v 1.3 2006/06/12 08:00:30 adam Exp $
 */

/**
 * \defgroup psock Библиотека protosocket-ов.
 * @{
 *
 * Библиотека protosocket-ов предоставляет интерфейс к стеку uIP, который работает
 * похоже на традиционный интерфейс сокетов BSD. В отличие от программ, написанных
 * для обычного интерфейса uIP, управляемого событиями, программы на 
 * protosocket-библиотеке выполнются последовательно и требуют явно реализованных
 * машин состояний.
 *
 * Protosocket-ы работают только с соединениями TCP.
 *
 * Protosocket-библиотека использует \ref pt protothread-ы для предоставления
 * последовательного потока выполнения. Это делате protosocket-ы нересурсоемкими
 * в плане расхода памяти, однако подразумевается, что protosocket-ы наследуют
 * фуциональные ограничения protothread-ов. Каждый protosocket живет только 
 * в пределах одной функции. Автоматические переменные (хранящиеся в стеке)
 * не сохраняются между вызовами функций protosocket-библиотеки.
 *
 * \note Поскольку protosocket-библиотека использует protothread-ы, локальные
 * переменные не всегда будут сохранены между вызовами функции 
 * protosocket-библиотеки. Так что рекомендуется использовать локальные 
 * переменные с большой осторожностью.
 *
 * Protosocket-библиотека предоставляет функции для отправки данных без
 * разборки с повторными передачами и подтверждениями, как и с функциями для
 * чтения данных с разборкой разбиения данных больше чем через 1 сегмент TCP.
 *
 * Поскольку каждый протосокет запускается как protothread, то protosocket 
 * стартует с вызова PSOCK_BEGIN() в начале функции, в которой используется
 * protosocket. Аналогично, protosocket protothread может быть прерван
 * вызовом PSOCK_EXIT().
 *
 */

/**
 * \file
 * Заголовочный файл библиотеки протосокетов
 * \author
 * Adam Dunkels <adam@sics.se>
 *
 */

#ifndef __PSOCK_H__
#define __PSOCK_H__

#include "uipopt.h"
#include "pt.h"

 /*
 * Структура, которая содержит состояние буфера.
 *
 * В этой структуре находится состояние буфера uIP. Структура не имеет
 * элементов, видимых для пользователя, но используется функциями,
 * предоставленными библиотекой.
 *
 */
struct psock_buf {
  u8_t *ptr;
  unsigned short left;
};

/**
 * Представление протосокета.
 *
 * Структура протосокета является непрозрачной, в ней нет полей,
 * которые видит пользователь.
 */
struct psock {
  struct pt pt, psockpt; /* Протосокеты используют функции psock
                             и функцию, которая работает внутри
                             функций psock. */
  const u8_t *sendptr;   /* Указатель на следующие отправляемые данные. */
  u8_t *readptr;          /* Указатель на следующие данные для чтения. */
  
  char *bufptr;          /* Указатель на буфер, используемый для буферизации
                            приходящих данных. */
  
  u16_t sendlen;         /* Количество байт, которое осталось отправить. */
  u16_t readlen;         /* Количество байт, которое осталось прочитать. */

  struct psock_buf buf;  /* Структура, которая содержит состояние входного
                             буфера. */
  unsigned int bufsize;  /* Размер входного буфера. */
  
  unsigned char state;   /* Состояние протосокета. */
};

void psock_init(struct psock *psock, char *buffer, unsigned int buffersize);
/**
 * Инициализирует протосокет.
 *
 * Этот макрос инициализирует протосокет, и должен быть вызван перед 
 * протосокета. Инициализация таке указывает входной буфер для
 * протосокета.
 *
 * \param psock (struct psock *) Указатель на протосокет, который будет
 * инициализирован.
 *
 * \param buffer (char *) Указатель на входной буфер для протосокета.
 *
 * \param buffersize (unsigned int) Размер входного буфера.
 *
 * \hideinitializer
 */
#define PSOCK_INIT(psock, buffer, buffersize) \
  psock_init(psock, buffer, buffersize)

/**
 * Запускает в фукнции протопоток протосокета.
 *
 * Этот макрос запускает протопоток, ассоциированный с протосокетом,
 * и он должен быть использован перед тем, как будет вызвана другая
 * фукнция протосокета.
 *
 * \param psock (struct psock *) Указатель на протосокет, который будет
 * запущен.
 *
 * \hideinitializer
 */
#define PSOCK_BEGIN(psock) PT_BEGIN(&((psock)->pt))

PT_THREAD(psock_send(struct psock *psock, const char *buf, unsigned int len));
/**
 * Отправление данных.
 *
 * Этот макрос посылает данные через протосокет. Протопоток протосокета
 * блокируется, пока все данные не будут отправлены, и не станет известно,
 * что данные приняты на дальнем конце соединения TCP.
 *
 * \param psock (struct psock *) A pointer to the protosocket over which
 * data is to be sent.
 *
 * \param data (char *) Указатель на протосокет, через который будут
 * отправлены данные.
 *
 * \param datalen (unsigned int) Длина отправляемых данных.
 *
 * \hideinitializer
 */
#define PSOCK_SEND(psock, data, datalen)                \
    PT_WAIT_THREAD(&((psock)->pt), psock_send(psock, data, datalen))

/**
 * \brief      Отправляет строку, завершающуюся нулем (null-terminated 
 * string).
 * \param psock Указатель на протосокет.
 * \param str  Строка для отправки.
 *
 *             Эта функция посылвает null-terminated строку через
 *             протосокет.
 *
 * \hideinitializer
 */
#define PSOCK_SEND_STR(psock, str)                      \
    PT_WAIT_THREAD(&((psock)->pt), psock_send(psock, str, strlen(str)))

PT_THREAD(psock_generator_send(struct psock *psock,
                                unsigned short (*f)(void *), void *arg));

/**
 * \brief      Генерация данных с помощью функции и отправка их
 * \param psock Указатель на протосокет.
 * \param generator Указатель на функцию генератора.
 * \param arg   Аргумент для функции генератора.
 *
 *             Эта функция генерирует данные и посылает их через
 *             протосокет. Это может использоваться для динамической
 *             генерации данных для передачи, вместо того, чтобы
 *             генерировать данные в буфере заранее. Эта функция
 *             снижает необходимость в буферной памяти. Функция
 *             генератора реализована приложением, и указатель на
 *             функцию предоставляется в аргументе, когда делается
 *             вызов PSOCK_GENERATOR_SEND().
 *
 *             Функция генератора должна поместить сгенерированные
 *             данные напрямую в буфер uip_appdata, и возвратить
 *             длину сгенерированных данных. Функция генератора
 *             вызывается слоем протосокета, когда данные посылаются
 *             первый раз, и каждый раз, когда требуется ретрансмиссия.
 *
 * \hideinitializer
 */
#define PSOCK_GENERATOR_SEND(psock, generator, arg)     \
    PT_WAIT_THREAD(&((psock)->pt),                                      \
                   psock_generator_send(psock, generator, arg))


/**
 * Закрытие протосокета.
 *
 * Этот макрос закрывает протосокет, и может быть вызван только из 
 * протопотока, в котором живет протосокет.
 *
 * \param psock (struct psock *) Указатель на протосокет, который
 * будет закрыт.
 *
 * \hideinitializer
 */
#define PSOCK_CLOSE(psock) uip_close()

PT_THREAD(psock_readbuf(struct psock *psock));
/**
 * Чтение данных, пока буфер не заполнится.
 *
 * Этот марос будет блокироватьс выполнение протопотока на ожидании
 * данных, и читать данные во входной буфер, указанный вызовом
 * PSOCK_INIT(). Дата читаются, пока буфер не заполнится.
 *
 * \param psock (struct psock *) Указатель на протосокет, из которого
 * читаются данные.
 *
 * \hideinitializer
 */
#define PSOCK_READBUF(psock)                            \
  PT_WAIT_THREAD(&((psock)->pt), psock_readbuf(psock))

PT_THREAD(psock_readto(struct psock *psock, unsigned char c));
/**
 * Читает данные, пока не попадется указанный символ.
 *
 * Этот макрос заблокирует выполнение на ожидании нужного символа, и читаемые 
 * данные будут попадать во входной буфер, указанный вызовом PSOCK_INIT(). 
 * Данные будут читаться в буфер, пока во входом потоке данных не появится
 * указанный символ.
 *
 * \param psock (struct psock *) Указатель на protosocket с которого должны
 * читаться данные.
 *
 * \param c (char) Символ, на котором должно быть остановлено чтение.
 *
 * \hideinitializer
 */
#define PSOCK_READTO(psock, c)                          \
  PT_WAIT_THREAD(&((psock)->pt), psock_readto(psock, c))

/**
 * Длина данных, котррые были прочитаны ранее.
 *
 * Этот макрос возвращает длину данных, которые были прочитаны ранее 
 * с использованием PSOCK_READTO() или PSOCK_READ().
 *
 * \param psock (struct psock *) Указатель на протосокет, содержащий
 * данные.
 *
 * \hideinitializer
 */
#define PSOCK_DATALEN(psock) psock_datalen(psock)

u16_t psock_datalen(struct psock *psock);

/**
 * Выход из протопотока протосокета.
 *
 * Этот макрос прерывает протопоток протосокета и должен почти всегда
 * использоваться в сочетании с PSOCK_CLOSE().
 *
 * \sa PSOCK_CLOSE_EXIT()
 *
 * \param psock (struct psock *) Указатель на протосокет.
 *
 * \hideinitializer
 */
#define PSOCK_EXIT(psock) PT_EXIT(&((psock)->pt))

/**
 * Закрывает протосокет и делает выход из протопотока протосокета.
 *
 * Этот макрос закрывает протосокет и делает выход из протопотока
 * протосокета.
 *
 * \param psock (struct psock *) Указатель на протосокет.
 *
 * \hideinitializer
 */
#define PSOCK_CLOSE_EXIT(psock)         \
  do {                                          \
    PSOCK_CLOSE(psock);                 \
    PSOCK_EXIT(psock);                  \
  } while(0)

/**
 * Декларирует конец протопотока протосокета.
 *
 * Этот макрос используется, чтобы декларировать, где находится
 * конец протопотока протосокета. Макрос должен всегда использоваться
 * совместно с соответствующим макросом PSOCK_BEGIN().
 *
 * \param psock (struct psock *) Указатель на протосокет.
 *
 * \hideinitializer
 */
#define PSOCK_END(psock) PT_END(&((psock)->pt))

char psock_newdata(struct psock *s);

/**
 * Проверяет - поступили ли новые данные на протосокет.
 *
 * Этот макрос используется совместно с макросом PSOCK_WAIT_UNTIL()
 * для проверки - поступили ли данные на протосокет.
 *
 * \param psock (struct psock *) Указатель на протосокет.
 *
 * \hideinitializer
 */
#define PSOCK_NEWDATA(psock) psock_newdata(psock)

/**
 * Ожидание, пока условие не станет true.
 *
 * Этот макрос блокирует протопоток, пока указанное условие не станет
 * true. Макрос PSOCK_NEWDATA() может использоваться для проверки,
 * поступили ли новые данные, когда протосокет находится в ожидании.
 *
 * Обычно этот макрос используется так:
 *
 \code
 PT_THREAD(thread(struct psock *s, struct timer *t))
 {
   PSOCK_BEGIN(s);

   PSOCK_WAIT_UNTIL(s, PSOCK_NEWADATA(s) || timer_expired(t));
   
   if(PSOCK_NEWDATA(s)) {
     PSOCK_READTO(s, '\n');
   } else {
     handle_timed_out(s);
   }
   
   PSOCK_END(s);
 }
 \endcode
 *
 * \param psock (struct psock *) Указатель на протосокет.
 * \param condition Условие, которое ждет блокировка.
 *
 * \hideinitializer
 */
#define PSOCK_WAIT_UNTIL(psock, condition)    \
  PT_WAIT_UNTIL(&((psock)->pt), (condition));

#define PSOCK_WAIT_THREAD(psock, condition)   \
  PT_WAIT_THREAD(&((psock)->pt), (condition))

#endif /* __PSOCK_H__ */

/** @} */