http

NAME

http — Клиентская реализация протокола HTTP/1.1

SYNOPSIS

DESCRIPTION

COMMANDS

::http::config ?options?

-accept mimetypes

-proxyhost hostname

-proxyport number

-proxyfilter command

-urlencoding encoding

-useragent string

Имя

Синтаксис

Описание

Процедура ::http::geturl выполняет HTTP-транзакцию. Её options определяют, будет ли выполнена транзакция GET, POST или HEAD. Возвращаемое значение ::http::geturl — это маркер транзакции. Это значение также является именем массива в пространстве имён ::http, который содержит информацию о состоянии транзакции. Элементы этого массива описаны в разделе МАССИВ СОСТОЯНИЙ.

Если указан параметр -command, то операция HTTP выполняется в фоновом режиме. ::http::geturl возвращает значение немедленно после генерации HTTP-запроса, а обратный вызов вызывается по завершении транзакции. Для этого необходимо, чтобы цикл событий Tcl был активным. В приложениях Tk это всегда так. Для чисто Tcl-приложений вызывающая сторона может использовать ::http::wait после вызова ::http::geturl для запуска цикла событий.

Команды

::http::config ?options?

Команда ::http::config используется для установки и запроса имени прокси-сервера и порта, а также имени User-Agent, используемого в запросах HTTP. Если не указаны никакие параметры, возвращается текущая конфигурация. Если указан один параметр, он должен быть одним из флагов, описанных ниже. В этом случае возвращается текущее значение этого параметра. В противном случае параметры должны представлять собой набор флагов и значений, определяющих конфигурацию:

-accept mimetypes

Заголовок Accept запроса. По умолчанию значение равно */*, что означает, что принимаются все типы документов. В противном случае можно указать список типов MIME, разделенных запятыми, которые вы готовы принять. Например, “image/gif, image/jpeg, text/*”.

-proxyhost hostname

Имя прокси-хоста, если таковой имеется. Если это значение пустая строка, то к хосту URL обращаются напрямую.

-proxyport number

Номер порта прокси-сервера.

-proxyfilter command

Команда — это обратный вызов, который выполняется во время ::http::geturl для определения, требуется ли прокси для данного хоста. При вызове к command добавляется один аргумент — имя хоста. Если прокси требуется, обратный вызов должен вернуть список из двух элементов, содержащий прокси-сервер и порт прокси-сервера. В противном случае фильтр должен вернуть пустой список. По умолчанию фильтр возвращает значения параметров -proxyhost и -proxyport, если они не пустые.

-urlencoding encoding

Кодировка, используемая для создания URL с кодировкой x-url с помощью ::http::formatQuery. По умолчанию используется utf-8, как указано в RFC 2718. До версии http 2.5 это не было определено, и такое поведение можно получить, указав пустую строку ({}), хотя рекомендуется использовать iso8859-1 для восстановления аналогичного поведения, но без ошибки ::http::formatQuery при обработке символов, не являющихся латинскими-1.

-useragent string

Значение заголовка User-Agent в запросе HTTP. По умолчанию значение равно “Tcl http client package 2.7”.

::http::geturl url ?options?

Команда ::http::geturl — это основная процедура в пакете. Параметр -query вызывает операцию POST, а параметр -validate вызывает операцию HEAD; в противном случае выполняется операция GET. Команда ::http::geturl возвращает значение маркера, которое можно использовать для получения информации о транзакции. Подробности см. в разделе МАССИВ СОСТОЯНИЯ и ОШИБКИ. Команда ::http::geturl ожидает завершения операции, если параметр -command не задает обратный вызов, который вызывается при завершении HTTP-транзакции. ::http::geturl принимает несколько параметров:

-binary boolean

Указывает, нужно ли принудительно интерпретировать данные URL как двоичные. Обычно это обнаруживается автоматически (все, что не начинается с типа содержимого text или у которого кодировка содержимого gzip или compress, считается двоичными данными).

-blocksize size

Размер блока, используемый при чтении URL. Одновременно считывается не более size байт. После каждого блока вызывается обратный вызов -progress (если этот параметр указан).

-channel name

Скопировать содержимое URL в канал name вместо сохранения в state(body).

-command callback

Вызвать callback после завершения HTTP-транзакции. Этот параметр заставляет ::http::geturl вернуть значение немедленно. callback получает дополнительный аргумент, который является маркером, возвращенным из ::http::geturl. Этот маркер является именем массива, описанного в разделе МАССИВ СОСТОЯНИЯ. Вот шаблон для обратного вызова:

proc httpCallback {token} {
    upvar #0 $token state
    # Access state as a Tcl array
}

-handler callback

Вызвать callback всякий раз, когда доступны данные HTTP; если он присутствует, с данными HTTP ничего больше не будет сделано. Эта процедура получает два дополнительных аргумента: сокет для данных HTTP и маркер, возвращенный из ::http::geturl. Маркер — это имя глобального массива, описанного в разделе МАССИВ СОСТОЯНИЯ. Процедура должна вернуть количество байт, прочитанных из сокета. Вот шаблон для обратного вызова:

proc httpHandlerCallback {socket token} {
    upvar #0 $token state
    # Access socket, and state as a Tcl array
    # For example...
    ...
    set data [read $socket 1000]
    set nbytes [string length $data]
    ...
    return $nbytes
}

-headers keyvaluelist

Этот параметр используется для добавления заголовков, которые еще не указаны в ::http::config, к запросу HTTP. Аргумент keyvaluelist должен быть списком с четным числом элементов, чередующихся между ключами и значениями. Ключи становятся именами полей заголовка. Новые строки удаляются из значений, чтобы заголовок не был поврежден. Например, если keyvaluelist имеет значение Pragma no-cache, то в запросе HTTP включается следующий заголовок:

Pragma: no-cache

-keepalive boolean

Если значение истинно, попытаться сохранить соединение открытым для обслуживания нескольких запросов. Значение по умолчанию равно 0.

-method type

Принудительно установить метод запроса HTTP на type. ::http::geturl будет автоматически выбирать GET, POST или HEAD на основе других параметров, но этот параметр позволяет выбирать такие варианты, как PUT и DELETE для поддержки веб-DAV.

-myaddr address

Передать определенный локальный адрес в вызов socket в случае наличия нескольких интерфейсов.

-progress callback

callback вызывается после каждого переноса данных из URL. Обратный вызов получает три дополнительных аргумента: маркер из ::http::geturl, ожидаемый общий размер содержимого из метаданных Content-Length и текущее количество переданных байт. Ожидаемый общий размер может быть неизвестен, в этом случае в обратный вызов передается ноль. Вот шаблон для обратного вызова прогресса:

proc httpProgress {token total current} {
    upvar #0 $token state
}

-protocol version

Выбрать версию протокола HTTP для использования. Это должно быть 1.0 или 1.1 (по умолчанию). Необходимо только для серверов, которые не понимают или иначе жалуются на HTTP/1.1.

-query query

Этот флаг заставляет ::http::geturl выполнить запрос POST, передав query серверу. query должен быть запросом в формате x-url-encoding. Для форматирования можно использовать процедуру ::http::formatQuery.

-queryblocksize size

Размер блока, используемый при отправке данных запроса в URL. Одновременно записывается не более size байт. После каждого блока вызывается обратный вызов -queryprogress (если он указан).

-querychannel channelID

Этот флаг заставляет ::http::geturl выполнить запрос POST, передав данные, содержащиеся в channelID, серверу. Данные, содержащиеся в channelID, должны быть запросом в формате x-url-encoding, если не используется параметр -type ниже. Если заголовок Content-Length не указан в параметрах -headers, ::http::geturl пытается определить размер данных POST, чтобы создать этот заголовок. Если размер определить невозможно, возвращается ошибка.

-queryprogress callback

callback вызывается после каждого переноса данных в URL (т.е. POST) и работает точно так же, как параметр -progress (формат обратного вызова такой же).

-strict boolean

Принудительно ли выполнять валидацию URL RFC 3986 в запросе. По умолчанию значение равно 1.

-timeout milliseconds

Если milliseconds не равно нулю, ::http::geturl устанавливает таймаут, который сработает после указанного количества миллисекунд. В результате таймаута вызывается ::http::reset и обратный вызов -command, если он указан. Значение возврата ::http::status равно timeout после наступления таймаута.

-type mime-type

Использовать mime-type в качестве значения Content-Type вместо значения по умолчанию (application/x-www-form-urlencoded) при выполнении операции POST.

-validate boolean

Если boolean не равно нулю, ::http::geturl выполняет запрос HTTP HEAD. Этот запрос возвращает метаинформацию об URL, но содержимое не возвращается. Метаинформация доступна в переменной state(meta) после транзакции. Подробности см. в разделе МАССИВ СОСТОЯНИЯ.

::http::formatQuery key value ?key value ...?

Эта процедура выполняет кодировку x-url данных запроса. Она принимает четное число аргументов, которые представляют собой ключи и значения запроса. Она кодирует ключи и значения и генерирует одну строку с правильными разделителями & и =. Результат подходит для значения -query, передаваемого команде ::http::geturl.

::http::reset token ?why?

Эта команда сбрасывает HTTP-транзакцию, идентифицированную маркером, если таковой имеется. Это устанавливает значение state(status) на why, которое по умолчанию равно reset, а затем вызывает зарегистрированный обратный вызов -command.

::http::wait token

Это вспомогательная процедура, которая блокирует выполнение и ожидает завершения транзакции. Она работает только в доверенном коде, так как использует vwait. Также она не полезна в случае, когда ::http::geturl вызывается без параметра -command, потому что в этом случае вызов ::http::geturl не возвращает значение, пока HTTP-транзакция не будет завершена, а значит, ждать нечего.

::http::data token

Это вспомогательная процедура, которая возвращает элемент body (т.е. данные URL) массива состояния.

::http::error token

Это вспомогательная процедура, которая возвращает элемент error массива состояния.

::http::status token

Это вспомогательная процедура, которая возвращает элемент status массива состояния.

::http::code token

Это вспомогательная процедура, которая возвращает элемент http массива состояния.

::http::ncode token

Это вспомогательная процедура, которая возвращает только числовой код возврата (200, 404 и т.д.) из элемента http массива состояния.

::http::size token

Это вспомогательная процедура, которая возвращает элемент currentsize массива состояния, представляющий количество полученных байт из URL в вызове ::http::geturl.

::http::meta token

Это вспомогательная процедура, которая возвращает элемент meta массива состояния, содержащий заголовки HTTP-ответа. Объяснение этого элемента см. ниже.

::http::cleanup token

Эта процедура очищает состояние, связанное с подключением, идентифицированным по token. После этого вызова процедуры, такие как ::http::data, нельзя использовать для получения информации об операции. Настоятельно рекомендуется вызывать эту функцию после завершения работы с заданным HTTP-запросом. Если этого не сделать, память не будет освобождена, а если ваше приложение вызовет ::http::geturl достаточно много раз, утечка памяти может привести к снижению производительности... или к худшему.

::http::register proto port command

Эта процедура позволяет предоставлять пользовательские типы HTTP-транспорта, такие как HTTPS, регистрируя префикс, порт по умолчанию и команду для выполнения, чтобы создать Tcl канал. Например:

package require http
package require tls

::http::register https 443 ::tls::socket

set token [::http::geturl https://my.secure.site/]

::http::unregister proto

Эта процедура аннулирует обработчик протокола, который был ранее зарегистрирован с помощью ::http::register.

Ошибки

Для асинхронных вызовов ::http::geturl применяются все вышеперечисленные ситуации с ошибками, за исключением того, что если при чтении заголовков или данных HTTP-ответа произойдёт какая-либо ошибка, исключение не генерируется. Это происходит потому, что после записи заголовков HTTP, ::http::geturl возвращает значение, а остальная часть HTTP-транзакции выполняется в фоновом режиме. Обработчик команды может проверить, произошла ли ошибка при чтении, вызвав ::http::status для проверки статуса и, если он error, вызвав ::http::error для получения сообщения об ошибке.

Кроме того, если основной поток программы достигнет точки, где ему нужно узнать результат асинхронного HTTP-запроса, он может вызвать ::http::wait, а затем проверить статус и ошибку, точно так же, как это делает обработчик.

В любом случае, вы по-прежнему должны вызвать ::http::cleanup для удаления массива состояний, когда вы закончите.

Есть и другие возможные результаты HTTP-транзакции, которые определяются путём проверки статуса из ::http::status. Они описаны ниже.

ok

Если HTTP-транзакция завершается полностью, статус будет ok. Однако вы всё равно должны проверить значение ::http::code, чтобы получить HTTP-статус. Процедура ::http::ncode предоставляет только числовой код ошибки (например, 200, 404 или 500), в то время как процедура ::http::code возвращает значение, подобное "HTTP 404 Файл не найден".

eof

Если сервер закрывает сокет, не ответив, ошибка не генерируется, но статус транзакции будет eof.

error

Сообщение об ошибке также будет сохранено в элементе массива состояния error, доступном через ::http::error.

Ещё одна возможность ошибки заключается в том, что ::http::geturl не может записать все данные запроса POST на сервер до того, как сервер ответит и закроет сокет. Сообщение об ошибке сохраняется в элементе массива состояния posterror, а затем ::http::geturl пытается завершить транзакцию. Если она может прочитать ответ сервера, она завершится со статусом ok, в противном случае – со статусом eof.

Массив состояния

upvar #0 $token state

После того, как данные, связанные с URL, больше не нужны, массив состояния должен быть удалён, чтобы освободить память. Для этой цели предоставляется процедура ::http::cleanup. Ниже представлены поддерживаемые элементы массива:

body

Содержимое URL. Будет пустым, если был указан параметр -channel. Это значение возвращается командой ::http::data.

charset

Значение атрибута charset из метаданных Content-Type. Если не указано, по умолчанию используется RFC-стандарт iso8859-1 или значение $::http::defaultCharset. Входящие текстовые данные автоматически преобразуются из этого набора символов в utf-8.

coding

Копия значения метаданных Content-Encoding.

currentsize

Текущее количество байтов, полученных из URL. Это значение возвращается командой ::http::size.

error

Если определено, это строка ошибки, которая возникла при прерывании HTTP-транзакции.

http

HTTP-статус ответа от сервера. Это значение возвращается командой ::http::code. Формат этого значения:

HTTP/1.1 code string

Код – трёхзначное число, определённое в стандарте HTTP. Код 200 означает «ОК». Коды, начинающиеся с 4 или 5, указывают на ошибки. Коды, начинающиеся с 3, – на ошибки перенаправления. В этом случае метаданные Location указывают новый URL, содержащий запрашиваемую информацию.

meta

HTTP-протокол возвращает метаданные, описывающие содержимое URL. Элемент meta массива состояния – список ключей и значений метаданных. Это формат, полезный для инициализации массива, содержащего только метаданные:

array set meta $state(meta)

Некоторые ключи метаданных перечислены ниже, но стандарт HTTP определяет больше, и серверы могут добавлять свои собственные.

Content-Type

Тип содержимого URL. Примеры включают text/html, image/gif, application/postscript и application/x-tcl.

Content-Length

Объявленный размер содержимого. Фактический размер, полученный ::http::geturl, доступен как state(currentsize).

Location

Альтернативный URL, содержащий запрашиваемые данные.

posterror

Ошибка, если она возникла при записи данных запроса POST на сервер.

status

Либо ok для успешного завершения, reset для сброса пользователем, timeout, если произошёл таймаут до завершения транзакции, или error для условия ошибки. Во время транзакции это значение пустая строка.

totalsize

Копия значения метаданных Content-Length.

type

Копия значения метаданных Content-Type.

url

Запрашиваемый URL.

Пример

proc httpcopy { url file {chunk 4096} } {
    set out [open $file w]
    set token [::http::geturl $url -channel $out \
            -progress httpCopyProgress -blocksize $chunk]
    close $out

    # This ends the line started by httpCopyProgress
    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]} {
            # Handle URL redirects
            puts stderr "Location:$value"
            return [httpcopy [string trim $value] $file $chunk]
        }
    }
    incr max
    foreach {name value} $state(meta) {
        puts [format "%-*s %s" $max $name: $value]
    }

    return $token
}
proc httpCopyProgress {args} {
    puts -nonewline stderr .
    flush stderr
}

См. также