Http      Commandes Internes Tcl

::http::config ?options?

La commande::http::config est utilisé pour fixer et consulter le nom et le port du serveur proxy, et le nom de l'Agent Utilisateur utilisé dans les requêtes HTTP Si aucunes options ne sont spécifiées, alors la configuration courante est renvoyée Si un seul argument est spécifié, alors il doit être un des flags décrits ci-dessous Dans ce cas la valeur courante de ce paramètre est renvoyée Autrement, les options seront un ensemble de flags et de valeurs qui definissent la configuration:

-accept mimetypes

L'en-tête Accept de la requête La valeur par défaut est */*, ce qui signifie que qui tout types de documents sont acceptés Autrement vous pouvez donner une  liste séparée par des virgules de types mime que vous souhaitez recevoir recevoir Par exemple, "image/gif, image/jpeg, text/*".

-proxyhost hostname

Le nom du proxy, s'il existe. Si cette valeur est la chaîne vide, l'URL est contacté directement.

-proxyport number

Le numéro de port du proxy.

-proxyfilter command

La commande est un callback qui est appelé pendant ::http::geturl pour determiner si un proxy est requis pour un host donné Un argument, un nom de machine, est ajouté à command quand elle est appelée Si un proxy est requis, le callback renverra une liste de deux élément contenant le serveur proxy et le port proxy Autrement le filtre renverra une liste vide Le filtre par défaut retourne les valeurs des paramètres -proxyhost et -proxyport si ils sont non-vides.

-useragent string

La valeur de l'en-tête Agent Utilisateur dans la requête HTTP Par défaut "Tcl http client package 2.2."

::http::geturl url ?options?

La commande::http::geturl est la fonction principale dans le paquetage. L'option - query provoque une opération POST et l'option -validate provoque une opération HEAD; autrement, une opération GET est effectuée La commande::http::geturl retourne une valeur token qui peut être utilisée pour obtenir l'information concernant la transaction Voir les sections TABLEAU D'ETAT et ERRORS pour les détails La commande::http::geturl bloque jusqu'a ce que l'opération se termine, à moins que l'option -command spécifie un callback appelé quand la transaction HTTP se termine. ::http::geturl accepte plusieurs options:

-blocksize size

La taille de bloc utilisée en lisant l'URL. Au plus size octets sont lus en une fois. Après chaque bloc, un appel à -progress est fait (si cette option est spécifiée).

-channel name

Copie l'URL contenu dans le canal name au lieu de le sauvegarder dans state(body).

-command callback

Appelle callback après la fin de la transaction HTTP. Cette option cause le retour immédiat de ::http::geturl. Le callback recoit un argument supplémentaire qui est le token renvoyé par ::http::geturl. Ce jeton est le nom d'un tableau qui est décrit dans la section TABLEAU D'ETAT.Voici un modèle pour le callback:
proc httpCallback {token} {
    upvar #0 $token state
    # Accède au tableau d'état Tcl
}

-handler callback

Appelle callback chaque fois que des données HTTP sont disponibles; si présent, rien d'autre ne sera fait avec les données HTTP. Cette fonction attend deux arguments supplémentaire: la socket pour les données HTTP et le token renvoyé par ::http::geturl. Le jeton est le nom d'un tableau global qui est décrit dans la section TABLEAU D'ETAT. La fonction est censée renvoyer le nombre d'octets lus de la socket. Voici un modèle pour le callback:
proc httpHandlerCallback {socket token } {
    upvar #0 $token state
    # Accède la socket, et au tableau d'état Tcl
    ... (exemple: set data [read $socket 1000];set nbytes [string length $data])
    ..   return nbytes
}

-headers keyvaluelist

Cette option est utilisée pour ajouter des en-têtes à la requête HTTP. L'argument keyvaluelist doit être une liste avec le même nombre d'éléments alternant entre clés et valeurs. Les clés deviennent les en-tête des champ noms. Les sauts de lignes sont enlevés des valeurs pour que l'en-tête ne puisse être corrompu. Par exemple, si keyvaluelist est Pragma no-cache alors l'en-tête suivant est inclus dans la requête HTTP:
Pragma: no-cache

-progress callback

Le callback est appelé après chaque transfert de données de l'URL. Le callback attend trois arguments additionels: le token de ::http::geturl, la taille totale attendue des meta-données contenues dans Content-Length, et le nombre courant d'octets transférés effectivement. La taille totale attendue peut être inconnue, auquel cas zéro est transmis au callback. Voici un modèle pour le callback progress:
proc httpProgress {token total current} {
    upvar #0 $token state
}

-query query

Ce flag fait effectuer à ::http::geturl une requête POST qui transmet la query au serveur. La query doit être une demande formatée x-url-encoding La fonction::http::formatQuery peut être utilisée pour le formatage.

-queryblocksize size

La taille de bloc utilisée en postant des données query à l'URL. Au plus size octets sont écrits à la fois. Après chaque bloc, un appel à -queryprogress callback est fait (si cette option est spécifiée).

-querychannel channelID

Ce flag fait effectuer à ::http::geturl une requête POST qui passe les données contenues dans channelID au serveur. Les données contenue dans channelID doivent être une demande formatée x-url-encoding à moins que l'option -type soit utilisée. Si un en-tête Content-Length n'est pas spécifié via l'option -headers, ::http::geturl tente de déterminer la taille des données post dans l'ordre de création de l'en-tête. Si elle est incapable de determiner la taille, elle retourne une erreur.

-queryprogress callback

Le callback est faite après chaque transfert de données à URL (ex. POST) et agit exactement comme l'option -progress (le format de callback est le même).

-timeout millisecondes

Si millisecondes est différent de zéro, alors ::http::geturl programme un timeout après le nombre spécifié de millisecondes. Un timeout provoque un appel de ::http::reset et un callback -command, si spécifié. La valeur de retour de ::http::status est timeout après un timeout.

-type mime-type

Utilisez mime-type comme la valeur Content-Type, au lieu de de la valeur par défaut (application/x-www-form-urlencoded) pendant une opération POST.

-validate boolean

Si boolean est différent de zéro, alors ::http::geturl does un HTTP HEAD requête. Cette requête retourne la meta information concernant l'URL, mais le contenu n'est pas renvoyé. La meta information est disponible dans la variable state(meta) après la transaction. Voir la section TABLEAU D'ETAT pour les détails.

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

Cette fonction opère un x-url-encodage des données consultées. Elle attend un même nombre d'arguments qui sont les clés et valeurs de la requête. Elle encode les clés et valeurs, et génère une chaîne avec les séparateurs corrects (& et =). Le résultat est convenable pour la valeur -query transmise à ::http::geturl.

::http::reset token?why?

Cette commande réinitialise la transaction HTTP identifiée par token, si elle existe. Ceci fixe la valeur state(status) à why, qui est par défaut de reset, et alors appelle le callback declaré par -command.

::http::wait token

Ceci est une fonction utilitaire qui bloque et attend que la transaction soit complétée. Elle fonctionne seulement avec du code de confiance parcequ'elle utilise vwait. D'autre part, elle n'est pas utile pour les cas où ::http::geturl est appelée sans l'option -command parce que dans ce cas l'appel à::http::geturl ne retourne pas jusqu'a ce que la transaction HTTP soit complète, et donc qu'il n'y a rien à attendre.

::http::data token

Ceci est une fonction utilitaire qui retourne l'élément body (ex., l'URL donnée) du tableau d'état.

::http::error token

Ceci est une fonction utilitaire qui retourne l'élément error du tableau d'état.

::http::status token

Ceci est une fonction utilitaire qui retourne l'élément status du tableau d'état.

::http::code token

Ceci est une fonction utilitaire qui retourne l'élément http du tableau d'état.

::http::ncode token

Ceci est une fonction utilitaire qui retourne juste le code numérique de retour (200, 404, etc.) de l'élément http du tableau d'état.

::http::size token

Ceci est une fonction utilitaire qui retourne l'élément currentsize du tableau d'état, qui représente le nombre d'octets reçus de l' URL dans l'appel à ::http::geturl.

::http::cleanup token

Cette fonction nettoye l'état associé à la connection identifiée par token Après cet appel, les fonctions comme ::http::data ne peuvent pas être utilisées pour obtenir l'information concernant l'opération Il est fortement recommandé que vous appeliez cette fonction après avoir fini avec une requête HTTP Ne pas le faire proquera la non-libération de la mémoire, et si votre appli appelle ::http::geturl plusieurs fois, la fuite mémoire pourrait provoquer un pic de performance...ou bien pire.

::http::register proto port command

Cette fonction permet de fournir des types de transport HTTP tel que HTTPS, en enregistrant un préfixe, le port par défaut, et la commande à exécuter pour créer le channel Tcl. Ex.:

package require http
package require tls
http::register https 443 ::tls::socket
set token [http::geturl https://my.secure.site/]

::http::unregister proto

Cette fonction libère un gestionnaire de protocole précedemment declaré via http::register

ok

Si la transaction HTTP se termine entièrement, alors le statut sera ok. Néanmoins, vous pouvez toujours vérifier la valeur http::code pour obtenir le statut HTTP La fonction http::ncode fournit just l'erreur numérique (ex., 200, 404 ou 500) alors que  la fonction http::code retourne une valeur comme "HTTP 404 File not found".

eof

Si le serveur ferme la socket sans réponse, alors aucune erreur n'est levée, mais le statut de la transaction sera eof.

error

Le message d'erreur sera aussi stocké dans l'élément error du tableau d'état, accessible via ::http::error.

body

Le contenu de l'URL. Sera vide si l'option -channel a été spécifiée Cette valeur est renvoyéee par la commande::http::data.

currentsize

Le nombre courant d'octets récupéré de l'URL. Cette valeur est renvoyée par la commande::http::size.

error

Si défini, c'est la chaîne d'erreur vue quand la transaction HTTP est avortée.

http

Le statut de la réponse HTTP du serveur Cette valeur est renvoyée par la commande::http::code Le format de cette valeur est:
HTTP/1.0 code string Le code est un nombre de trois-digit défini dans le standard HTTP. Un code de 200 est OK Les codes commençant avec 4 ou 5 indiquent des erreurs. Les codes commençant avec 3 sont des erreurs de redirection Dans ce cas la meta-donnée Location spécifie une nouvelle URL qui contient l'information requise.

meta

Le protocole HTTP retourne les meta-données qui décrivent les contenus de l'URL. L'élément meta du tableau d'état est une liste de clés et valeurs des meta-données Ceci dans un format utile pour l'initialisation d'un tableau qui contient les meta-données: array set meta $state(meta) Certaines des clés meta-données sont listées ci-dessous, mais le standard HTTP en définit plus, et les serveurs sont libres d'ajouter les leurs.

Content-Type

Le type de contenus de l'URL Les exemples inclutnt text/html, image/gif, application/postscript et application/x-tcl.

Content-Length

La taille déclarée des contenus La taille obtenue par ::http::geturl est disponibles comme state(size).

Location

Une URL alternative qui contient les données requises.

posterror

L'erreur, si elle existe, qui s'est produite pendant l'écriture du post des données sur le serveur.

status

Soit ok, en cas de succès, reset si réinitialisé par l'utilisateur, timeout si un timeout s'est produit avant que la transaction soit complète, ou error pour une condition d'erreur Durant la transaction cette valeur est une chaîne vide.

totalsize

Un copie de la valeur des meta-données Content-Length.

type

Une copie de la valeur des meta-données Content-Type.

url

L'URL requise.