451 lines
23 KiB
HTML
451 lines
23 KiB
HTML
<!DOCTYPE HTML PUBLIC -//W3C//DTD HTML 4.01 Transitional//EN>
|
||
<html>
|
||
<head>
|
||
<title>Http</title>
|
||
</head>
|
||
|
||
<body>
|
||
<h1>Http</h1>
|
||
|
||
<p>Клиентская часть реализации протокола HTTP/1.0.</p>
|
||
|
||
<h2><a name=СИНТАКСИС></a>СИНТАКСИС</h2>
|
||
|
||
<pre>
|
||
<strong>package</strong> <strong>require</strong> <em>http</em> ?<em>2.0</em>?
|
||
<a href=#http::config><strong>::http::config</strong></a> ?<em>options</em>?
|
||
<a href=#http::geturl_url><strong>::http::geturl</strong> <strong>url</strong></a> ?<em>options</em>?
|
||
<a href=#http::formatQuery><strong>::http::formatQuery</strong></a> <em>list</em>
|
||
<a href=#http::reset><strong>::http::reset</strong></a> <em>token</em> ?<em>why</em>?
|
||
<a href=#http::wait><strong>::http::wait</strong></a> <em>token</em>
|
||
<a href=#http::status><strong>::http::status</strong></a> <em>token</em>
|
||
<a href=#http::size><strong>::http::size</strong></a> <em>token</em>
|
||
<a href=#http::code><strong>::http::code</strong></a> <em>token</em>
|
||
<a href=#http::data><strong>::http::data</strong></a> <em>token</em>
|
||
</pre>
|
||
|
||
<h2><a name=ОПИСАНИЕ></a>ОПИСАНИЕ</h2>
|
||
|
||
<p>Пакет <strong>http</strong> обеспечивает клиентскую часть протокола
|
||
HTTP/1.0 и реализует операции GET, POST и HEAD. Он позволяет
|
||
конфигурировать сервер-представитель (proxy) для выхода через
|
||
межсетевые экраны. Пакет совместим с политикой безопасности
|
||
Safesock.</p>
|
||
|
||
<p>Процедура <a href=#http::geturl_url><strong>::http::geturl</strong></a>
|
||
выполняет HTTP транзакцию. В зависимости от заданной опции это
|
||
может быть GET, POST или HEAD транзакция. Величина,
|
||
возвращаемая процедурой <a href=#http::geturl_url>
|
||
<strong>::http::geturl</strong></a>, является признаком (token) выполнения
|
||
транзакции. Кроме того, ее значение совпадает с именем массива в
|
||
пространстве имен <strong>::http</strong>, который содержит информацию о
|
||
выполнении транзакции. Элементы массива описаны ниже, см. "<a
|
||
href=#МАССИВ_СОСТОЯНИЯ_ТРАНЗАКЦИИ>Массив
|
||
состояния транзакции</a>".</p>
|
||
|
||
<p>Если процедура вызвана с опцией <strong>-command</strong>, операция
|
||
выполняется в фоновом режиме. Процедура <a href=
|
||
#http::geturl_url><strong>::http::geturl</strong></a>
|
||
завершается сразу после формирования HTTP запроса, а результаты
|
||
запроса обрабатываются после их получения. Для успешной работы в
|
||
таком режиме необходимо, чтобы был запущен обработчик
|
||
событий. Это всегда так для Tk-приложений. В чисто Tcl -
|
||
приложениях можно использовать процедуру <a
|
||
href=#http::wait><strong>::http::wait</strong></a> для запуска
|
||
обработчика событий.</p>
|
||
|
||
<h2><a name=КОМАНДЫ></a>КОМАНДЫ</h2>
|
||
|
||
<dl>
|
||
<dt><a name=http::config></a><strong>::http::config</strong>
|
||
?<em>options?</em></dt>
|
||
|
||
<dd><p>Команда <strong>::http::config</strong> используется, чтобы
|
||
установить или запросить имя proxy-сервера, порта и
|
||
пользовательского приложения (User-Agent), используемые в
|
||
HTTP запросах. Если никакие опции не заданы, возвращается
|
||
текущая конфигурация. Если задан единственный аргумент,
|
||
тогда, он должен быть именем одной из опций, описанных
|
||
ниже. В этом случае возвращается текущая величина указанной
|
||
опции. В противном случае аргументы состоят из пар: имя
|
||
опции - присваиваемое значение.</p>
|
||
|
||
<dl>
|
||
<dt><strong>-accept</strong> <em>mimetypes</em></dt>
|
||
|
||
<dd>Определяет типы документов, которые могут быть приняты
|
||
по запросу. Значение по умолчанию */* означает, что
|
||
могут быть приняты документы любого типа. Чтобы ограничить
|
||
список допустимых документов, можно использовать список
|
||
(через запятую) шаблонов документов следующего вида:
|
||
image/gif, image/jpeg, text/*.</dd>
|
||
|
||
<dt><strong>-proxyhost</strong> <em>hostname</em></dt>
|
||
|
||
<dd>Имя proxy-сервера, через который осуществляется связь.
|
||
Если не указано, связь осуществляется напрямую.</dd>
|
||
|
||
<dt><strong>-proxyport</strong> <em>number</em></dt>
|
||
|
||
<dd>Имя proxy-порта.</dd>
|
||
|
||
<dt><strong>-proxyfilter</strong> <em>command</em></dt>
|
||
|
||
<dd>Определяет команду, которая возвращает имена
|
||
proxy-сервера и proxy-порта, необходимые для данной
|
||
связи. В противном случае возвращает пустое значение. В
|
||
качестве аргумента при вызове команды используется имя
|
||
сервера (host). Если команда не задана, используются
|
||
значения опций <strong>-proxyhost</strong> и
|
||
<strong>-proxyport</strong>.</dd>
|
||
|
||
<dt><strong>-useragent</strong> <em>string</em></dt>
|
||
|
||
<dd>Определяет имя пользовательского приложения
|
||
(User-Agent). Значение по умолчанию "Tcl http client
|
||
package 2.0."</dd>
|
||
</dl>
|
||
</dd>
|
||
|
||
<dt><a name=http::geturl_url></a><strong>::http::geturl url</strong>
|
||
?<em>options</em>?</dt>
|
||
|
||
<dd><p>Команда <strong>::http::geturl</strong> - основная команда пакета.
|
||
Если задана опция <strong>-query</strong>, выполняется операция POST,
|
||
если задана опция <strong>-validate</strong>, выполняется операция
|
||
HEAD. В противном случае выполняется операция GET. Команда
|
||
возвращает признак - имя массива, который может быть
|
||
использован для получения дополнительной информации о
|
||
состоянии транзакции. Подробности см. <a
|
||
href=#МАССИВ_СОСТОЯНИЯ_ТРАНЗАКЦИИ>"Массив
|
||
состояния транзакции"</a>. Команда завершается после
|
||
завершения соответствующей операции, если она вызвана без
|
||
опции <strong>-command</strong>. В противном случае команда
|
||
<strong>::http::geturl</strong> завершается немедленно, а по
|
||
завершении операции вызывается соответствующая команда для
|
||
обработки ее результатов. Команда <strong>::http::geturl</strong>
|
||
может использоваться с различными опциями:</p>
|
||
|
||
<dl>
|
||
<dt><strong>-blocksize</strong> <em>size</em></dt>
|
||
|
||
<dd>Используется при чтении информации. Определяет
|
||
максимальный размер блока (в байтах), который может быть
|
||
прочитан за один раз. После каждого чтения блока
|
||
вызывается команда, определенная с помощью опции
|
||
<strong>-progress</strong>.
|
||
</dd>
|
||
|
||
<dt><strong>-channel</strong> <em>name</em></dt>
|
||
|
||
<dd>Перенаправляет полученную информация в соответствующий
|
||
канал вместо того, чтобы сохранять ее в переменной
|
||
<em>state(body)</em>.
|
||
</dd>
|
||
|
||
<dt><strong>-command</strong> <em>callback</em></dt>
|
||
|
||
<dd><p>Обеспечивает вызов команды <em>callback</em> после
|
||
завершения транзакции. При использовании этой опции
|
||
команда <strong>::http::geturl</strong> завершается сразу. Команда
|
||
<em>callback</em> вызывается с аргументом <em>token</em>,
|
||
который содержит имя массива, описанного ниже, см. <a
|
||
href=#МАССИВ_СОСТОЯНИЯ_ТРАНЗАКЦИИ>"Массив
|
||
состояния транзакции"</a>. Ниже приведен шаблон
|
||
типовой процедуры для использования в данной опции:</p>
|
||
<pre>
|
||
proc httpCallback {token} {
|
||
upvar #0 state
|
||
# Далее возможна работа со state как с обычным Tcl-массивом
|
||
}
|
||
</pre>
|
||
</dd>
|
||
|
||
<dt><strong>-handler</strong> <em>callback</em></dt>
|
||
|
||
<dd><p>Опция обеспечивает вызов команды <em>callback</em> как
|
||
только HTTP данные получены. Команда получает два
|
||
дополнительных аргумента: HTTP <em>socket</em> и имя
|
||
массива <em>token</em>, возвращенное командой
|
||
<strong>::http::geturl</strong> (см. <a href=
|
||
#МАССИВ_СОСТОЯНИЯ_ТРАНЗАКЦИИ>"Массив состояния
|
||
транзакции"</a>). Команда должна возвращать число
|
||
байтов, прочитанных из <em>socket</em>. Ниже приведен
|
||
шаблон подобной процедуры:</p>
|
||
<pre>
|
||
proc httpHandlerCallback {socket token} {
|
||
upvar #0 state
|
||
# Получен доступ к socket и Tcl-массиву state
|
||
# ...
|
||
# (например:
|
||
# set data [read 1000];
|
||
# set nbytes [string length ])
|
||
# ...
|
||
return nbytes
|
||
}
|
||
</pre>
|
||
</dd>
|
||
|
||
<dt><strong>-headers</strong> <em>keyvaluelist</em></dt>
|
||
|
||
<dd><p>Опция используется для включения в заголовок HTTP
|
||
запроса дополнительных полей. Аргумент должен быть
|
||
правильным списком с четным числом элементов, состоящим
|
||
попеременно из ключей и их значений. Ключи используются
|
||
как имена полей заголовка. Из значений удаляются символы
|
||
перехода на новую строку, чтобы избежать формирования
|
||
неправильного заголовка. Например, если
|
||
<em>keyvaluelist</em> содержит список <em>{Pragma
|
||
no-cache}</em> будет сформирован следующий заголовок
|
||
запроса:</p>
|
||
<pre>
|
||
Pragma: no-cache
|
||
</pre>
|
||
</dd>
|
||
|
||
<dt><strong>-progress</strong> <em>callback</em></dt>
|
||
|
||
<dd><p>Опция обеспечивает вызов команды <em>callback</em> для
|
||
обработки очередной порции данных. Команда
|
||
<em>callback</em> получает три аргумента: значение
|
||
<em>token</em>, возвращенное командой
|
||
<strong>::http::geturl</strong>, предполагаемый полный размер
|
||
данных из мета-данных и текущее количество поступивших
|
||
данных в байтах. Если предполагаемый полный размер
|
||
неизвестен, вместо него подставляется 0. Ниже приведен
|
||
шаблон для процедуры, вызываемой по опции
|
||
<strong>-progress</strong>:</p>
|
||
|
||
<pre>
|
||
proc httpProgress {token total current} {
|
||
upvar #0 state
|
||
}
|
||
</pre>
|
||
</dd>
|
||
|
||
<dt><strong>-query</strong> <em>query</em></dt>
|
||
|
||
<dd>Если указана данная опция, <strong>::http::geturl</strong>
|
||
формирует запрос POST и передает его на сервер. Запрос
|
||
должен быть сформатирован. Для выполнения форматирования
|
||
может использоваться процедура <a href=
|
||
#http::formatQuery><strong>::http::formatQuery</strong></a>.
|
||
</dd>
|
||
|
||
<dt><strong>-timeout</strong> <em>milliseconds</em></dt>
|
||
|
||
<dd>Если значение <em>milliseconds</em> не равно нулю,
|
||
устанавливается соответствующее время задержки. Задержка
|
||
выполняется перед вызовом команды <a href=
|
||
#http::reset><strong>::http::reset</strong></a> и команды,
|
||
заданной опцией <strong>-command</strong>. Во время задержки команда
|
||
<a href=#http::status><strong>::http::status</strong></a>
|
||
возвращает значение <em>timeout</em>.
|
||
</dd>
|
||
|
||
<dt><strong>-validate</strong> <em>boolean</em></dt>
|
||
|
||
<dd>Если значение boolean не равно нулю,
|
||
<strong>::http::geturl</strong> выполняет HTTP HEAD запрос. Такой
|
||
запрос возвращает мета информацию об источнике данных
|
||
(URL), а не его содержание. Мета информация содержится в
|
||
переменной <em>state(meta)</em> (см. "<a
|
||
href=#МАССИВ_СОСТОЯНИЯ_ТРАНЗАКЦИИ>Массив
|
||
состояния транзакции</a>").
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
|
||
<dt><a name=http::formatQuery></a><strong>::http::formatQuery</strong>
|
||
<em>key</em> <em>value</em> ?<em>key</em> <em>value</em>...?</dt>
|
||
|
||
<dd>Команда выполняет перекодирование запроса. Команда
|
||
использует четное число аргументов, являющихся соответственно
|
||
ключами запроса и их значениями. Она преобразует ключи и
|
||
значения и возвращает одну строку, в которой расставлены
|
||
необходимые "&" и "="
|
||
разделители. Результат можно использовать в качестве значения
|
||
для опции <strong>-query</strong> команды <a href=#http::geturl_url>
|
||
<strong>::http::geturl</strong></a>.
|
||
</dd>
|
||
|
||
<dt><a name=http::reset></a><strong>::http::reset</strong> <em>token</em>
|
||
?<em>why</em>?</dt>
|
||
|
||
<dd>Команда перезапускает HTTP транзакцию <em>token</em>, если
|
||
такая исполняется. Значение переменной <strong>state(status)</strong>
|
||
при этом переустанавливается в <em>why</em> (по умолчанию -
|
||
<strong>reset</strong>) и вызывается команда, заданная опцией
|
||
<strong>-command</strong>.
|
||
</dd>
|
||
|
||
<dt><a name=http::wait></a><strong>::http::wait</strong>
|
||
<em>token</em></dt>
|
||
|
||
<dd>Эта команда обеспечивает ожидание завершения транзакции. Она
|
||
работает только в надежных интерпретаторах, так как она
|
||
использует команду <a href=vwait.html><strong>vwait</strong></a>.
|
||
</dd>
|
||
|
||
<dt><a name=http::data></a><strong>::http::data</strong>
|
||
<em>token</em></dt>
|
||
|
||
<dd>Эта команда возвращает значение переменной
|
||
<strong>state(body)</strong>.
|
||
</dd>
|
||
|
||
<dt><a name=http::status></a><strong>::http::status</strong>
|
||
<em>token</em></dt>
|
||
|
||
<dd>Эта команда возвращает значение переменной
|
||
<strong>state(status)</strong>.
|
||
</dd>
|
||
|
||
<dt><a name=http::code></a><strong>::http::code</strong>
|
||
<em>token</em></dt>
|
||
|
||
<dd>Эта команда возвращает значение переменной
|
||
<strong>state(http)</strong>.
|
||
</dd>
|
||
|
||
<dt><a name=http::size></a><strong>::http::size</strong>
|
||
<em>token</em></dt>
|
||
|
||
<dd>Эта команда возвращает значение переменной
|
||
<strong>state(currentsize)</strong>.
|
||
</dd>
|
||
</dl>
|
||
|
||
<h2><a name=МАССИВ_СОСТОЯНИЯ_ТРАНЗАКЦИИ></a>МАССИВ СОСТОЯНИЯ ТРАНЗАКЦИИ</h2>
|
||
|
||
<p>Команда <a href=#http::geturl_url>
|
||
<strong>::http::geturl</strong></a> возвращает <em>token</em> - имя
|
||
Tcl-массива, содержащего информацию о HTTP транзакции. Для
|
||
упрощения доступа к массиву можно использовать следующую
|
||
конструкцию:</p>
|
||
<pre>
|
||
upvar #0 state
|
||
</pre>
|
||
|
||
<p>Массив содержит следующие элементы:</p>
|
||
<dl>
|
||
|
||
<dt>body</dt>
|
||
|
||
<dd>Содержание документа, заданного с помощью URL. Пусто, если
|
||
указана опция <strong>-channel</strong>. Значение переменной можно
|
||
получить также с помощью команды <a href=
|
||
#http::data><strong>::http::data</strong></a>.
|
||
</dd>
|
||
|
||
<dt>сurrentsize</dt>
|
||
|
||
<dd>Текущий объем информации в байтах, полученный от
|
||
источника. Значение переменной можно получить с помощью
|
||
команды <a href=#http::size><strong>::http::size</strong></a>.
|
||
</dd>
|
||
|
||
<dt>error</dt>
|
||
|
||
<dd>Если элемент определен, он содержит строку с сообщением об
|
||
ошибке, полученную при прерывании HTTP транзакции.</dd>
|
||
|
||
<dt>http</dt>
|
||
|
||
<dd>Элемент содержит значение HTTP статуса, полученное от
|
||
сервера. Значение переменной можно получить также с помощью
|
||
команды <a
|
||
href=#http::code><strong>::http::code</strong></a>. Статус
|
||
представляет собой строку из трех цифр, значения которой
|
||
соответствуют HTTP стандарту. Код 200 соответствует успешному
|
||
выполнению транзакции. Коды, начинающиеся с '4' или '5';,
|
||
указывают на ошибку. Коды, начинающиеся с '3', соответствуют
|
||
ошибкам перенаправления. В этом случае мета данные
|
||
<strong>Location</strong> определяют новый источник информации, который
|
||
содержит запрошенные данные.</dd>
|
||
|
||
<dt>meta</dt>
|
||
|
||
<dd><p>Мета данные, описывающие содержание документа. Данный
|
||
элемент массива содержит список ключей и их значений. Чтобы
|
||
облегчить доступ к данным можно использовать следующую
|
||
конструкцию:</p>
|
||
<pre>
|
||
array set meta (meta)
|
||
</pre>
|
||
<p>Некоторые ключи мета данных перечислены ниже, но в HTTP
|
||
стандарте их перечислено больше, кроме того, сервер может
|
||
добавлять собственные.</p>
|
||
</dd>
|
||
|
||
<dt>Content-Type</dt>
|
||
|
||
<dd>Тип документа. Например, <strong>text/html</strong>, <strong>image/gif</strong>,
|
||
<strong>application/postscript</strong> или <strong>application/x-tcl</strong>.</dd>
|
||
|
||
<dt>Content-Length</dt>
|
||
|
||
<dd>Объявленный размер документа. Реальный объем информации,
|
||
полученной с помощью команды <a href=#http::geturl_url>
|
||
<strong>::http::geturl</strong></a>, содержится в переменной
|
||
<strong>state(size)</strong>.
|
||
</dd>
|
||
|
||
<dt>Location</dt>
|
||
|
||
<dd>Измененный адрес документа.</dd>
|
||
|
||
<dt>status</dt>
|
||
|
||
<dd>Возможные значения <strong>ok</strong>,<strong>reset</strong> или
|
||
<strong>error</strong>. Во время транзакции значение пустое.</dd>
|
||
|
||
<dt>totalsize</dt>
|
||
|
||
<dd>Копия значения мета данных <strong>Content-Length</strong>.</dd>
|
||
|
||
<dt>type</dt>
|
||
|
||
<dd>Копия значения мета данных <strong>Content-Type</strong>.</dd>
|
||
|
||
<dt>url</dt>
|
||
|
||
<dd><p>Запрошенный адрес. Пример:</p>
|
||
<pre>
|
||
# Копирование источника в файл и печать мета данных
|
||
proc ::http::copy { url file {chunk 4096} } {
|
||
set out [open w]
|
||
set token [geturl -channel -progress ::http::Progress -blocksize ]
|
||
close
|
||
# Следующая команда завершает строку, начатую
|
||
# процедурой http::Progress
|
||
puts stderr
|
||
upvar #0 state
|
||
set max 0
|
||
foreach {name value} (meta) {
|
||
if {[string length ] > } {
|
||
set max [string length ]
|
||
}
|
||
if {[regexp -nocase ^location$ ]} {
|
||
# Обработка перенаправления адреса
|
||
puts stderr Location:
|
||
return [copy [string trim ] ]
|
||
}
|
||
}
|
||
incr max
|
||
foreach {name value} (meta) {
|
||
puts [format %-*s %s : ]
|
||
}
|
||
return
|
||
}
|
||
proc ::http::Progress {args} {
|
||
puts -nonewline stderr . ;
|
||
flush stderr
|
||
}
|
||
</pre>
|
||
</dd>
|
||
</dl>
|
||
</body>
|
||
</html>
|
||
|