Http

From Base de connaissances eggdrops & TCL
Jump to: navigation, search

Http - Implémentation client du protocole HTTP/1.0.

Syntaxe

package require http ?2.3?
::http::config ?options?
::http::geturl url ?options?
::http::formatQuery list
::http::reset token
::http::wait token
::http::status token
::http::size token
::http::code token
::http::ncode token
::http::data token
::http::error  token
::http::cleanup token
::http::register proto port command
::http::unregister proto

Description

Le paquetage http fournit la partie client du protocole HTTP/1.0. Le paquetage implémente les opérations GET, POST, et HEAD de HTTP/1.0. Il permet la configuration d'un proxy pour traverser les firewalls Le paquetage est compatible avec la politique de sécurité Safesock, donc il peut être utilisé par un applet non vérifié pour récupérer des URL à partir d'un ensemble restreint d'hôtes. Ce paquetage peut être étendu pour supporter d'autres protocoles de transport HTTP, tel que HTTPS, en fournissant une commande socket utilisateur, via http::register.

La fonction ::http::geturl effectue une transaction HTTP. Ses options determinent si une transaction GET, POST, ou HEAD est effectuée La valeur de retour de ::http::geturl est un jeton pour la transaction. La valeur est aussi le nom d'un tableau dans le ::http namespace qui contient information d'état concernant la transaction Les éléments de ce tableau sont décrits dans la section TABLEAU D'ETAT.

Si l'option -command est spécifiée, alors l'opération HTTP est faite en arrière-plan. ::http::geturl retourne immédiatement après la génération de la requête HTTP et le callback est appelé quand la transaction se termine Pour que cela fonctionne, la boucle d'évènement Tcl doit être active Dans les applications Tk c'est toujours vrai Pour les applications purement Tcl, l'appelant peut utiliser ::http::wait après l'appel de ::http::geturl pour lancer la boucle d'évènement.

Commandes

  • ::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
    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 dtat 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 dtat 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émenterror 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.

Exemple:

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

Erreurs

La fonction http::geturl lèvera des erreurs dans les cas suivants: options de ligne de commande invalides, URL invalide, une URL sur une machine inexistante, ou une URL à un mauvais port sur une machine existante. Ces erreurs signifient que la transaction réseau n'a même pas démarré. Elle lève aussi une erreur si elle recoit une erreur I/O pendant l'écriture de l'en-tête de la requête HTTP. Pour les appels::http::geturl synchrones (où -command n'est pas spécifiée), elle lèvera une erreur si elle recoit une erreur I /O en lisant l'en-têtes ou les données de la réponse HTTP parce que ::http::geturl ne retourne pas de jeton dans ces cas, elle fait tout le nettoyage requis et il n'y a pas de nécessité pour votre appli d'appeler ::http::cleanup.

Pour les appels asynchrones de ::http::geturl, toutes les situations d'erreur précédentes s'appliquent, excepté que si s'il y a une erreur pendant la lecture de l'en-têtes ou les données de la réponse HTTP, aucune exception n'est lévèe Ceci parcequ'après l'écriture des en-têtes HTTP, ::http::geturl retourne, et le reste de la transaction HTTP se produit en arrière-plan La commande callback peut verifier si l'erreur s'est produite pendant la lecture en appelant ::http::status pour vérifier le statut et si c'est error, appeller ::http::error pour obtenir le message d'erreur.

Alternativement, si le flux du programme principal atteint un point ou il a besoin de connaitre le résultat de la requête HTTP asynchrone, il peut appeller ::http::wait et alors verifier les statut et erreur, comme le callback le fait.

Dans tous les cas, vous devez toujours appeller http::cleanup pour effacer le tableau d'état quand vous avez fini.

Les autres résultats possibles de la transaction HTTP déterminés par l'examen du statut à partir de http::status sont décrit ci-dessous.

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émenterror du tableau d'état, accessible via ::http::error.

Une autre possibilité d'erreur est que http::geturl soit incapable d'écrire toutes les données post sur le serveur avant que le serveur réponde et ferme la socket. Le message d'erreur est sauvegardé dans l'élément posterror du tableau d'état et alors http::geturl tente de finaliser la transaction. Si elle peut lire la réponse du serveur elle finira avec un statut ok, autrement elle aura un statuteof

Tableau d'état

La fonction::http::geturl retourne un token qui peut être utilisé pour obtenir l'état de la transaction HTTP sous la forme d'un tableau Tcl. Utilisez cette construction pour créer une variable tableau facile à utiliser:

upvar #0 $token state

Une fois que les données associées à l'url ne sont plus nécessaires, le tableau d'état sera détruit pour libérer la mémoire. La fonction http::cleanup est fournie à cet usage. Les éléments suivants du tableau sont supportés:

  • 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 : Une 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.

Exemple

# Copie une URL dans un fichier et affiche les meta-données
proc ::http::copy { url file {chunk 4096} } {
   set out [[open $file w]]
   set token [[geturl $url -canal $out -progress ::http::Progress -blocksize $chunk]]
   close $out
   # Ceci finit la ligne lancé par http::Progress
   puts stderr ""
   upvar #0 $token state
   set max 0
   foreach {name value} $state (meta) {
      if {[[string longueur $name]] > $max} {
         set max [[string longueur $name]]
      }
      if {[[regexp -nocase ^location$ $name]]} {
         # Gère la redirection d'URL
         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 -nunwline stderr . ; flush stderr
}

Voir également

safe, socket, tls