From 2b8edf234c9f1926ca2b24bf431fc1c8dc7c4ecf Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 21 Nov 2013 17:39:16 +0000 Subject: [PATCH] gvariant: Document the need to cast varargs when constructing GVariants MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Slightly expand on the documentation about casting varargs when constructing GVariants, and link to it from all the functions where it’s a necessary consideration. Add an example of passing flags to a ‘t’ type variable (guint64). Assuming the flags enum does not have many members, the flag variable will be 32 bits wide, and needs an explicit cast to be passed into g_variant_new() as a 64-bit value. https://bugzilla.gnome.org/show_bug.cgi?id=712837 --- docs/reference/glib/gvariant-varargs.xml | 1 + glib/gvariant-parser.c | 12 ++++++++++++ glib/gvariant.c | 23 +++++++++++++++++++++++ 3 files changed, 36 insertions(+) diff --git a/docs/reference/glib/gvariant-varargs.xml b/docs/reference/glib/gvariant-varargs.xml index 3f34d53..550cea0 100644 --- a/docs/reference/glib/gvariant-varargs.xml +++ b/docs/reference/glib/gvariant-varargs.xml @@ -466,6 +466,7 @@ + Note that in C, small integer types in variable argument lists are promoted up to int or unsigned int as appropriate, and diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c index 128523c..7617f34 100644 --- a/glib/gvariant-parser.c +++ b/glib/gvariant-parser.c @@ -2428,6 +2428,10 @@ g_variant_parse (const GVariantType *type, * #GVariant pointer will be returned unmodified, without adding any * additional references. * + * Note that the arguments in @app must be of the correct width for their types + * specified in @format when collected into the #va_list. See + * the GVariant varargs documentation. + * * In order to behave correctly in all cases it is necessary for the * calling function to g_variant_ref_sink() the return result before * returning control to the user that originally provided the pointer. @@ -2481,6 +2485,10 @@ g_variant_new_parsed_va (const gchar *format, * that case, the same arguments are collected from the argument list as * g_variant_new() would have collected. * + * Note that the arguments must be of the correct width for their types + * specified in @format. This can be achieved by casting them. See + * the GVariant varargs documentation. + * * Consider this simple example: * |[ * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); @@ -2530,6 +2538,10 @@ g_variant_new_parsed (const gchar *format, * calling g_variant_new_parsed() followed by * g_variant_builder_add_value(). * + * Note that the arguments must be of the correct width for their types + * specified in @format_string. This can be achieved by casting them. See + * the GVariant varargs documentation. + * * This function might be used as follows: * * |[ diff --git a/glib/gvariant.c b/glib/gvariant.c index e5f23c4..93d2278 100644 --- a/glib/gvariant.c +++ b/glib/gvariant.c @@ -5168,6 +5168,21 @@ g_variant_valist_get (const gchar **str, * 'r'; in essence, a new #GVariant must always be constructed by this * function (and not merely passed through it unmodified). * + * Note that the arguments must be of the correct width for their types + * specified in @format_string. This can be achieved by casting them. See + * the GVariant varargs documentation. + * + * + * MyFlags some_flags = FLAG_ONE | FLAG_TWO; + * const gchar *some_strings[] = { "a", "b", "c", NULL }; + * GVariant *new_variant; + * + * new_variant = g_variant_new ("(t^as)", + * /* This cast is required. */ + * (guint64) some_flags, + * some_strings); + * + * * Returns: a new floating #GVariant instance * * Since: 2.24 @@ -5214,6 +5229,10 @@ g_variant_new (const gchar *format_string, * @format_string, are collected from this #va_list and the list is left * pointing to the argument following the last. * + * Note that the arguments in @app must be of the correct width for their types + * specified in @format_string when collected into the #va_list. See + * the GVariant varargs documentation. + * * These two generalisations allow mixing of multiple calls to * g_variant_new_va() and g_variant_get_va() within a single actual * varargs call by the user. @@ -5365,6 +5384,10 @@ g_variant_get_va (GVariant *value, * This call is a convenience wrapper that is exactly equivalent to * calling g_variant_new() followed by g_variant_builder_add_value(). * + * Note that the arguments must be of the correct width for their types + * specified in @format_string. This can be achieved by casting them. See + * the GVariant varargs documentation. + * * This function might be used as follows: * * |[ -- 2.7.4