From f401bea1f3345c748b46976895c1ceecad6f6258 Mon Sep 17 00:00:00 2001 From: Neil Drumm Date: Tue, 16 May 2006 06:56:49 +0000 Subject: #63782 by jvandyk, More documentation for xmlrpc.inc --- includes/xmlrpc.inc | 79 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 68 insertions(+), 11 deletions(-) (limited to 'includes/xmlrpc.inc') diff --git a/includes/xmlrpc.inc b/includes/xmlrpc.inc index fcf7d8624..4db993798 100644 --- a/includes/xmlrpc.inc +++ b/includes/xmlrpc.inc @@ -9,6 +9,16 @@ This version is made available under the GNU GPL License */ +/** + * Recursively turn a data structure into objects with 'data' and 'type' attributes. + * + * @param $data + * The data structure. + * @param $type + * Optional type assign to $data. + * @return + * Object. + */ function xmlrpc_value($data, $type = FALSE) { $xmlrpc_value = new stdClass(); $xmlrpc_value->data = $data; @@ -17,7 +27,7 @@ function xmlrpc_value($data, $type = FALSE) { } $xmlrpc_value->type = $type; if ($type == 'struct') { - /* Turn all the values in the array in to new xmlrpc_values */ + // Turn all the values in the array into new xmlrpc_values foreach ($xmlrpc_value->data as $key => $value) { $xmlrpc_value->data[$key] = xmlrpc_value($value); } @@ -69,8 +79,14 @@ function xmlrpc_value_calculate_type(&$xmlrpc_value) { return 'string'; } +/** + * Generate XML representing the given value. + * + * @param $xmlrpc_value + * @return + * XML representation of value. + */ function xmlrpc_value_get_xml($xmlrpc_value) { - /* Return XML for this value */ switch ($xmlrpc_value->type) { case 'boolean': return ''. (($xmlrpc_value->data) ? '1' : '0') .''; @@ -113,26 +129,43 @@ function xmlrpc_value_get_xml($xmlrpc_value) { return FALSE; } +/** + * Construct an object representing an XML-RPC message. + * + * @param $message + * String containing XML as defined at http://www.xmlrpc.com/spec + * @return + * Object + */ function xmlrpc_message($message) { $xmlrpc_message = new stdClass(); $xmlrpc_message->array_structs = array(); // The stack used to keep track of the current array/struct - $xmlrpc_message->array_structs_types = array(); // Stack keeping track of if things are structs or array + $xmlrpc_message->array_structs_types = array(); // The stack used to keep track of if things are structs or array $xmlrpc_message->current_struct_name = array(); // A stack as well $xmlrpc_message->message = $message; return $xmlrpc_message; } +/** + * Parse an XML-RPC message. If parsing fails, the faultCode and faultString + * will be added to the message object. + * + * @param $xmlrpc_message + * Object generated by xmlrpc_message() + * @return + * TRUE if parsing succeeded; FALSE otherwise + */ function xmlrpc_message_parse(&$xmlrpc_message) { - // first remove the XML declaration + // First remove the XML declaration $xmlrpc_message->message = preg_replace('/<\?xml(.*)?\?'.'>/', '', $xmlrpc_message->message); if (trim($xmlrpc_message->message) == '') { return FALSE; } $xmlrpc_message->_parser = xml_parser_create(); - // Set XML parser to take the case of tags in to account + // Set XML parser to take the case of tags into account xml_parser_set_option($xmlrpc_message->_parser, XML_OPTION_CASE_FOLDING, FALSE); // Set XML parser callback functions - /* do not set object. $xmlrpc_message does not have member functions any more + /* Do not set object. $xmlrpc_message does not have member functions any more xml_set_object($xmlrpc_message->_parser, $xmlrpc_message); */ xml_set_element_handler($xmlrpc_message->_parser, 'xmlrpc_message_tag_open', 'xmlrpc_message_tag_close'); xml_set_character_data_handler($xmlrpc_message->_parser, 'xmlrpc_message_cdata'); @@ -150,6 +183,14 @@ function xmlrpc_message_parse(&$xmlrpc_message) { return TRUE; } +/** + * Store a copy of the $xmlrpc_message object temporarily. + * + * @param $value + * Object + * @return + * The most recently stored $xmlrpc_message + */ function xmlrpc_message_set($value = NULL) { static $xmlrpc_message; if ($value) { @@ -172,7 +213,7 @@ function xmlrpc_message_tag_open($parser, $tag, $attr) { case 'fault': $xmlrpc_message->messagetype = $tag; break; - /* Deal with stacks of arrays and structs */ + // Deal with stacks of arrays and structs case 'data': $xmlrpc_message->array_structs_types[] = 'array'; $xmlrpc_message->array_structs[] = array(); @@ -214,7 +255,7 @@ function xmlrpc_message_tag_close($parser, $tag) { $value_flag = TRUE; break; case 'value': - // If no type is indicated, the type is string. + // If no type is indicated, the type is string // We take special care for empty values if (trim($xmlrpc_message->current_tag_contents) != '' || $xmlrpc_message->last_open == 'value') { $value = (string)$xmlrpc_message->current_tag_contents; @@ -230,7 +271,7 @@ function xmlrpc_message_tag_close($parser, $tag) { $value = base64_decode(trim($xmlrpc_message->current_tag_contents)); $value_flag = TRUE; break; - /* Deal with stacks of arrays and structs */ + // Deal with stacks of arrays and structs case 'data': case 'struct': $value = array_pop($xmlrpc_message->array_structs ); @@ -270,6 +311,16 @@ function xmlrpc_message_tag_close($parser, $tag) { xmlrpc_message_set($xmlrpc_message); } +/** + * Construct an object representing an XML-RPC request + * + * @param $method + * The name of the method to be called + * @param $args + * An array of parameters to send with the method. + * @return + * Object + */ function xmlrpc_request($method, $args) { $xmlrpc_request = new stdClass(); $xmlrpc_request->method = $method; @@ -365,6 +416,13 @@ function xmlrpc_base64_get_xml($xmlrpc_base64) { return ''. base64_encode($xmlrpc_base64->data) .''; } +/** + * Execute an XML remote procedural call. This is private function; call xmlrpc() + * in common.inc instead of this functino. + * + * @return + * A $xmlrpc_message object if the call succeeded; FALSE if the call failed + */ function _xmlrpc() { $args = func_get_args(); $url = array_shift($args); @@ -389,7 +447,7 @@ function _xmlrpc() { // Now parse what we've got back if (!xmlrpc_message_parse($message)) { // XML error - xmlrpc_error(-32700, t('parse error. not well formed')); + xmlrpc_error(-32700, t('Parse error. Not well formed')); return FALSE; } // Is the message a fault? @@ -416,4 +474,3 @@ function xmlrpc_error_msg() { $error = xmlrpc_error(); return $error->message; } - -- cgit v1.2.3