Retourner des images par Service Web (via SOAP)

4e Dimension version 2003 et ultérieure, propose la publication de méthodes comme Services Web. Concrètement les requêtes et réponses de Services Web sont des messages SOAP (Simple Object Access Protocol) qui suivent les règles d’encodage des données XML. 4e Dimension propose la conversion automatique de pratiquement tous les types natifs 4D pour envoi dans une réponse SOAP, à l’exception des images. Heureusement, il est possible d’inclure des BLOBs dans les réponses SOAP de sorte qu’il est possible d’inclure des images en les convertissant au préalable à l’aide de la commande IMAGE VERS BLOB.

Le retour d’images via SOAP est utile dans plusieurs situations, par exemple les scénarios suivants :

• un système de publication Web demande des images statiques ou dynamiques par SOAP pour les inclure dans des pages Web ;
• un système de base de données centralisé 4e Dimension joue le rôle d’une bibliothèque d’images ou d’archivage pour un nombre indéterminé de clients SOAP ;
• un système de base de données centralisé 4e Dimension jour le rôle de pivot de distribution d’images pour un nombre indéterminé de clients.

Cette note technique détaille les mécanismes de conversion et « d’empaquetage » d’images dans les réponses SOAP. La base de démo comprend du code fonctionnel réalisant un système simple de serveur d’images reposant sur SOAP.

Le serveur d’image accomplit les tâches suivantes :

• écouter et répondre aux requêtes SOAP ;
• fournir une liste des images disponibles ;
• fournir une liste des formats d’images possibles ;
• charger, convertir et retourner les images.

Nous allons commenter chacune de ces tâches plus en détail.

Pour publier des méthodes comme Services Web, les conditions suivantes doivent être remplies :

1. Le serveur Web natif de 4e Dimension doit fonctionner ;
2. Les préférences ci-dessous doivent être activées :
   Préférences -> Web -> Web Services -> Autoriser requêtes Web Services ;
3. La propriété ci-dessous doit être activée pour chaque méthode publiée :
   Propriétés de la méthode/Offert comme Web Service.

Une fois ces étapes de configuration effectuées, 4e Dimension gère automatiquement tous les aspects d’écoute et de réponse aux requêtes SOAP.

Table Image▲

La démo propose des images stockées dans une table nommée [Images], représentée ci-dessous :

Le champ Name sert de clé unique pour les enregistrements de la table. En environnement de production, une clé du type entier long unique et non modifiable serait un meilleur choix. Une version améliorée du système pourrait gérer des attributs supplémentaires comme la date de prise de la photo, des notes sur le matériel photo et les réglages utilisés, le lieu de la prise de vue, des informations de contact, des mots-clés et le détail de la licence.

GetPictureList▲

TOUT SELECTIONNER([Images])
TRIER([Images];[Images]Name)
TABLEAU ALPHA(80;getPicture_ImageNames_as;0)
SELECTION VERS TABLEAU([Images]Name;getPicture_ImageNames_as)
LIBERER ENREGISTREMENT([Images])

DECLARATION SOAP(getPicture_ImageNames_as;Est un tableau chaîne ;SOAP sortie ;"outPictureNames")

Fournir une liste des formats d’images disponibles▲

TABLEAU TEXTE(getPictureFormatMimeTypes_at;0)
COPIER TABLEAU(<>pictureFormatMimeTypes_at;getPictureFormatMimeTypes_at)
DECLARATION SOAP(getPictureFormatMimeTypes_at;Est un tableau texte ;SOAP sortie ;"outSupportedMIMETypes")

   ` -----------------------------------------------------
   ` Réception des codes d’images depuis Quicktime
   ` -----------------------------------------------------
TABLEAU ALPHA(4;<>pictureFormatCodes_as;0)
LISTE TYPES IMAGES(<>pictureFormatCodes_as)

   ` -----------------------------------------------------
   ` Ajout de 'GIFf', si non présent, car il des supporté directement par 4D
   ` -----------------------------------------------------
C_ENTIER LONG($index)
$index:=0
$index:=Chercher dans tableau(<>pictureFormatCodes_as;"GIFf") `GIF ne requiert pas Quicktime
Si ($index<1)
   INSERER LIGNES(<>pictureFormatCodes_as;1;1)
   <>pictureFormatCodes_as{1}:="GIFf"
Fin de si


   ` -----------------------------------------------------
   ` Construction d’un tableau des types MIME
   ` -----------------------------------------------------
C_ENTIER LONG($count)
$count:=0
$count:=Taille tableau(<>pictureFormatCodes_as)

TABLEAU TEXTE(<>pictureFormatMimeTypes_at;$count)

C_ALPHA(4;$type_s)
Boucle ($index;$count;1;-1) ` Bouclons à l’envers, car il se peut que nous détruisions des éléments en chemin
   $type_s:=<>pictureFormatCodes_as{$index}
   CHERCHER([Picture_Format_Codes];[Picture_Format_Codes]Code=$type_s)

   Si (Enregistrements trouves([Picture_Format_Codes])=1)
      <>pictureFormatMimeTypes_at{$index}:=[Picture_Format_Codes]MIME_Type
   Sinon
      SUPPRIMER LIGNES(<>pictureFormatCodes_as;$index;1)
      SUPPRIMER LIGNES(<>pictureFormatMimeTypes_at;$index;1)
   Fin de si

LIBERER ENREGISTREMENT([Picture_Format_Codes])

Fin de boucle

La démo propose plusieurs fonctions de Services Web pour retourner des images et des données sur les images. La plus simple est la méthode getPicture publiée comme méthode SOAP getPicture. La méthode attend deux paramètres d’entrée, un nom d’image et un type MIME d’image. Un développeur de client de Service Web peut découvrir les valeurs acceptées pour ces deux arguments en appelant les fonctions GetPictureList et GetPictureFormatList. Cette approche permet aux clients de construire dynamiquement et interactivement des requêtes valides afin d’obtenir des images dans des formats spécifiques.

Ci-dessous une version résumée de la méthode getPicture :

   ` -----------------------------------------------------
   ` Déclare les entrées/sorties pour 4DWSDL et la construction du message SOAP
   ` -----------------------------------------------------
DECLARATION SOAP($1;Est un texte ;SOAP entrée ;"inPictureName")
DECLARATION SOAP($2;Est un texte ;SOAP entrée ;"inPictureMimeType")
DECLARATION SOAP(getPicture_ResultPicture_x;Est un BLOB ;SOAP sortie ;"outPictureBlob")

   ` -----------------------------------------------------
   ` Déclare les paramètres pour l’exécution et la compilation
   ` -----------------------------------------------------
C_TEXTE($1;$pictureName_t)
C_TEXTE($2;$pictureMimeType_t)

   ` -----------------------------------------------------
   ` Prépare les valeurs de retour
   ` -----------------------------------------------------
C_BLOB(getPicture_ResultPicture_x)
   ` <-- variable de sortie (nous n’utilisons pas $0 car les images peuvent être importantes)
FIXER TAILLE BLOB(getPicture_ResultPicture_x;0)

   ` -----------------------------------------------------
   ` Effectue le contrôle d’erreur sur les entrées
   ` -----------------------------------------------------
C_ENTIER LONG($errorCode_l)
$errorCode_l:=0

C_ENTIER LONG($soapFaultType_l)
$soapFaultType_l:=SOAP erreur client

Si (Nombre de parametres<2)
   $errorCode_l:=1 ` Pas assez de paramètres

Sinon
   $pictureName_t:=$1
   $pictureMimeType_t:=$2
   CHERCHER([Images];[Images]Name=$pictureName_t)
   C_ALPHA(4;$format_s)
   $format_s:=""
   $format_s:=pictureGet4DCodeFromMimeType ($pictureMimeType_t)

   Au cas ou
      : ($format_s="")
      $errorCode_l:=2 ` Type MIME demandé non supporté ou non reconnu
      : (Enregistrements trouves([Images])=0)
      $errorCode_l:=3 ` Image demandée non trouvée
      : (Enregistrements trouves([Images])>1)
      $errorCode_l:=4 ` Trouvé plusieurs images
   Fin de cas

Fin de si ` (Nombre de parametres<2)


Si ($errorCode_l=0)
   ` -----------------------------------------------------
   ` Corps de la méthode
   ` -----------------------------------------------------
   ` Pas de $0 nécessaire. 4D lit les déclarations de sortie SOAP et retourne les valeurs des variables
   IMAGE VERS BLOB([Images]Picture;getPicture_ResultPicture_x;$format_s)
   LIBERER ENREGISTREMENT([Images])
Fin de si

Si ($errorCode_l#0)
   C_TEXTE($errorText_t)
   $errorText_t:=getPictureErrorText ($errorCode_l)
   ENVOYER ERREUR SOAP($soapFaultType_l;$errorText_t)
Fin de si

Les BLObs inclus dans les messages SOAP sont convertis en textes base64 pour le transfert. Dans 4e Dimension retrouver l’image initiale s’effectue simplement, comme le montre l’exemple de méthode proxy de client SOAP ci-dessous :

C_TEXTE($1;$name_t)
C_TEXTE($2;$mimeType_t)
C_POINTEUR($3;$picture_p)
$name_t:=$1
$mimeType_t:=$2
$picture_p:=$3
FIXER PARAMETRE WEB SERVICE("inPictureName";$name_t)
FIXER PARAMETRE WEB SERVICE("inPictureMimeType";$mimeType_t)

APPELER WEB SERVICE(requestGetAccessURL ;"ReturningPicturesWithSoap#getPicture";
"getPicture";"http://www.4d.com/namespace/default";Web Service dynamique )

Si (OK=1)
   C_BLOB($pictureBlob_x)
   LIRE RESULTAT WEB SERVICE($pictureBlob_x;"outPictureBlob";*) ` Nettoyage mémoire
   BLOB VERS IMAGE($pictureBlob_x;$picture_p->)

   ` NOTE:
   ` BLOB VERS IMAGE peut seulement convertir les formats compatibles Quickime 4 et au-delà
   ` Par exemple, les images MacPaint ( code = 'PNTG', MIME type = image/x-macpaint)
   ` ne sont pas toujours converties correctement. Dans de tels cas, le BLOB est formé correctement,
   ` mais l’image résultante est vide. Si vous disposez d’autres codes de traitement d’images ou d’un plug-in
   ` vous pouvez les appliquer au BLOB au lieu d’utiliser BLOB VERS IMAGE
Fin de si

La table [Images] de la base de données de démo comprend plusieurs attributs de l’image : hauteur, largeur, taille brute, auteurs et description. En utilisant SOAP, il est facile d’écrire des méthodes qui retournent l’un ou plusieurs de ces attributs à la fois. Ces fonctions permettent aux clients SOAP d’agir plus intelligemment et sélectivement. Par exemple, demander une vignette avant de charger des images lourdes, préconstruire les balises HTML d’images avec les largeurs et hauteurs ou charger une description de l’image, tout cela est possible simplement avec les Services Web.

La démo implémente quelques-unes de ces idées avec les commandes décrites ci-dessous :

• getPictureDate retourne une description de l’image, de sa taille, sa largeur, sa hauteur et des auteurs ;
• getPictureListExtended étend la commande getPictureList pour inclure la description, la taille, la largeur, la hauteur et les auteurs de chaque image ;
• getPictureWithType retourne l’image avec son code de type MIME ;
• getThumbnail retourne une vignette de l’image générée dynamiquement.

Téléchargez les bases exemples :

Base 4D 2004

Base 4D 2003 Windows

Base 4D 2003 MacOS