#63782 by jvandyk, More documentation for xmlrpc.inc

1 files changed, 68 insertions, 11 deletions

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 '<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;
 }
-