This is an old revision of the document!
Table of Contents
Remote Plugins
Note: This plugin type is develonly |
---|
Remote plugins enables you to add methods that can be accessed via various web services (currently xmlrpc only).
How to write a remote plugin?
You have to add the remote.php
to your plugin folder. There are only three things you have to do there:
- Your plugin class must inherit from DokuWiki_Remote_Plugin.
- Implement _getMethods correctly.
- write your methods.
A simple skeleton is:
- remote.php
<?php class remote_plugin_time extends DokuWiki_Remote_Plugin { function _getMethods() { return array( 'getTime' => array( 'args' => array(), 'return' => 'date' ) ); } function getTime() { return $this->getApi()->toDate(time()); } }
Writing your methods
Simple write your methods. You can take parameters and give results back. DokuWiki will take care that you get the right parameter and your result will be handled correctly.
The only thing you cannot use as parameter and return values are objects. The only allowed types are: array
and primitive types.
Beside these types there are two special types, file and date. These type have to be encoded using the $this→getApi()→toDate()
respectively $this→getApi()→toFile()
.
The toDate
method takes an unix timestamp. The toFile
method takes a string with the file content.
Security
The API will take care of basic security checks, i.e. user is logged in and user can access the web service. Every more detailed access, like per page, has to be done by the plugin.
Take a look at the rawPage
method from inc/RemoteAPICore.php
function rawPage($id,$rev=''){ $id = cleanID($id); if(auth_quickaclcheck($id) < AUTH_READ){ throw new RemoteAccessDeniedException('You are not allowed to read this file', 111); } $text = rawWiki($id,$rev); if(!$text) { return pageTemplate($id); } else { return $text; } }
Here is the auth_qucikaclcheck
function used to check the permission on a page id.
Errors
When an error occurs you have to throw an instance of RemoteException
. Beside the RemoteException
is the RemoteAccessDeniedException
to signal wrong permissions.
The _getMethods Method
The _getMethods
method returns an array with the following structure:
'remoteName' => array( 'args' => array('type eg. string|int|...|date|file',), ['name' => 'method name in class',] 'return' => 'type', 'public' => 1/0 - method bypass default group check (used by login) ['doc' = 'method documentation'], ), [next method]
- remoteName
- Name of the method on remote interface. Your call will look like
plugin.<your plugin name>.<given remoteName>
.
- args
- array of possible parameter types. types can be: string, int, double, bool, date, file.
- name (optional)
- if the real name of the method divides from the remoteName you have to set it in the name field.
- return
- return type of the method.
- public
- possible values 1 or 0: on 1 it will bypass the default group check and allow access to the call. This is used i.e. by the remote login method.
- doc (optional)
- Optional documentation string.
Note: It is possible to have two entries in the _getMethods
array for one method.
Custom remote names
In some circumstances you need a full custom name for the remote call. The RPC_CALL_ADD event allows you to map a custom name to a remoteName of your plugin.