[libsoup/wip/xmlrpc-variant: 5/11] fixup! xmlrpc: Add GVariant (de)serializer

[Dan Winship <danw src gnome org>]

commit 00638fb69ef7685495c8531c08d63758b0f1016a
Author: Dan Winship <danw gnome org>
Date:   Thu Aug 6 08:27:51 2015 -0400

    fixup! xmlrpc: Add GVariant (de)serializer

 libsoup/soup-xmlrpc.c |   76 +++++++++++++++++++++++++-----------------------
 1 files changed, 40 insertions(+), 36 deletions(-)
---
diff --git a/libsoup/soup-xmlrpc.c b/libsoup/soup-xmlrpc.c
index b388a07..c13f133 100644
--- a/libsoup/soup-xmlrpc.c
+++ b/libsoup/soup-xmlrpc.c
@@ -250,15 +250,15 @@ fail:
  *
  * Serialization details:
  *  - "a{s*}" and "{s*}" are serialized as &lt;struct&gt;
- *  - "ay" are serialized as &lt;base64&gt;
+ *  - "ay" is serialized as &lt;base64&gt;
  *  - Other arrays and tuples are serialized as &lt;array&gt;
  *  - booleans are serialized as &lt;boolean&gt;
  *  - byte, int16, uint16 and int32 are serialized as &lt;int&gt;
- *  - uint32 and int64 are serialized as nonstandard &lt;i8&gt;
+ *  - uint32 and int64 are serialized as the nonstandard &lt;i8&gt; type
  *  - doubles are serialized as &lt;double&gt;
- *  - Strings, object-paths and signatures are serialized as &lt;string&gt;
+ *  - Strings (including object-paths and signatures) are serialized as &lt;string&gt;
  *  - Variants (i.e. "v" type) are unwrapped and their child is serialized.
- *  - #GVariant created by soup_xmlrpc_new_datetime() are serialized as
+ *  - #GVariants created by soup_xmlrpc_new_datetime() are serialized as
  *    &lt;dateTime.iso8601&gt;
  *  - Other types are not supported and will return %NULL and set @error.
  *    This notably includes: uint64, maybes and dictionaries with non-string
@@ -270,7 +270,7 @@ fail:
  * Since: 2.52
  **/
 char *
-soup_xmlrpc_build_request (const char *method_name,
+soup_xmlrpc_build_request (const char  *method_name,
                           GVariant    *params,
                           GError     **error)
 {
@@ -282,14 +282,9 @@ soup_xmlrpc_build_request (const char *method_name,
        int len;
        char *body = NULL;
 
-       g_variant_ref_sink (params);
+       g_return_val_if_fail (g_variant_is_of_type (params, G_VARIANT_TYPE_TUPLE), NULL);
 
-       if (!g_variant_is_of_type (params, G_VARIANT_TYPE_TUPLE)) {
-               g_set_error (error, SOUP_XMLRPC_ERROR, SOUP_XMLRPC_ERROR_ARGUMENTS,
-                            "params must be a tuple but is %s",
-                            g_variant_get_type_string (params));
-               goto fail;
-       }
+       g_variant_ref_sink (params);
 
        doc = xmlNewDoc ((const xmlChar *)"1.0");
        doc->standalone = FALSE;
@@ -321,7 +316,6 @@ soup_xmlrpc_build_request (const char *method_name,
        xmlFreeDoc (doc);
        g_variant_unref (params);
 
-fail:
        return body;
 }
 
@@ -340,12 +334,13 @@ fail:
  * If @params is floating, it is consumed.
  *
  * Returns: (transfer full): a #SoupMessage encoding the
- *  indicated XML-RPC request, or %NULL on error.
+ *   indicated XML-RPC request, or %NULL on error.
+ *
  * Since: 2.52
  **/
 SoupMessage *
-soup_xmlrpc_message_new (const char *uri,
-                        const char *method_name,
+soup_xmlrpc_message_new (const char  *uri,
+                        const char  *method_name,
                         GVariant    *params,
                         GError     **error)
 {
@@ -371,11 +366,14 @@ soup_xmlrpc_message_new (const char *uri,
  * as a string. To create a fault response, use soup_xmlrpc_build_fault(). This
  * is the low-level method that soup_xmlrpc_message_set_response() is built on.
  *
- * See soup_xmlrpc_build_request() for serialization details.
+ * See soup_xmlrpc_build_request() for serialization details, but note
+ * that since a method can only have a single return value, @value
+ * should not be a tuple here (unless the return value is an array).
  *
  * If @value is floating, it is consumed.
  *
  * Returns: the text of the methodResponse, or %NULL on error.
+ *
  * Since: 2.52
  **/
 char *
@@ -430,6 +428,7 @@ soup_xmlrpc_build_response (GVariant *value, GError **error)
  * If @value is floating, it is consumed.
  *
  * Returns: %TRUE on success, %FALSE otherwise.
+ *
  * Since: 2.52
  **/
 gboolean
@@ -988,8 +987,9 @@ fail:
 /**
  * SoupXMLRPCParams:
  *
- * Opaque structure containing an XML-RPC value. Can be parsed using
- * soup_xmlrpc_params_parse() and freed with soup_xmlrpc_params_free().
+ * Opaque structure containing XML-RPC methodCall parameter values.
+ * Can be parsed using soup_xmlrpc_params_parse() and freed with
+ * soup_xmlrpc_params_free().
  *
  * Since: 2.52
  */
@@ -1038,12 +1038,13 @@ soup_xmlrpc_params_new (xmlNode *node)
  * See soup_xmlrpc_parse_request_full() for deserialization details.
  *
  * Returns: (transfer full): a new #GVariant, or %NULL
+ *
  * Since: 2.52
  */
 GVariant *
-soup_xmlrpc_params_parse (SoupXMLRPCParams *self,
-                         const char      *signature,
-                         GError          **error)
+soup_xmlrpc_params_parse (SoupXMLRPCParams  *self,
+                         const char        *signature,
+                         GError           **error)
 {
        GVariant *value = NULL;
 
@@ -1077,25 +1078,24 @@ fail:
  *
  * Parses @method_call and return the method name. Method parameters can be
  * parsed later using soup_xmlrpc_params_parse(). If the signature of parameters
- * is known in advance then soup_xmlrpc_parse_request_full() could be used
+ * is known in advance then soup_xmlrpc_parse_request_full() can be used
  * instead.
  *
  * Returns: (transfer full): method's name, or %NULL on error.
  * Since: 2.52
  **/
 char *
-soup_xmlrpc_parse_request (const char *method_call,
-                          int length,
+soup_xmlrpc_parse_request (const char        *method_call,
+                          int                length,
                           SoupXMLRPCParams **params,
-                          GError **error)
+                          GError           **error)
 {
        xmlDoc *doc = NULL;
        xmlNode *node;
        xmlChar *xmlMethodName = NULL;
        char *method_name = NULL;
 
-       doc = xmlParseMemory (method_call,
-                                 length == -1 ? strlen (method_call) : length);
+       doc = xmlParseMemory (method_call, length == -1 ? strlen (method_call) : length);
        if (!doc) {
                g_set_error (error, SOUP_XMLRPC_ERROR, SOUP_XMLRPC_ERROR_ARGUMENTS,
                             "Could not parse XML document");
@@ -1158,8 +1158,8 @@ fail:
  * Deserialization details:
  *  - If @signature is provided, &lt;int&gt and &lt;i4&gt can be deserialized
  *    to byte, int16, uint16, int32, uint32, int64, uint64 or handle. Otherwise
- *    it will be int32. If the value is out of range for the target type it will
- *    return an @error.
+ *    it will be deserialized to int32. If the value is out of range
+ *    for the target type it will return an error.
  *  - &lt;struct&gt; will be deserialized to "a{sv}". @signature could define
  *    another value type (e.g. "a{ss}").
  *  - &lt;array&gt; will be deserialized to "av". @signature could define
@@ -1168,16 +1168,17 @@ fail:
  *  - &lt;string&gt; will be deserialized to "s". @signature could define
  *    another type ("o" or "g").
  *  - &lt;dateTime.iso8601&gt; will be deserialized to int64 unix timestamp.
- *  - @signature must not have maybes, otherwise an @error is returned.
- *  - Dictionaries must have string keys, otherwise an @error is returned.
+ *  - @signature must not have maybes, otherwise an error is returned.
+ *  - Dictionaries must have string keys, otherwise an error is returned.
  *
  * Returns: (transfer full): method's name, or %NULL on error.
+ *
  * Since: 2.52
  **/
 char *
-soup_xmlrpc_parse_request_full (const char *method_call,
-                               int         length,
-                               const char *signature,
+soup_xmlrpc_parse_request_full (const char  *method_call,
+                               int          length,
+                               const char  *signature,
                                GVariant   **parameters,
                                GError     **error)
 {
@@ -1218,7 +1219,8 @@ soup_xmlrpc_parse_request_full (const char *method_call,
  *
  * See soup_xmlrpc_parse_request_full() for deserialization details.
  *
- * Returns: (transfer full): a new #GVariant, or %NULL
+ * Returns: (transfer full): a new (non-floating) #GVariant, or %NULL
+ *
  * Since: 2.52
  **/
 GVariant *
@@ -1312,6 +1314,7 @@ fail:
  * node containing @value. See soup_xmlrpc_build_request().
  *
  * Returns: a floating #GVariant.
+ *
  * Since: 2.52
  */
 GVariant *
@@ -1329,6 +1332,7 @@ soup_xmlrpc_new_custom (const char *type, const char *value)
  * node. See soup_xmlrpc_build_request().
  *
  * Returns: a floating #GVariant.
+ *
  * Since: 2.52
  */
 GVariant *