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
    Определяет типы документов, которые могут быть приняты по запросу. Значение по умолчанию ‘*/*’ означает, что могут быть приняты документы любого типа. Чтобы ограничить список допустимых документов, можно использовать список (через запятую) шаблонов документов следующего вида: “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 url ?options?
    Команда ::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} {
    upvar #0 $token state
    # Получен доступ к socket и Tcl-массиву state
    ...
    (например: set data [read $socket 1000];set nbytes [string length $data])
    ...
    return nbytes
    }
    -headers keyvaluelist
    Опция используется для включения в заголовок HTTP запроса дополнительных полей. Аргумент должен быть правильным списком с четным числом элементов, состоящим попеременно из ключей и их значений. Ключи используются как имена полей заголовка. Из значений удаляются символы перехода на новую строку, чтобы избежать формирования неправильного заголовка. Например, если keyvaluelist содержит список {Pragma no-cache} будет сформирован следующий заголовок запроса:
    Pragma: no-cache
    -progress callback
    Опция обеспечивает вызов команды callback для обработки очередной порции данных. Команда callback получает три аргумента: значение token, возвращенное командой ::http::geturl, предполагаемый полный размер данных из мета-данных и текущее количество поступивших данных в байтах. Если  едполагаемый полный размер неизвестен, вместо него подставляется 0. Ниже приведен шаблон для процедуры, вызываемой по опции -progress:
    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) (см. “Массив состояния транзакции”).
    ::http::formatQuery key value?key value...?
    Команда выполняет перекодирование запроса. Команда использует четное число аргументов, являющихся соответственно ключами запроса и их значениями. Она преобразует ключи и значения и возвращает одну строку, в которой расставлены необходимые “&” и “=” разделители. Результат можно использовать в качестве значения для опции -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
    Мета данные, описывающие содержание документа. Данный элемент массива содержит список ключей и их значений. Чтобы облегчить доступ к данным можно использовать следующую конструкцию:
    array set meta $state(meta)
    Некоторые ключи мета данных перечислены ниже, но в HTTP стандарте их перечислено больше, кроме того, сервер может добавлять собственные.
    Content-Type
    Тип документа. Например, text/html, image/gif, application/postscript или application/x-tcl.
    Content-Length
     
    Объявленный размер документа. Реальный объем информации, полученной с помощью команды ::http::geturl, содержится в переменной state(size).
    Location
    Измененный адрес документа.
    status
    Возможные значения ok, reset или error. Во время транзакции значение пустое.
    totalsize
    Копия значения мета данных Content-Length.
    type
    Копия значения мета данных Content-Type.
    url
    Запрошенный адрес.
    Пример:
     
    # Копирование источника в файл и печать мета данных
    proc ::http::copy { url file {chunk 4096} } {
    set out [open $file w]
    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]
     }
    }
    incr max
    foreach {name value} $state(meta) {
     puts [format “%-*s %s” $max $name: $value]
    }
    return $token

    }
    proc ::http::Progress {args} {
    puts -nonewline stderr. ; flush stderr
    }


    [ Список команд Tcl ]            [ Содержание ]