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