Extensions

XRL supporte plusieurs extensions par rapport à la spécification XML-RPC originale. Ces extensions sont connues pour être bien supportées par les autres implémentations et pour ne pas rentrer en conflit avec la spécification originale en général.

Extensions supportées

getCapabilities

L”extension getCapabilities a été créée pour deux raisons :

  • Pour permettre aux serveurs XML-RPC d’annoncer les fonctionnalités (non-standards) qu’ils supportent.
  • Pour fournir un moyen simple clients XML-RPC d’adapter leur comportement en fonction des fonctionnalités non-standards supportées par un serveur.

Les serveurs XRL implémentent les méthodes additionnelles suivantes lorsque cette extension est activée :

  • system.getCapabilities

introspection

L’extension introspection permet à un client d’obtenir des informations à propos d’une procédure distante en interrogeant le serveur XML-RPC qui la fournit.

Les serveurs XRL implémentent les méthodes additionnelles suivantes lorsque cette extension est activée :

  • system.listMethods
  • system.methodSignature
  • system.methodHelp

multicall

L’extension multicall a été créée afin d’attenuer la latence introduite par les allers-retours HTTP lorsque plusieurs appels de méthodes sont envoyés au même serveur XML-RPC.

Les serveurs XRL implémentent les méthodes additionnelles suivantes lorsque cette extension est activée :

  • system.multicall

faults_interop

L’extension faults_interop contient les spécifications de codes correspondant à des cas d’erreurs standards, afin d’encourager l’interopérabilité entre les implémentations XML-RPC.

Cette extension est toujouts activée et n’ajoute aucune méthode supplémentaire aux serveurs XML-RPC. Un développeur désireux d’utiliser les erreurs interopérables définies dans cette extension peut lever l’exception associée dans l’espace de noms \fpoirotte\XRL\Faults.

$server->error = function () {
    throw new \fpoirotte\XRL\Faults\SystemErrorException();
};

Les exceptions suivantes peuvent être utilisées pour représenter une erreur interopérable :

  • ApplicationErrorException
  • InternalErrorException
  • InvalidCharacterException
  • InvalidParameterException
  • InvalidXmlRpcException
  • MethodNotFoundException
  • NotWellFormedException
  • SystemErrorException
  • TransportErrorException
  • UnsupportedEncodingException

Par ailleurs, l’exception ImplementationDefinedErrorException peut être utilisée pour les erreurs propres à l’implémentation. Notez cependant qu’un code d’erreur conforme à la spécification doit être passé explicitement lors de la création d’une telle erreur.

$server->error = function () {
    throw new \fpoirotte\XRL\Faults\ImplementationDefinedErrorException(
        -32000,                 // Implementation-defined error code
        "You're out of memory"  // Implementation-defined error message
    );
};

Types Apache

L’extension des types Apache est un peu spéciale. Elle n’ajoute pas de nouvelles méthodes. À la place, elle définit de nouveaux types XML-RPC.

Cette extensions est toujours activée. Lisez également la documentation sur les types XML-RPC supportés pour plus d’information sur ces types et la manière dont ils sont utilisés dans XRL.

Activer les extensions

Par défaut, XRL n’active que quelques extensions (plus précisément, les extensions faults_interop et Apache types).

Pour activer le reste des extensions, vous devez appeler \fpoirotte\XRL\CapableServer::enable() sur le serveur :

// Create a regular XML-RPC server.
$server = new \fpoirotte\XRL\Server();

// Enable additional extensions (capabilities) for that server.
\fpoirotte\XRL\CapableServer::enable($server);

Note

Il n’est pas possible actuellement d’activer séparément chaque extension en utilisant \fpoirotte\XRL\CapableServer::enable(). C’est une situation de type « tout ou rien ».