Xml rpc

Principes de xml-rpc

1. un message en xml est construit, il contient un nom de méthode et des paramètres
2. ce message est envoyé vers une URL
3. cette url correspond à un script (en PHP par exemple), qui va analyser le message reçu. il execute alors la méthode indiquée en lui donnant les paramètres reçus
4. une réponse est ensuite renvoyée : elle indique un message d'erreur ou des valeurs résultats, toujours sous forme XML.

Bien sûr, les messages XML ont un format précis, normalisée. Pour en savoir plus sur le format, lire les spécifications de XML-RPC ou en version française.

Cependant, vous n'avez pas besoin de connaître le format. Des composants XPCom (réalisé en Javascript) se chargent de formater les messages, de faire les appels et de recevoir la reponse.

Les objets XPCOM pour XML-Rpc

interfaces

Il y a trois interfaces disponibles :

• nsIXmlRpcClient
• nsIXmlRpcClientListener
• nsIXmlRpcFault

Elles sont implémentées dans les composants @mozilla.org/xml-rpc/client;1 et @mozilla.org/xml-rpc/fault;1

Comme c'est réalisé en javascript, vous pouvez regarder leur code source dans <votre repertoire mozilla>/components/nsXmlRpcClient.js. Disponible également en ligne http://mozblog.mozdev.org/nsXmlRpcClient(..).

La référence des interfaces et des composants sont disponibles sur xulplanet :

• http://www.xulplanet.com/references/xpco(..)
• http://www.xulplanet.com/references/xpco(..)
• http://www.xulplanet.com/references/xpco(..)
• http://www.xulplanet.com/references/xpco(..)
• http://www.xulplanet.com/references/xpco(..)

Utilisation

Vous avez un excellent petit tutoriel sur phpPattern : http://www.phppatterns.com/index.php/art(..)

Voici en résumé comment on fait :

instanciation d'un client xml-rpc

 var xmlRpcClient;

 netscape.security.PrivilegeManager.enablePrivilege('UniversalXPConnect UniversalBrowserAccess');
 xmlRpcClient = Components.classes['@mozilla.org/xml-rpc/client;1'].createInstance(
	Components.interfaces.nsIXmlRpcClient);

 xmlRpcClient.init('http://lesite.com/service_rpc.php');

déclaration d'un handler

Il faut déclarer un objet handler qui sera appelé pour traiter les divers évenements qui vont survenir durant l'appel. Il doit contenir trois méthodes :

• onResult : appelé quand un résultat valide est reçu
• onFault : appelé si le client xmlrpc a reçu un resultat signalant une faute
• onError : appelé quand une erreur survient

 var monHandler = {
   // Param0: l'objet xmlrpcclient
   // Param1: le paramètre arg1 de asyncCall (voir plus loin)
   // Param2: le résultat xmlrpc
   onResult: function(client, argumentAsyncall, resultat) {
   ... // ici traitement du résultat
   },

   // Param0: l'objet xmlrpcclient
   // Param1: le paramètre arg1 de asyncCall (voir plus loin)
   // Param2: la chaine  erreur
   onFault: function (client, argumentAsyncall, faute) {
     alert('faute XML-RPC : '+faute);
   },

   // Param0: l'objet xmlrpcclient
   // Param1: le paramètre arg1 de asyncCall (voir plus loin)
   // Param2: code statut XPCOM
   // Param3: message d'erreur
   onError: function (client, argumentAsyncall, status, errorMsg) {
     alert('Error: '+erreurMsg);
   }
 };

création des paramètres

Il se peut que vous ayez des paramètres à indiquer à la méthode xmlrpc. Pour cela, il va falloir créer ces paramètres en indiquant leur type.

Ici, on crée un argument de type chaine et un autre de type entier :

  var parametre1 = xmlRpcClient.createType(xmlRpcClient.STRING,{});
  parametre1.data='test';

  var parametre2 = xmlRpcClient.createType(xmlRpcClient.INT,{});
  parametre2.data=2;

D'autres types existent :

• BOOLEAN
• DOUBLE
• DATETIME
• ARRAY
• STRUCT

appel d'une méthode xml-rpc

  xmlRpcClient.asyncCall(arg0, arg1, arg2, arg3, arg4);

• arg0 : l'objet handler à utiliser
• arg1 : un objet quelconque utilisé par l'objet handler (NULL si il n'y en a pas)
• arg2 : le nom de la méthode xml-rpc à appeler
• arg3 : liste des arguments à passer à la méthode
• arg4 : nombre d'arguments

exemple :

 xmlRpcClient.asyncCall(monHandler, null, 'testRPC', [parametre1, parametre2], 2);

On appelle la méthode xmlrpc 'testRPC', en lui passant 2 paramètres, parametre1 et parametre2, en spécifiant que la réponse sera traité par l'objet monHandler déclaré plus haut (et il ne recevra pas de paramètre puisque arg2 est à null).