diff options
author | Dries Buytaert <dries@buytaert.net> | 2010-07-31 04:17:34 +0000 |
---|---|---|
committer | Dries Buytaert <dries@buytaert.net> | 2010-07-31 04:17:34 +0000 |
commit | ad41c41fe4587518bfc66de19124bcedf1c43ebd (patch) | |
tree | 0e8df8f9ab4fae0405f2ba6ee6ba52ca12385847 /includes/xmlrpcs.inc | |
parent | a94519077bae9c7a38c20cd8d46dc76805110ad1 (diff) | |
download | brdo-ad41c41fe4587518bfc66de19124bcedf1c43ebd.tar.gz brdo-ad41c41fe4587518bfc66de19124bcedf1c43ebd.tar.bz2 |
- Patch #855420 by jhodgdon, aspilicious: documentation cleanup for xmlrpcs.inc and add missing documentation headers.
Diffstat (limited to 'includes/xmlrpcs.inc')
-rw-r--r-- | includes/xmlrpcs.inc | 108 |
1 files changed, 82 insertions, 26 deletions
diff --git a/includes/xmlrpcs.inc b/includes/xmlrpcs.inc index 469d65f32..7fb4ca895 100644 --- a/includes/xmlrpcs.inc +++ b/includes/xmlrpcs.inc @@ -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(); |