From 6a45180c95baaddedafacf1780de2670c5a6a44a Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Sun, 10 Apr 2011 11:19:45 -0400 Subject: [PATCH] Clarify docs for g_dbus_gvalue_to_gvariant() and g_dbus_gvariant_to_gvalue() Signed-off-by: David Zeuthen --- gio/gdbusutils.c | 77 +++++++++++++++++++++++++++++--------------------------- gio/gdbusutils.h | 2 +- 2 files changed, 41 insertions(+), 38 deletions(-) diff --git a/gio/gdbusutils.c b/gio/gdbusutils.c index 3960f95..35dc217 100644 --- a/gio/gdbusutils.c +++ b/gio/gdbusutils.c @@ -355,17 +355,15 @@ g_dbus_is_guid (const gchar *string) /** * g_dbus_gvariant_to_gvalue: * @value: A #GVariant. - * @out_gvalue: Return location for the #GValue. + * @out_gvalue: Return location pointing to a zero-filled (uninitialized) #GValue. * - * Convert a #GVariant to a #GValue. If @value is floating, it is consumed. + * Converts a #GVariant to a #GValue. If @value is floating, it is consumed. * - * The rules specified in g_dbus_gvalue_to_gvariant() are used. + * The rules specified in the g_dbus_gvalue_to_gvariant() function are + * used - this function is essentially its reverse form. * - * Note that the passed @out_gvalue does not have to have a #GType - * set, as it will be initialized to the #GType corresponding to - * @value. - * - * This conversion can never fail. + * The conversion never fails - a valid #GValue is always returned in + * @out_gvalue. * * Since: 2.30 */ @@ -500,9 +498,9 @@ g_dbus_gvariant_to_gvalue (GVariant *value, /** * g_dbus_gvalue_to_gvariant: * @gvalue: A #GValue to convert to a #GVariant. - * @expected_type: The #GVariantType to create. + * @type: A #GVariantType. * - * Convert a #GValue to #GVariant. + * Converts a #GValue to a #GVariant of the type indicated by the @type parameter. * * The conversion is using the following rules: * @@ -511,49 +509,49 @@ g_dbus_gvariant_to_gvalue (GVariant *value, * * * If the #GType for @gvalue is... - * ... then @expected_type must be + * ... then @type must be * * * * * #G_TYPE_STRING - * s, o, g, ay + * 's', 'o', 'g' or 'ay' * * * #G_TYPE_STRV - * as, aay + * 'as' or 'aay' * * * #G_TYPE_BOOLEAN - * b + * 'b' * * * #G_TYPE_UCHAR - * y + * 'y' * * * #G_TYPE_INT - * i, n + * 'i' or 'n' * * * #G_TYPE_UINT - * u, q + * 'u' or 'q' * * * #G_TYPE_INT64 - * x + * 'x' * * * #G_TYPE_UINT64 - * t + * 't' * * * #G_TYPE_INT - * h + * 'h' * * * #G_TYPE_DOUBLE - * d + * 'd' * * * #G_TYPE_VARIANT @@ -562,25 +560,29 @@ g_dbus_gvariant_to_gvalue (GVariant *value, * * *
- * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and - * @expected_type is 'i'. It will also fail for any - * #GType (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED - * derived-types) not in the table above. + * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type + * is 'i'. It will + * also fail for any #GType (including e.g. #G_TYPE_OBJECT and + * #G_TYPE_BOXED derived-types) not in the table above. * * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is * %NULL, the empty #GVariant instance (never - * %NULL) for @expected_type is returned (e.g. 0 for scalar types, the - * empty string for string types and so on). + * %NULL) for @type is returned (e.g. 0 for scalar types, the empty + * string for string types, '/' for object path + * types, the empty array for any array type and so on). + * + * See the g_dbus_gvariant_to_gvalue() function for how to convert a + * #GVariant to a #GValue. * * Returns: A #GVariant (never floating) of #GVariantType - * @expected_type holding the data from @gvalue or %NULL in case of + * @type holding the data from @gvalue or %NULL in case of * failure. Free with g_variant_unref(). * * Since: 2.30 */ GVariant * -g_dbus_gvalue_to_gvariant (const GValue *gvalue, - const GVariantType *expected_type) +g_dbus_gvalue_to_gvariant (const GValue *gvalue, + const GVariantType *type) { GVariant *ret; const gchar *s; @@ -588,12 +590,13 @@ g_dbus_gvalue_to_gvariant (const GValue *gvalue, const gchar *empty_strv[1] = {NULL}; g_return_val_if_fail (gvalue != NULL, NULL); - g_return_val_if_fail (expected_type != NULL, NULL); + g_return_val_if_fail (type != NULL, NULL); ret = NULL; - /* The expected type could easily be e.g. "s" with the GValue holding a string. - * because of the UseGVariant annotation + /* @type can easily be e.g. "s" with the GValue holding a GVariant - for example this + * can happen when using the org.gtk.GDBus.C.ForceGVariant annotation with the + * gdbus-codegen(1) tool. */ if (G_VALUE_TYPE (gvalue) == G_TYPE_VARIANT) { @@ -601,7 +604,7 @@ g_dbus_gvalue_to_gvariant (const GValue *gvalue, } else { - switch (g_variant_type_peek_string (expected_type)[0]) + switch (g_variant_type_peek_string (type)[0]) { case G_VARIANT_CLASS_BOOLEAN: ret = g_variant_ref_sink (g_variant_new_boolean (g_value_get_boolean (gvalue))); @@ -665,7 +668,7 @@ g_dbus_gvalue_to_gvariant (const GValue *gvalue, break; case G_VARIANT_CLASS_ARRAY: - switch (g_variant_type_peek_string (expected_type)[1]) + switch (g_variant_type_peek_string (type)[1]) { case G_VARIANT_CLASS_BYTE: s = g_value_get_string (gvalue); @@ -682,7 +685,7 @@ g_dbus_gvalue_to_gvariant (const GValue *gvalue, break; case G_VARIANT_CLASS_ARRAY: - switch (g_variant_type_peek_string (expected_type)[2]) + switch (g_variant_type_peek_string (type)[2]) { case G_VARIANT_CLASS_BYTE: as = g_value_get_boxed (gvalue); @@ -719,7 +722,7 @@ g_dbus_gvalue_to_gvariant (const GValue *gvalue, if (ret == NULL) { GVariant *untrusted_empty; - untrusted_empty = g_variant_new_from_data (expected_type, NULL, 0, FALSE, NULL, NULL); + untrusted_empty = g_variant_new_from_data (type, NULL, 0, FALSE, NULL, NULL); ret = g_variant_ref_sink (g_variant_get_normal_form (untrusted_empty)); g_variant_unref (untrusted_empty); } diff --git a/gio/gdbusutils.h b/gio/gdbusutils.h index 73a827f..a05a230 100644 --- a/gio/gdbusutils.h +++ b/gio/gdbusutils.h @@ -42,7 +42,7 @@ gboolean g_dbus_is_interface_name (const gchar *string); void g_dbus_gvariant_to_gvalue (GVariant *value, GValue *out_gvalue); GVariant *g_dbus_gvalue_to_gvariant (const GValue *gvalue, - const GVariantType *expected_type); + const GVariantType *type); G_END_DECLS -- 2.7.4