Commit ad41c41f authored by Dries's avatar Dries

- Patch #855420 by jhodgdon, aspilicious: documentation cleanup for...

- Patch #855420 by jhodgdon, aspilicious: documentation cleanup for xmlrpcs.inc and add missing documentation headers.
parent a9451907
......@@ -7,9 +7,9 @@
*/
/**
* The main entry point for XML-RPC requests.
* Invokes XML-RPC methods on this server.
*
* @param $callbacks
* @param array $callbacks
* Array of external XML-RPC method names with the callbacks they map to.
*/
function xmlrpc_server($callbacks) {
......@@ -99,12 +99,13 @@ function xmlrpc_server($callbacks) {
}
/**
* Throw an XML-RPC error.
* Throws an XML-RPC error.
*
* @param $error
* an error object OR integer error code
* An error object or integer error code.
* @param $message
* description of error, used only if integer error code was passed
* (optional) The description of the error. Used only if an integer error
* code was passed in.
*/
function xmlrpc_server_error($error, $message = FALSE) {
if ($message && !is_object($error)) {
......@@ -113,6 +114,12 @@ function xmlrpc_server_error($error, $message = FALSE) {
xmlrpc_server_output(xmlrpc_error_get_xml($error));
}
/**
* Sends XML-RPC output to the browser.
*
* @param string $xml
* XML to send to the browser.
*/
function xmlrpc_server_output($xml) {
$xml = '<?xml version="1.0"?>' . "\n" . $xml;
drupal_add_http_header('Content-Length', strlen($xml));
......@@ -122,10 +129,16 @@ function xmlrpc_server_output($xml) {
}
/**
* Store a copy of the request temporarily.
* Stores a copy of an XML-RPC request temporarily.
*
* @param object $xmlrpc_server
* (optional) Request object created by xmlrpc_server(). Omit to leave the
* previous server object saved.
*
* @param $xmlrpc_server
* Request object created by xmlrpc_server().
* @return
* The latest stored request.
*
* @see xmlrpc_server_get()
*/
function xmlrpc_server_set($xmlrpc_server = NULL) {
static $server;
......@@ -135,21 +148,31 @@ function xmlrpc_server_set($xmlrpc_server = NULL) {
return $server;
}
// Retrieve the stored request.
/**
* Retrieves the latest stored XML-RPC request.
*
* @return object
* The stored request.
*
* @see xmlrpc_server_set()
*/
function xmlrpc_server_get() {
return xmlrpc_server_set();
}
/**
* Dispatch the request and any parameters to the appropriate handler.
* Dispatches an XML-RPC request and any parameters to the appropriate handler.
*
* @param object $xmlrpc_server
* Object containing information about this XML-RPC server, the methods it
* provides, their signatures, etc.
* @param string $methodname
* The external XML-RPC method name; e.g., 'system.methodHelp'.
* @param array $args
* Array containing any parameters that are to be sent along with the request.
*
* @param $xmlrpc_server
* Contains information about this XML-RPC server, the methods it provides,
* their signatures, etc.
* @param $methodname
* The external XML-RPC method name, e.g. 'system.methodHelp'
* @param $args
* Array containing any parameters that were sent along with the request.
* @return
* The results of the call.
*/
function xmlrpc_server_call($xmlrpc_server, $methodname, $args) {
// Make sure parameters are in an array
......@@ -222,6 +245,20 @@ function xmlrpc_server_call($xmlrpc_server, $methodname, $args) {
return call_user_func_array($method, $args);
}
/**
* Dispatches multiple XML-RPC requests.
*
* @param array $methodcalls
* An array of XML-RPC requests to make. Each request is an array with the
* following elements:
* - methodName: Name of the method to invoke.
* - params: Parameters to pass to the method.
*
* @return
* An array of the results of each request.
*
* @see xmlrpc_server_call()
*/
function xmlrpc_server_multicall($methodcalls) {
// See http://www.xmlrpc.com/discuss/msgReader$1208
$return = array();
......@@ -254,7 +291,12 @@ function xmlrpc_server_multicall($methodcalls) {
}
/**
* Lists the methods available on this XML-RPC server.
*
* XML-RPC method system.listMethods maps to this function.
*
* @return array
* Array of the names of methods available on this server.
*/
function xmlrpc_server_list_methods() {
$xmlrpc_server = xmlrpc_server_get();
......@@ -262,8 +304,13 @@ function xmlrpc_server_list_methods() {
}
/**
* Returns a list of the capabilities of this server.
*
* XML-RPC method system.getCapabilities maps to this function.
*
* @return array
* Array of server capabilities.
*
* @see http://groups.yahoo.com/group/xml-rpc/message/2897
*/
function xmlrpc_server_get_capabilities() {
......@@ -288,16 +335,20 @@ function xmlrpc_server_get_capabilities() {
}
/**
* XML-RPC method system.methodSignature maps to this function.
* Returns the method signature of a function.
*
* @param $methodname
* Name of method for which we return a method signature.
* This is the function mapped to the XML-RPC method system.methodSignature.
*
* @return
* An array of types representing the method signature of the
* function that the methodname maps to. The methodSignature of
* this function is 'array', 'string' because it takes an array
* and returns a string.
* A method signature is an array of the input and output types of a method. For
* instance, the method signature of this function is array('array', 'string'),
* because it takes an array and returns a string.
*
* @param string $methodname
* Name of method to return a method signature for.
*
* @return array
* An array of types representing the method signature of the function that
* $methodname maps to.
*/
function xmlrpc_server_method_signature($methodname) {
$xmlrpc_server = xmlrpc_server_get();
......@@ -316,10 +367,15 @@ function xmlrpc_server_method_signature($methodname) {
}
/**
* Returns the help for an XML-RPC method.
*
* XML-RPC method system.methodHelp maps to this function.
*
* @param $method
* @param string $method
* Name of method for which we return a help string.
*
* @return string
* Help text for $method.
*/
function xmlrpc_server_method_help($method) {
$xmlrpc_server = xmlrpc_server_get();
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment