# Jabber-RPC Module
A strophe plugin for Jabber-RPC extension ([XEP-0009](http://xmpp.org/extensions/xep-0009.html)).
See the XEP abstract :
> This specification defines an XMPP protocol extension for transporting XML-RPC encoded requests and responses between two XMPP entities. The protocol supports all syntax and semantics of XML-RPC except that it uses XMPP instead of HTTP as the underlying transport.
This plugin does not aim at managing your flow of RPC. It is a simple helper to send and handle remote requests between two XMPP nodes.
## Usage
Just link the rpc plugin below the strophe library in your HTML head section:
``` html
```
It's preferable to also use the service discovery plugin to respond correctly to `disco#info` requests. You can [download it](https://github.com/metajack/strophejs-plugins/tree/master/disco) and add it as follow :
``` html
```
## API
The plugin prototype is accessible from the `connection.rpc` variable
### Send an RPC
There are four functions to send RPC :
- `sendRequest(id, to, method, params)`
- `method` is the string name of the method to call
- `params` is an array of parameters to send
- `sendResponse(id, to, result)`
- `result` is the object to send as the result of the request
- `sendError(id, to, code, message)`
- `code` is the number of the error
- `message` is the message describing the error
- `sendXMLElement(id, to, xml)`
- `xml` is the XML Element that will be sent (whether it is properly formed or not)
The parameters `id` and `to` are respectively the id of the request and the the jid of the recipient.
### Handle incoming RPCs
It is possible to handle incoming RPCs using the functions :
- `addRequestHandler`
- `addResponseHandler`
- `addXMLHandler`
The handlers you pass to these functions take different parameters :
```javascript
var responseHandler = function(id, from, result, error) {
// error is a boolean
// it is true if the response was an error message
if (error === true) { ... }
else { ... }
}
connection.rpc.addResponseHandler(responseHandler);
var requestHandler = function(id, from, method, parameters) { ... }
connection.rpc.addRequestHandler(requestHandler);
var xmlHandler = function(xml) { ... }
connection.rpc.addXMLHandler(xmlHandler)
```
Note that the parser of this module won't throw any exception. However `result`, `method` and `parameters` will be set as `null` if the incoming message is not XML-RPC compliant.
### Whitelist
By default, this plugin will accept RPC from everyone. However, it is possible to use a whitelist of JID to filter incoming RPCs.
Use the function `addJidToWhiteList` to accept JIDs. Note that it is possible to use a wildcard for the node or the domain.
Examples :
```javascript
connection.rpc.addJidToWhiteList("me@jabber.org");
connection.rpc.addJidToWhiteList(["*@jabber.org", "me@*"]);
connection.rpc.addJidToWhiteList("*@*");
```
## Tests & specs
I use the node module `buster` for the tests. Install it and use it as follow :
```bash
$ npm install buster
$ buster server
```
Open a browser and navigate to `http://localhost:1111` and capture the browser.
Then you can run the tests:
```
$ buster test --browser
```