cURL avec 4D 2004 - Client HTTP, Get et Post, FTP, et plus encore

cURL est issu du site web http://cURL.haxx.se/
« cURL est un outil sous forme de ligne de commande pour transférer des fichiers avec une syntaxe URL, supportant les protocoles FTP, FTPS, HTTP, HTTPS, GOPHER, TELNET, DICT, FILE et LDAP. cURL supporte les protocoles de certification HTTPS, le HTTP PORT, HTTP PUT, l'upload par FTP, l'upload par formulaire HTTP, les proxys, cookies, authentification par utilisateur et mot de passe (Basic, Digest, NTLM, Negotiate, kerberos,…), transfert de fichier, tunnels proxy et une foultitude d'autres trucs utiles. »

cURL est open source et gratuit. Il est fourni avec Mac OS X et déjà préinstallé ! Si vous voulez avoir un premier aperçu sous Mac, lancez le Terminal et tapez :

curl www.4d.fr

cURL doit être installé sous Windows, mais vous pouvez le placer à côté de votre base de données 4D et le distribuer chez vos clients sans installation spécifique. Vous pouvez l'installer automatiquement sur toutes les machines 4D Client, sans intervention manuelle, en utilisant le nouveau dossier « 4D Extras ». Le contrat de licence de cURL permet cela. Lisez la section « Installation sur Windows » pour plus de détails.

cURL est aussi disponible sous forme de librairies. Il peut donc être compilé dans un plugin 4D. Cette note technique montre comment utiliser la commande LANCER PROCESS EXTERNE pour contrôler des outils externes sans avoir besoin de développer un plugin. Le gros avantage ici est qu'il est facile de faire une mise à jour de l'outil. Avec un plugin, vous auriez à le recompiler. L'utilisation de LANCER PROCESS EXTERNE évite d'être confronté aux limites induites par des mises à jour prochaines de 4D, du système d'exploitation ou d'autres composants.

La base exemple vous donnera un aperçu de ce qu'il est possible de faire avec cURL. Vous avez seulement besoin d'une connexion Internet et de 4D 2004 [ndt : 4D 2004.4 est la dernière version à ce jour]. Le même code peut être utilisé sur Mac OS X (testé de 10.2.8 à 10.4) et sur Windows. cURL doit être préinstallé sur Windows, ainsi que QuickTime.

La première fenêtre de dialogue utilise un simple GET. Entrez une URL ou gardez « www.4d.fr », et cliquez sur le bouton Get.

Cela initialisera une connexion Internet et téléchargera la page. Celle-ci sera affichée sous format « texte brut » comme ci-dessus.

cURL fonctionne bien évidemment avec les serveurs proxys ; vous trouvez plus d'informations dans les documentations.

Une petite astuce : entrez -x IP:port www.4d.com dans le dialogue ci-dessus pour vous connecter à travers un proxy.

Voici un exemple simple pour récupérer des données par le web. Le script du bouton est :

vResultat := LancerCurl(vURL)

LancerCurl est une méthode projet qui tient compte des différentes façons de lancer cURL sur Mac OS ou sous Windows, et qui retourne la réponse sous forme de texte. Nous avons également la méthode LancerCurlBlob qui permet de récupérer des données de plus de 32 ko, comme des images ou des fichiers PDF retournés dans un blob.

cURL permet aussi d'écrire le résultat de la requête dans un document sur le disque (très utile pour les documents PDF) ou d'uploader les documents directement à partir du disque.

Passons maintenant à un exemple plus complexe. Si vous allez à la page deux du dialogue, vous trouverez un exemple de requête HTTP utilisant Post :

C'est un exemple concret utilisé commercialement dans les systèmes de facturation en Europe. Les sociétés européennes ont un numéro de TVA qui permet d'envoyer une transaction hors TVA si les deux parties ont chacune un numéro de TVA valide. L'expéditeur doit vérifier la validité du numéro de TVA du destinataire. Il existe un site web qui traite cette partie dont les données devraient normalement être saisies dans un navigateur.

L'exemple suivant automatise cette tâche. Ce code est capable de remplir automatiquement les données nécessaires et de comprendre le résultat reçu.

Faites un essai avec le numéro déjà entré et cliquez sur le bouton Vérifier ; le code ci-dessous affichera « Le numéro est valide ». Modifiez le numéro et essayez à nouveau…

Maintenant, examinons le code :

C_TEXTE($HTTP_URL;$iso;$post;$response)

$HTTP_URL:="http://ec.europa.eu/taxation_customs/vies/cgi-bin/viesquer"
$iso:=Sous chaine(vVAT;1;2)
$post:="-d \"Lang=FR&MS="+$iso+"&ISO="+$iso+"&VAT="+Sous chaine(vVAT;3)+"\""
$response:=LancerCurl ($post+" "+$HTTP_URL)
Au cas ou 
  : (Position(" TVA valide";$response)>0)
    vResult:="Ce numéro est valide"
  : (Position("TVA Non valide";$response)>0)
    vResult:="Ce numéro n'est pas valide !!!"
  : (Position("La connexion a échoué !!!";$response)>0)
    vResult:="Il y a un problème avec le serveur de TVA"
  Sinon 
    vResult:="Problème avec la connexion web !"+Caractere(13)+Caractere(13)+$response
Fin de cas

Si vous comparez ce code avec le premier exemple, le texte passé est plus complexe et nous pouvons maintenant « analyser » les données reçues. Nous n'avons pas besoin d'un décodeur HTTP pour trouver le texte « Numéro valide » ou « Numéro invalide » dans le document HTML. Et c'est tout ce que nous avons besoin de savoir !

Nous avons pris ce site web pour notre exemple parce qu'il est disponible en une vingtaine de langues, qu'il peut être testé dans le monde entier, et parce que c'est un exemple concret en matière de comptabilité. Nous vous montrerons comment analyser un formulaire web et saisir les données automatiquement.

Tout d'abord, jetons un œil sur la page web :
http://ec.europa.eu/taxation_customs/vies/fr/vieshome.htm

Pour cet exemple, nous vous recommandons d'utiliser Firefox/Mozilla pour les fonctionnalités utiles.

Si vous regardez la page affichée dans le navigateur, vous notez trois champs saisissables et un bouton « Vérifier ». Pour remplir automatiquement les champs du formulaire, nous avons besoin des noms des formulaires HTML. Bien sûr, il est possible de lire le code source HTML, mais avec Firefox il y a une façon de faire plus simple. Faites un clic droit (ou clic contextuel) à l'intérieur de la page et sélectionnez « Voir les informations de la page » (ou « View page info »). Le second onglet du dialogue affiche les variables du formulaire.

Notez que cette page HTML contient deux formulaires. Firefox affiche ces deux formulaires dans la liste ci-dessous : sélectionnez le second formulaire.

La partie inférieure montre que ce formulaire a, outre trois champs que nous avons déjà vus, un champ additionnel de type « hidden » qui renseigne la langue courante de la page web. Il affiche également tous les champs et leur valeur courante.

Il y a différente syntaxe pour un POST HTML mais le principe reste simple. Toutes les variables doivent se suivre les unes à la suite des autres, en utilisant une esperluette « & » pour les séparer.
Par exemple :
Lang=FR&MS=FR&ISO=FR&VAT=72318918851

cURL gère automatiquement le code nécessaire pour créer la requête POST adéquate. L'option « -d » signifie à cURL que c'est une requête de type « POST ». La requête elle-même a besoin d'être énoncée entre guillemets.

Revoici le code :

$post:="-d \"Lang=FR&MS="+$iso+"&ISO="+$iso+"&VAT="+Sous chaine(vVAT;3)+"\""

Le même principe peut être utilisé pour toutes les pages web. La dernière partie de cet exemple montre une tâche plus complexe.

Google permet d'effectuer une recherche d'images. Pour entrer les paramètres de recherche, on utilise un formulaire web. Google se repose sur la gestion des cookies, un Referrer valide et un User-Agent reconnu, sinon le service est refusé. Beaucoup de pages web ne fonctionnent que si les cookies sont supportés et/ou nécessitent un Referrer ou un User-Agent ; c'est pourquoi nous avons choisi ceci pour notre exemple avancé.

Entrez un nom ou un mot dans le champ de recherche et cliquez sur le bouton Chercher. Google va être interrogé et nous renvoyer les vingt premières images (pleine résolution). La durée de la requête dépend de votre connexion Internet et peut prendre un certain temps : 2 à 3 mégaoctets sont chargés à partir de 20 serveurs différents…

Le processus peut être divisé comme suit :
- récupérer des cookies valides de images.google.com ;
- remplir le formulaire et recevoir le résultat ;
- analyser le résultat et retrouver les URL des images ;
- rapatrier les images effectives.

cURL permet d'envoyer des cookies en utilisant l'option « -b mycookie=Hello ».

cURL permet de recevoir des cookies en récupérant l'en-tête complet avec l'option « -i », mais il est encore nécessaire d'analyser l'en-tête manuellement.

Une fonctionnalité vraiment intéressante est de demander à cURL de sauvegarder tous les cookies reçus dans un fichier texte et d'utiliser ce fichier pour de futures requêtes :

$url:="-b cookies.txt -c cookies.txt http://images.google.com/" 
vResultat:=LancerCurl ($url)

L'option -b envoie automatiquement tous les cookies présents dans le fichier texte « cookies.txt » (s'il existe). L'option -c analyse l'en-tête, récupère les cookies et les sauvegarde dans ce même fichier. Cette procédure permet de suivre facilement une session et de gérer complètement et automatiquement l'utilisation des cookies.

Bien que similaire à l'exemple de TVA, il y a trois exceptions :
- l'encodage de texte ;
- le cookie ;
- le Referrer et le User-Agent.

Dans l'exemple ci-dessus, nous avons utilisé un nom avec un espace dans la chaine de la requête. Les espaces ne peuvent pas être envoyés directement, ils doivent être encodés. C'est le cas pour plusieurs caractères et pour tous les caractères ci-dessus, comme les trémas et autres caractères diacritiques. L'encodage s'effectue en valeurs hexadécimales par la conversion vers ISO-8859-1, et préfixé par le caractère '%'.

$dummy:=Mac vers ISO(vSearch) 
$search:=ConvertirChaineEnURL ($dummy)

La base exemple contient également un code pour convertir des chaines en MacRoman vers de l'UTF16 et/ou de l'UTF8 ; certaines pages web requièrent cet encodage.

$url:="http://images.google.com/images?q="+$search+"&hl=en&lr=&btnG=Search+Images"

$data:="-A/-- \"Mozilla/4.0\" -b cookies.txt -e images.google.com "
vResult:=LancerCurl ($data+$url)

Essayez de lancer une recherche Google sur les images, en utilisant un navigateur, et notez l'URL affichée dans le navigateur.

Nous avons simplement reconstruit cette URL et nous l'avons assignée à la variable $url.
L'option -A permet de simuler un User-Agent. Dans cet exemple, nous informons le navigateur web que nous utilisons Microsoft Internet Explorer 4.0.
L'option -b envoie le fichier de cookies et l'option -e renseigne le Referrer.

vResultat a récupéré maintenant le document HTML qui contient toutes les URL des images que nous cherchions.

Il n'est pas nécessaire de construire un analyseur HTML complet pour recevoir les URL. Nous avons seulement besoin de retrouver un en-tête unique pour trouver l'information que nous cherchons. Toutes les images trouvées commencent par « <a href=/imgres?imgurl= ».

TABLEAU TEXTE(arPictURL;0)
$querystring:="<a href=/imgres?imgurl="
$resultat:=vResultat
$pos:=Position($querystring;$resultat)
Tant que ($pos>0)
  $resultat:=Sous chaine($resultat;$pos+Longueur($querystring))
  $pos:=Position("&";$resultat)
  Si ($pos>0)
    $url:=Sous chaine($resultat;1;$pos-1)
    AJOUTER A TABLEAU(arPictURL;$url)
    $resultat:=Sous chaine($resultat;$pos)
    $pos:=Position($querystring;$resultat)
  Fin de si 
Fin tant que 

TABLEAU IMAGE(arPict;0)
FIXER MINUTEUR(1)

Finalement, nous récupérons un tableau arPictURL qui contient toutes les URL des images. Le chargement des images n'a pas été codé dans la méthode objet du bouton, parce que charger 20 images de 20 serveurs différents prend plus ou moins de temps selon la bande passante disponible de la connexion Internet. Pour éviter que l'interface utilisateur ne gèle, le téléchargement a été divisé en plusieurs étapes, et chaque image téléchargée est affichée. Ainsi pour l'utilisateur, il n'y a pas de gel de l'interface et l'activité de la base continue en affichant les données. Pour cela, nous utilisons la fonction FIXER MINUTEUR dans la méthode formulaire.

Méthode formulaire :

Si (Evenement formulaire=Sur minuteur )
  ` utilisé pour la page "Post & Get Picture"
  ` boucle sur les images et download        
  Si (Taille tableau(arPictURL)>Taille tableau(arPict))
     $i:=Taille tableau(arPict)+1
     CHANGER TITRE FENETRE("Téléchargement image "+Chaine($i)+
                           " de "+Chaine(Taille tableau(arPictURL)))
    $url:=arPictURL{$i}
    $pictureblob:=LancerCurlBlob ($url)
    BLOB VERS IMAGE($pictureblob;vpict)
    AJOUTER A TABLEAU(arPict;vpict)
  Sinon 
    FIXER MINUTEUR(0) ` fini
    vPict:=arPict{1}
    CHANGER TITRE FENETRE("")
  Fin de si 
 
Fin de si

Cette note technique a survolé les fonctionnalités les plus utilisées et la procédure pour remplir un formulaire web automatiquement. Mais cURL peut faire plus encore.

Voir site :
http://curl.haxx.se/

Jetez un œil à la documentation:
http://curl.haxx.se/docs/

ou encore à ces autres exemples :
http://curl.haxx.se/docs/manpage.html
http://curl.haxx.se/docs/httpscripting.html

L'outil gratuit de FireFox/Mozilla est également une aide précieuse pour comprendre comment communiquer entre le navigateur web et le server :
http://livehttpheaders.mozdev.org

Si une tâche automatisée de cURL ne fonctionne pas, c'est souvent parce que vous avez oublié d'installer ou de lire les cookies, de donner un bon Referrer ou une erreur de ce genre. Trouver le problème s'avère parfois difficile parce que la communication entre cURL et le serveur web est invisible.

Un « sniffer » (par exemple Ethereal pour Windows et Mac OS X ; pour MacOS X, voir aussi MacSniffer) peut aider énormément, mais peut aussi rendre le problème confus s'il y a beaucoup trop de données échangées.

La solution commerciale « HTTPLook » pour Windows (démo disponible sur freedownloadscenter ou ShareUp) enregistre tous les paquets HTTP provenant d'un navigateur, de cURL ou des Internet Commandes de 4D. C'est une aide formidable pour de tels problèmes.

cURL doit être installé sur toutes les machines clientes. L'installeur se compose d'un seul fichier .exe, sans avoir besoin de DLL ou d'entrée de registre pour exécuter les fonctions du noyau. Nous vous recommandons de l'installer dans le dossier 4D Extras pour que les ressources soient automatiquement dupliquées sur les 4D Clients.

Le chemin du dossier/application peut être retourné par le code suivant :

$path:=Dossier 4D(Dossier Extras )
$path:=$path+"cURL.exe"

Dans la base exemple, c'est la version 7.15.4 Non SSL qui est préinstallée. Il s'agit de la version la plus récente au moment de la publication de cette note. L'archive est également fournie.

Pour une version plus récente (pour toutes plateformes), veuillez vous référer à l'adresse suivante :
http://curl.haxx.se/download.html

Il y a également une version SSL disponible. Cette version requiert l'installation de OpenSSL. OpenSSL peut être téléchargé à partir de ce même site web : défilez jusqu'à « OpenSSL binary packages » et téléchargez le fichier Zip pour Windows. OpenSSL est open source et peut être distribué, à condition de suivre les conditions du contrat de licence (vous devez ajouter des informations dans vos dialogues de licence, dans votre documentation et dans la fenêtre « À propos de… »).

Si vous voulez utiliser les fonctionnalités LDAP, vous devrez installer des librairies supplémentaires.

Télécharger la base exemple et la version de Curl utilisée dans cette note technique.