# Http

Клиентская часть реализации протокола HTTP/1.0.

## СИНТАКСИС

          package require http ?2.0?
          ::http::config ?options?
          ::http::geturl url ?options?
          ::http::formatQuery list
          ::http::reset token ?why?
          ::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  state
                          # Далее возможна работа со state как с обычным Tcl-массивом
        	      }

  -handler callback

    Опция обеспечивает вызов команды callback как только HTTP данные получены. Команда получает два дополнительных аргумента: HTTP socket и имя массива token, возвращенное командой ::http::geturl (см. "Массив состояния транзакции"). Команда должна возвращать число байтов, прочитанных из socket. Ниже приведен шаблон подобной процедуры:

             proc httpHandlerCallback {socket token} {
                           upvar #0  state
                           # Получен доступ к socket и Tcl-массиву state
                           # ...
                           # (например:
                           # set data [read  1000];
                           # set nbytes [string length ])
                           # ...
                           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  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  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 (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  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
      	  }