From f401bea1f3345c748b46976895c1ceecad6f6258 Mon Sep 17 00:00:00 2001
From: Neil Drumm <drumm@3064.no-reply.drupal.org>
Date: Tue, 16 May 2006 06:56:49 +0000
Subject: [PATCH] #63782 by jvandyk, More documentation for xmlrpc.inc
---
includes/xmlrpc.inc | 79 ++++++++++++++++++++++++++++++++++++++-------
1 file changed, 68 insertions(+), 11 deletions(-)
diff --git a/includes/xmlrpc.inc b/includes/xmlrpc.inc
index fcf7d8624d44..4db993798ee3 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 '<boolean>'. (($xmlrpc_value->data) ? '1' : '0') .'</boolean>';
@@ -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>'. base64_encode($xmlrpc_base64->data) .'</base64>';
}
+/**
+ * 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;
}
-
--
GitLab