[apache-rus] Russian Apache C API specs

[Alex Tutubalin/Apache-RUS team <arlexa@miracle.geol.msu.ru>]

Привет,

На http://apache.lexa.ru/notes.html#api 
выложена нулевая версия описания "Russian Apache API".
Пожелания и критика принимаются с благодарностью.
Perl API будет в общих чертах повторять C-шный

Alex
p.s. Чтобы лишний раз не бегать на WWW, вот текстовая версия
того же документа.

                               Russian Apache API
     При разработке собственных модулей бывает необходимо использовать
     функциональность, уже существующую в Russian Apache - например
     перекодировать какую-то строку из кодировки сервера в кодировку
     клиента. Естественно, можно использовать все не-static функции из
     mod_charset, но для некоторых из них гарантировано, что их интерфейс не
     будет меняться (по мере сил, естественно :)

     Russian Apache API включен в Russian Apache PL27.0 и выше. Russian
     Apache API включает в себя такие макросы, вызовы и т.п.:
        o Заголовочный файл - mod_charset.h. Расположен в
          src/modules/extra/mod_charset.h.
        o Defines:
             + RUSSIAN_APACHE - определена, если сервер собирается вместе с
               mod_charset.
             + MOD_CHARSET_MAGIC - определяет версию API. Текущая (она же -
               первая) версия имеет номер 19981025. Подразумевается, что
               более новые версии Russian Apache API включают в себя старые
               версии без изменений.
        o Вызовы функций: Все вызовы функций получают в качестве первого
          параметра текущий запрос (request_rec* r). Все они могут
          вызываться только после стадии обработки fixup т.е. в момент
          выдачи ответа клиенту в противном случае они возвращают 0 или NULL
          (в зависимости от типа возвращаемого значения) и никаких других
          действий не производят.
          Список функций:
            1. int ra_request_ok(request_rec *r); - возвращает 1, если
               mod_charset уже успешно обработал этот запрос т.е определил
               кодировку сервера и клиента. В противном случае возвращается
               0.
            2. int ra_no_of_charsets(request_rec *r); - возвращает число
               различных charsets, известных серверу.
            3. char * ra_charset_name(request_rec *r, int n); - возвращает
               имя charset номер n (считая от нуля) в виде указателя на
               zero-terminated string.
            4. char * ra_server_charset(request_rec *r); - возвращает имя
               charset сервера (т.е. кодировку в которой mod_charset
               рассчитывает получить данные от модуля/скрипта/из файла).
               Возвращаемое значение совпадает с значением CGI-переменной
               SOURCE_CHARSET.
            5. char * ra_client_charset(request_rec *r); - возвращает имя
               кодировки клиента.
            6. char *ra_str_client2server(request_rec *r, const char* str);
               - перекодирует zero-terminated строку strиз кодировки клиента
               в кодировку сервера и возвращает указатель на
               перекодированную строку. Место для новой строки аллоцируется
               в r->pool, с ней можно делать что угодно. Перекодировка
               производится "по байтам", конструкции вида %AA не
               перекодируются.
            7. char *ra_str_server2client(request_rec *r, const char* str);
               - перекодирует zero-terminated строку strиз кодировки сервера
               в кодировку клиента и возвращает указатель на
               перекодированную строку. Место для новой строки аллоцируется
               в r->pool, с ней можно делать что угодно. Перекодировка
               производится "по байтам", конструкции вида %AA не
               перекодируются.
            8. char *ra_str_client2server_esc(request_rec *r, const char*
               str); - перекодирует zero-terminated строку strиз кодировки
               клиента в кодировку сервера и возвращает указатель на
               перекодированную строку. Место для новой строки аллоцируется
               в r->pool, с ней можно делать что угодно. Эта функция
               корректно перекодирует escaped-конструкции вида %AA, причем в
               результирующей строке на их место тоже будут вставлены
               escaped-символы.
            9. char *ra_str_server2clien_esc(request_rec *r, const char*
               str); - перекодирует zero-terminated строку strиз кодировки
               сервера в кодировку клиента и возвращает указатель на
               перекодированную строку. Место для новой строки аллоцируется
               в r->pool, с ней можно делать что угодно. Эта функция
               корректно перекодирует escaped-конструкции вида %AA, причем в
               результирующей строке на их место тоже будут вставлены
               escaped-символы.
           10. void *ra_data_client2server(request_rec *r, const void* data,
               unsigned int nbytes, void **result, unsigned int *rnbytes); -
               перекодирует nbytes данных, переданных указателем data.
               Возвращает указатель на перекодированные данные, тот же
               указатель записывается в *result, в *rnbytes помещается длина
               перекодированных данных (она может быть другой в общем
               случае). Перекодировка производится из кодировки клиента в
               кодировку сервера. Перекодированные данные накапливаются во
               внутреннем буфере (r->ra_codep->recode_data) и будут потеряны
               при любом следующем вызове любой функции перекодировки).
           11. void *ra_data_server2client(request_rec *r, const void* data,
               unsigned int nbytes, void **result, unsigned int *rnbytes); -
               перекодирует nbytes данных, переданных указателем data.
               Возвращает указатель на перекодированные данные, тот же
               указатель записывается в *result, в *rnbytes помещается длина
               перекодированных данных (она может быть другой в общем
               случае). Перекодировка производится из кодировки сервера в
               кодировку клиента. Перекодированные данные накапливаются во
               внутреннем буфере (r->ra_codep->recode_data) и будут потеряны
               при любом следующем вызове любой функции перекодировки).
           12. void *ra_data_server2client_esc(request_rec *r, const void*
               data, unsigned int nbytes, void **result, unsigned int
               *rnbytes);
               void *ra_data_server2client_esc(request_rec *r, const void*
               data, unsigned int nbytes, void **result, unsigned int
               *rnbytes); - аналогично двум предшествующим функциям, но с
               корректной обработкой %AA-escapes.

                             Russian Apache Perl API
     Perl API находится в стадии разработки, но в общих чертах повторяет C
     API. Модуль для mod_perl, реализующий Perl API будет доступен после
     выхода Russian Apache PL27.0