Commit da750215 authored by Dries's avatar Dries

- Patch #855418 by jhodgdon, aspilicious: fix doc errors in xmlcpr.inc and...

- Patch #855418 by jhodgdon, aspilicious: fix doc errors in xmlcpr.inc and fill in the missing doc headers.
parent e65cb2df
......@@ -13,14 +13,15 @@
*/
/**
* Turn a data structure into objects with 'data' and 'type' attributes.
* Turns a data structure into objects with 'data' and 'type' attributes.
*
* @param $data
* The data structure.
* @param $type
* Optional type assign to $data.
* @return
* Object.
* Optional type to assign to $data.
*
* @return object
* An XML-RPC data object containing the input $data.
*/
function xmlrpc_value($data, $type = FALSE) {
$xmlrpc_value = new stdClass();
......@@ -44,16 +45,19 @@ function xmlrpc_value($data, $type = FALSE) {
}
/**
* Map PHP type to XML-RPC type.
* Maps a PHP type to an XML-RPC type.
*
* @param $xmlrpc_value
* Variable whose type should be mapped.
* @return
* XML-RPC type as string.
*
* @return string
* The corresponding XML-RPC type.
*
* @see http://www.xmlrpc.com/spec#scalars
*/
function xmlrpc_value_calculate_type($xmlrpc_value) {
// http://www.php.net/gettype: Never use gettype() to test for a certain type [...] Instead, use the is_* functions.
// http://www.php.net/gettype: Never use gettype() to test for a certain type
// [...] Instead, use the is_* functions.
if (is_bool($xmlrpc_value->data)) {
return 'boolean';
}
......@@ -82,12 +86,13 @@ function xmlrpc_value_calculate_type($xmlrpc_value) {
}
/**
* Generate XML representing the given value.
* Generates XML representing the given value.
*
* @param $xmlrpc_value
* A value to be represented in XML.
*
* @return
* XML representation of value.
* XML representation of $xmlrpc_value.
*/
function xmlrpc_value_get_xml($xmlrpc_value) {
switch ($xmlrpc_value->type) {
......@@ -133,12 +138,15 @@ function xmlrpc_value_get_xml($xmlrpc_value) {
}
/**
* Construct an object representing an XML-RPC message.
* Constructs an object representing an XML-RPC message.
*
* @param $message
* String containing XML as defined at http://www.xmlrpc.com/spec
* @return
* Object
* A string containing an XML message.
*
* @return object
* An XML-RPC object containing the message.
*
* @see http://www.xmlrpc.com/spec
*/
function xmlrpc_message($message) {
$xmlrpc_message = new stdClass();
......@@ -156,9 +164,10 @@ function xmlrpc_message($message) {
* object.
*
* @param $xmlrpc_message
* Object generated by xmlrpc_message()
* An object generated by xmlrpc_message().
*
* @return
* TRUE if parsing succeeded; FALSE otherwise
* TRUE if parsing succeeded; FALSE otherwise.
*/
function xmlrpc_message_parse($xmlrpc_message) {
$xmlrpc_message->_parser = xml_parser_create();
......@@ -186,12 +195,15 @@ function xmlrpc_message_parse($xmlrpc_message) {
}
/**
* Store a copy of the $xmlrpc_message object temporarily.
* Stores a copy of the most recent XML-RPC message object temporarily.
*
* @param $value
* Object
* @return
* The most recently stored $xmlrpc_message
* An XML-RPC message to store, or NULL to keep the last message.
*
* @return object
* The most recently stored message.
*
* @see xmlrpc_message_get()
*/
function xmlrpc_message_set($value = NULL) {
static $xmlrpc_message;
......@@ -201,10 +213,21 @@ function xmlrpc_message_set($value = NULL) {
return $xmlrpc_message;
}
/**
* Returns the most recently stored XML-RPC message object.
*
* @return object
* The most recently stored message.
*
* @see xmlrpc_message_set()
*/
function xmlrpc_message_get() {
return xmlrpc_message_set();
}
/**
* Handles opening tags for XML parsing in xmlrpc_message_parse().
*/
function xmlrpc_message_tag_open($parser, $tag, $attr) {
$xmlrpc_message = xmlrpc_message_get();
$xmlrpc_message->current_tag_contents = '';
......@@ -228,12 +251,18 @@ function xmlrpc_message_tag_open($parser, $tag, $attr) {
xmlrpc_message_set($xmlrpc_message);
}
/**
* Handles character data for XML parsing in xmlrpc_message_parse().
*/
function xmlrpc_message_cdata($parser, $cdata) {
$xmlrpc_message = xmlrpc_message_get();
$xmlrpc_message->current_tag_contents .= $cdata;
xmlrpc_message_set($xmlrpc_message);
}
/**
* Handles closing tags for XML parsing in xmlrpc_message_parse().
*/
function xmlrpc_message_tag_close($parser, $tag) {
$xmlrpc_message = xmlrpc_message_get();
$value_flag = FALSE;
......@@ -314,14 +343,15 @@ function xmlrpc_message_tag_close($parser, $tag) {
}
/**
* Construct an object representing an XML-RPC request
* Constructs an object representing an XML-RPC request.
*
* @param $method
* The name of the method to be called
* The name of the method to be called.
* @param $args
* An array of parameters to send with the method.
* @return
* Object
*
* @return object
* An XML-RPC object representing the request.
*/
function xmlrpc_request($method, $args) {
$xmlrpc_request = new stdClass();
......@@ -344,7 +374,20 @@ function xmlrpc_request($method, $args) {
return $xmlrpc_request;
}
/**
* Generates, temporarily saves, and returns an XML-RPC error object.
*
* @param $code
* The error code.
* @param $message
* The error message.
* @param $reset
* TRUE to empty the temporary error storage. Ignored if $code is supplied.
*
* @return object
* An XML-RPC error object representing $code and $message, or the most
* recently stored error object if omitted.
*/
function xmlrpc_error($code = NULL, $message = NULL, $reset = FALSE) {
static $xmlrpc_error;
if (isset($code)) {
......@@ -359,6 +402,15 @@ function xmlrpc_error($code = NULL, $message = NULL, $reset = FALSE) {
return $xmlrpc_error;
}
/**
* Converts an XML-RPC error object into XML.
*
* @param $xmlrpc_error
* The XML-RPC error object.
*
* @return string
* An XML representation of the error as an XML methodResponse.
*/
function xmlrpc_error_get_xml($xmlrpc_error) {
return <<<EOD
<methodResponse>
......@@ -381,6 +433,15 @@ function xmlrpc_error_get_xml($xmlrpc_error) {
EOD;
}
/**
* Converts a PHP or ISO date/time to an XML-RPC object.
*
* @param $time
* A PHP timestamp or an ISO date-time string.
*
* @return object
* An XML-RPC time/date object.
*/
function xmlrpc_date($time) {
$xmlrpc_date = new stdClass();
$xmlrpc_date->is_date = TRUE;
......@@ -407,10 +468,28 @@ function xmlrpc_date($time) {
return $xmlrpc_date;
}
/**
* Converts an XML-RPC date-time object into XML.
*
* @param $xmlrpc_date
* The XML-RPC date-time object.
*
* @return string
* An XML representation of the date/time as XML.
*/
function xmlrpc_date_get_xml($xmlrpc_date) {
return '<dateTime.iso8601>' . $xmlrpc_date->year . $xmlrpc_date->month . $xmlrpc_date->day . 'T' . $xmlrpc_date->hour . ':' . $xmlrpc_date->minute . ':' . $xmlrpc_date->second . '</dateTime.iso8601>';
}
/**
* Returns an XML-RPC base 64 object.
*
* @param $data
* Base 64 data to store in returned object.
*
* @return object
* An XML-RPC base 64 object.
*/
function xmlrpc_base64($data) {
$xmlrpc_base64 = new stdClass();
$xmlrpc_base64->is_base64 = TRUE;
......@@ -418,34 +497,38 @@ function xmlrpc_base64($data) {
return $xmlrpc_base64;
}
/**
* Converts an XML-RPC base 64 object into XML.
*
* @param $xmlrpc_base64
* The XML-RPC base 64 object.
*
* @return string
* An XML representation of the base 64 data as XML.
*/
function xmlrpc_base64_get_xml($xmlrpc_base64) {
return '<base64>' . base64_encode($xmlrpc_base64->data) . '</base64>';
}
/**
* Performs one or more XML-RPC request(s).
* Performs one or more XML-RPC requests.
*
* @param $url
* An absolute URL of the XML-RPC endpoint.
* Example:
* http://www.example.com/xmlrpc.php
* The absolute URL of the XML-RPC endpoint. Example:
* http://www.example.com/xmlrpc.php
* @param ...
* For one request:
* The method name followed by a variable number of arguments to the
* method.
* For multiple requests (system.multicall):
* An array of call arrays. Each call array follows the pattern of the
* single request: method name followed by the arguments to the method.
* @return
* Either the return value of the method on success, or FALSE. If FALSE is
* returned, see xmlrpc_errno() and xmlrpc_error_msg().
* - For a non-multicall request: the result just as if this had been a local
* function call.
* - For a multicall request: an array of results. Each result will either be
* a one-element array containing the result returned by the method called,
* or an xmlrpc_error object if the call failed.
* - For one request: The method name followed by a variable number of
* arguments to the method.
* - For multiple requests (system.multicall): An array of call arrays. Each
* call array follows the pattern of the single request: method name
* followed by the arguments to the method.
*
* @see xmlrpc_error()
* @return
* A single response (single request) or an array of responses (multicall
* request). Each response is the return value of the method, just as if it
* has been a local function call, on success, or FALSE on failure. If FALSE
* is returned, see xmlrpc_errno() and xmlrpc_error_msg() to get more
* information.
*/
function _xmlrpc() {
$args = func_get_args();
......@@ -505,7 +588,7 @@ function _xmlrpc() {
}
/**
* Returns the last XML-RPC client error number
* Returns the last XML-RPC client error number.
*/
function xmlrpc_errno() {
$error = xmlrpc_error();
......@@ -513,7 +596,7 @@ function xmlrpc_errno() {
}
/**
* Returns the last XML-RPC client error message
* Returns the last XML-RPC client error message.
*/
function xmlrpc_error_msg() {
$error = xmlrpc_error();
......@@ -521,7 +604,9 @@ function xmlrpc_error_msg() {
}
/**
* Clears any previous error.
* Clears any previously-saved errors.
*
* @see xmlrpc_error()
*/
function xmlrpc_clear_error() {
xmlrpc_error(NULL, NULL, TRUE);
......
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