Windows CGI интерфейс.

• Обзор
• Разбор данных HTML форм
• Вызов CGI программ
  • Командная строка
  • Метод вызова
• CGI файл данных
  • [CGI] секция
  • [Accept] секция
  • [System] секция
  • [Extra Headers] секция
  • [Form Literal] секция
  • [Form External] секция
  • [Form Huge] секция
  • [Form File] секция
• Пример разбора формы
• Возврат результатов

Обзор

Большое количество World Wide Web приложений основано на использовании внешних программ, управляемых Web сервером. Использование данных программ позволяет строить Web приложения с динамически обновляемой информацией, хранящейся в базах данных или генерирующейся в зависимости от бизнес-правил решаемых задач. Для связи между Web сервером и вызываемыми программами широко используется Common Gateway Interface (CGI), имеющий реализации как для Windows-ориентированных программ, так и для приложений, функционирующих в среде Unix. Данный документ описывает Windows-модификацию интерфейса CG, иначе называемую Windows CGI интерфейсом.

Разбор данных HTML-форм

Windows CGI требует, чтобы Web сервер декодировал данные из HTML форм, если они переданы при помощи POST метода запроса. Он не требует от сервера декодирования параметров, если они переданы в качестве строки запроса ("query string"), являющейся частью URL.

Существует два способа, которыми данные из форм могут быть переданы серверу броузером:

URL-Encoded

Это наиболее используемый формат данных, передаваемых из форм. Содержимое полей формы выделяются из формы и передаются согласно спецификации HTML 1.0, а затем собираются в одну строку, где отделяются друг от друга символом амперсанда. Тип содержания сообщения устанавливается броузером в application/x-www-form-urlencoded.

Multipart Form Data

Данный формат разработан для эффективной загрузки файлов на сервер с использованием форм. Содержимое полей формы передается как многостраничное MIME сообщение. Каждое поле содержится в одной странице. Тип содержания, устанавливается броузером в multipart/form-data.

"Грамотные" серверы должны уметь обрабатывать оба типа данных из форм.

Вызов CGI программ

Сервер использует функцию CreateProcess() для вызова CGI программ. Сервер синхронизируется с CGI программой, поскольку он должен определить момент завершения CGI программы. Это достигается использованием функции Win32 WaitForSingleObject(), ожидающей получения сигнала завершения CGI программы.

Командная строка

Сервер должен вызывать CGI программу выполняя функцию CreateProcess() с командной строкой следующего формата:

   WinCGI-exe cgi-data-file

WinCGI-exe

Полный путь к исполняемой CGI программе. Сервер не зависит от "текущего каталога" или переменной окружения PATH. Примите к сведению, что "исполняемая" не обязательно означает .EXE файл. Это может быть документ, ассоциирующийся с реально исполняемой программой, описанной в WIN.INI или System Registry.

cgi-data-file

Полный путь к CGI файлу данных.

Метод вызова

Сервер использует CreateProcess() для запуска процесса, не имеющего главного окна. Вызванный процесс не будет отображаться каким либо образом на мониторе сервера.

Некоторые сервера поддерживают режим отладки CGI программ и скриптов, что позволяет серверу запускать CGI программу как обычный процесс с созданием главного окна и отображением информации на мониторе сервера. Данный способ весьма удобен на стадии отладки CGI программ.

CGI файл данных

Сервер передает данные CGI программам через Windows "private profile" afqk, в формате "параметр-значение" (windows INI файл). CGI программа может прочитать данный файл и получит все данные, передаваемые ей из формы, а также автоматически генерируемые броузером данные.

CGI файл данных состоит из следующих секций:

• [CGI]
• [Accept]
• [System]
• [Extra Headers]
• [Form Literal]
• [Form External]
• [Form Huge]
• [Form File]

Секция [CGI]

Данная секция содержит большинство специфических CGI параметров (тип доступа, тип запроса, дополнительные заголовки, определенные в других секциях и т.п.). Каждое значение представлено в виде символьной строки. Если значение является пустой строкой, значит данный параметр был опущен. Список параметров данной секции представлен ниже:

Request Protocol

Название и модификация информационного протокола, использованного для передачи данного запроса. Формат: протокол/модификация. Пример: "HTTP/1.0".

Request Method

Метод, который использовался для данного запроса. Для HTTP это "GET", "HEAD", "POST" и т.д.

Executable Path

Логический путь к исполняемой CGI программе, необходимый для ссылки CGI программе на саму себя.

Logical Path

Запрос также может указывать к ресурсам, необходимым для выполнения данного запроса. Данный параметр содержит путь в том виде, который был получен сервером без мэпирования его на физический путь на диске.

Physical Path

Если запрос содержит информацию о логическом пути, сервер преобразует его к физическому пути (например, к пути к файлу на диске) доступа согласно синтаксическим правилам операционной системы.

Query String

Информация, размещающаяся после ? в URL вызываемой CGI программы. Сервер оставляет эту информацию без изменений в том виде, в котором она была помещена в URL.

Request Range

Byte-range спецификация получаемая вместе с запросом (если есть). Смотри текущий Internet Draft (или RFC), описывающий расширение HTTP для получения более полной информации. Сервер должен поддерживать работу CGI программ в byte-ranging.

Referer

URL документа, содержащего ссылку на данную CGI программу. Надо заметить, что некоторые броузеры закрывают данную возможность и не дают ее использовать.

From

E-mail адрес пользователя броузера. Надо заметить, что данный параметр присутствует с спецификации HTTP, но не используется большинством броузером из соображений секретности.

User Agent

Строка, описывающая программное обеспечение броузера. Не генерируется большинством броузеров.

Content Type

Данный параметр содержит MIME-тип данных, посланных клиентом вместе с полями из формы, если эти данные были посланы. Формат: type/subtype.

Content Length

Для запросов, с которыми посланы дополнительные данные в это поле заносится длина посланных данных в байтах.

Content File

Для запросов, содержащих дополнительные данные, посланные пользователем, этот параметр содержит имя файла, в которое WEB-сервер записывает эти данные. В дальнейшем, пользовательская программа может считать эти данные. Параметр содержит полный путь к файлу данных.

Server Software

Название и версия серверного программного обеспечения, обработавшего запрос и вызвавшего CGI-программу. Формат: name/version.

Server Name

Сетевое имя сервера или псевдоним, необходимый для ссылающихся на себя URL Этот параметр (в комбинации с параметром ServerPort) может быть использован для вычисления полного URL к серверу.

Server Port

Номер порта, по которому работает сервер.

Server Admin

E-mail адрес администратора сервера. Данный параметр необходим для генерации сообщений об ошибках и отправки данных сообщений администратору сервера или для генерации форм с URL "mailto:".

CGI Version

Remote Host

Сетевое имя хоста клиента, если доступно. Данный параметр может быть использован для опознавание клиента.

Remote Address

Сетевой (IP) адрес клиента. Данный параметр может быть использован для проверки пользователя если отсутствует сетевое имя.

Authentication Method

Если используется защищенный вызов CGI программы, это протокол-зависимый метод аутентификации, используемый для аутентификации пользователя.

Authentication Realm

Если используется защищенный вызов CGI программы, это протокол-зависимый сервис, используемый для аутентификации пользователя. Список пользователей для полученного вида сервиса проверяется для аутентификации пользователя.

Authenticated Username

Если используется защищенный вызов CGI программы, это имя пользователя, которое клиент использует для аутентификации при доступе к CGI-программе.

Секция [Accept]

Данная секция содержит типы данных, посылаемых клиентом, найденные в заголовке запроса в виде

Accept: type/subtype {parameters}

Если данные параметры присутствуют (например, "q=0.100") , они передаются как значения параметра Accept. Для каждого типа передаваемых данных заводится свой параметр Accept.

Секция [System]

Данная секция содержит параметры, специфические для Windows реализации CGI:

GMT Offset

Количество секунд, которое необходимо добавить к времени по Гринвичу для вычисления локального времени клиента.

Debug Mode

Данный параметр имеет значение "Yes" если включен режим "CGI/script tracing" на сервере.

Output File

Полный путь к файлу, в который необходимо поместить данные, отсылаемые сервером клиенту после завершения работы программы.

Content File

Полный путь к файл у в котором содержится дополнительная информация, поступающая вместе с запросом.

Секция [Extra Headers]

Данная секция содержит "дополнительные" заголовки, которые включены в запрос в виде "параметр=значение". Сервер должен раскодировать как параметр, так и его значение прежде чем они будут помещены в файл данных CGI.

Секция [Form Literal]

Если запрос от клиента пришел в виде HTTP POST из HTML формы (с типом содержимого application/x-www-form-urlencoded или multipart/form-data), то сервер раскодирует данные из формы и поместит их в секцию [Form Literal].

Для URL-кодированных данных формы, строка передаваемых параметров выглядит как "параметр=значение&параметр=значение&...", где значения находятся в url-кодированном формате. Сервер разделяет "параметр=значение" по символу '&', затем разделяет собственно "параметр" и "значение", декодирует "значение" и помещает результат в виде "параметр=раскодированное_значение" в секцию [Form Literal].

Для многостраничных данных строка данных представляется в многостраничном MIME формате, где каждое поле представлено как отдельная часть (файл). Сервер декодирует имена и значение каждой части и размещает их в формате "параметр=значение" в секции [Form Literal].

Если форма содержит какие-либо элементы SELECT MULTIPLE, то будет создано несколько строк с вида "параметр=значение" с одинаковым именем "параметра". В этом случае генерирует нормальную строку "параметр=значение" для первого встречающегося элемента, а каждый следующий представляет в виде "параметр_X=значение", где "X" - увеличивающийся счетчик.

Секция [Form External]

Если размер декодированной строки превышает 254 символа или декодированная строка содержит управляющие символы, такие, как перевод строки, возврат каретки, двойные кавычки и т.д., то сервер помещает данное значение в отдельный временный файл, а в секцию [Form External] помещает строку в виде:

  параметр=путь длина 

где путь - это полный путь и имя временного файла, содержащего декодированное значение параметра, а длина - длина в байтах этого файла.

Секция [Form Huge]

Если общая длина строки с кодированными параметрами превышает 65,535 байт, то сервер не выполняет декодирование, а оставляет данный в Content File, а в секцию [Form Huge] помещает строки в виде:

  параметр=смещение длина

где смещение - это смещение от начала Content File по которому находится требуемый параметр, а длина - длина в байтах значения выбранного параметра. Вы можете использовать смещение для выполнения поиска начала значения выбранного вами параметра и использовать длину для чтения значения выбранного параметра. Не забывайте, что если параметр закодирован, то вам необходимо раскодировать его перед использованием.

Секция [Form File]

Если запрос пришел в виде multipart/form-data, то он может содержать один или несколько загруженных с клиента файлов. В этом случае каждый загруженный файл размещается в специальном временном файле, а в секции [Form File] строки имеют тот же формат, что и секции [Form External]. каждая строка параметра в этом случае выглядит так:

  параметр=[полный_путь_к_файлу] длина тип ссылка [имя_файла]

где полный_путь_к_файлу - это путь к временному файлу, содержащему загруженный файл, длина - длина в байтах загруженного файла, тип - тип  MIME загруженного файла, ссылка - способ кодировки загруженного файла и имя_файла - исходное название загруженного файла. Использование квадратных скобок обязательно, поскольку имя файла и путь могут содержать символы пробела.

Пример декодированных значений формы

В данном примере форма содержит небольшое поле, SELECT MULTIPLE с 2-мя небольшими секциями, поле длиной 300 символов, поле, содержащее специальные символы и поле длиной 230KB.

[Form Literal]
smallfield=123 Main St. #122
multiple=first selection
multiple_1=second selection

[Form External]
field300chars=C:\TEMP\HS19AF6C.000 300
fieldwithlinebreaks=C:\TEMP\HS19AF6C.001 43

[Form Huge]
field230K=C:\TEMP\HS19AF6C.002 276920

Обработка результата

CGI программа возвращает результат работы, отвечающий (явно или неявно) целям запроса. Сервер кодирует результат работы в соответствии со стандартом HTTP и использует HTTP для отправки результата клиенту. Это означает, что сервер добавляет необходимый HTTP заголовки в сообщение, формируемое CGI программой.

Результат работы CGI программы состоит из двух частей: заголовка и тела сообщения. Заголовок состоит из одной или более строк текста, отделенных от тела пустой строкой. Тело сообщения содержит данные, представленные в MIME формате, указанном в заголовке.

Сервер не изменяет тело документа, что означает, что сервер передает сформированный CGI программой ответ "как он есть".T

Специальные строки заголовка

Сервер распознает следующие строки заголовка в выходном потоке:

Content-Type:

Указывает на MIME тип тела сообщения. Значение этого параметра должно быть в формате type/subtype.

URI: <value> (value enclosed in angle brackets)

Данное значение указывает на полный URL или ссылку на локальный файл, сообщение из которого будет возвращено клиенту в теле сообщения. Если значение является локальным файлом, сервер отсылает его как результат запроса, как будто клиент воспользовался методом GET при генерации запроса. Если значение является полным URL, то сервер возвращает сообщение "401 redirect" для обеспечения прямой загрузки указанного объекта.

Location:

То же самое, что и URI, но данная форма сейчас не используется. Параметр value НЕ должен быть взят в угловые скобки.

Другие заголовки

Другие заголовки передаются клиенту в том виде, в котором они представлены.

Прямой возврат

Сервер позволяет конечному приложению осуществлять прямой возврат результата запроса клиенту. Это осуществляется посредством включение в заголовок возвращаемого сообщения его информационного протокола. Это позволяет CGI программам формировать непосредственный ответ клиенту с указанием HTTP заголовка без предварительной обработки его сервером..

Сервер анализирует результат запроса, помещаемый CGI программой в выходной файл (Output File), и, если первая строка "HTTP/1.0", он предполагает, что сообщение содержит полный HTTP ответ и отсылает его клиенту без упаковки.