class: GVariantBuilder

[15:7] extends: object

A utility type for constructing container-type #GVariant instances. This is an opaque structure and may only be accessed using the following functions. #GVariantBuilder is not threadsafe in any way. Do not attempt to access it from more than one thread.

Members

handleObj
lib
retainedCallbacks
signalHandlerNames
signalSetterHandlers

Methods

GVariantBuilder (type = null)

Allocates and initialises a new #GVariantBuilder. You should call g_variant_builder_unref() on the return value when it is no longer needed. The memory will not be automatically freed by any other call. In most cases it is easier to place a #GVariantBuilder directly on the stack of the calling function and initialise it with g_variant_builder_init_static().
- @p type is a container type.
toNativeHandle (Source)

Normalizes a constructor argument into a raw pointer carrier. Accepts a raw NativeHandle, a raw NativeBuffer returned from fn.call(...), another generated wrapper exposing handle(), or null. Returns null when the argument carries no pointer.
- @p Source is the raw handle, raw buffer, wrapper, or null.
- @r A raw pointer carrier or null when no pointer is present.
getLib ()

Returns the opened native library for this generated wrapper.
- @r The opened native library.
handle ()

Returns the wrapped NativeHandle.
- @r The wrapped NativeHandle.
isNull ()

Returns true when the wrapped handle is null.
- @r A bool.
describe ()

Returns a small string for debugging generated wrappers.
- @r A string.
add (string format_string, list varargs)

Adds to a #GVariantBuilder. 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: |[ GVariant * make_pointless_dictionary (void) { GVariantBuilder builder; int i; g_variant_builder_init_static (&builder, G_VARIANT_TYPE_ARRAY); for (i = 0; i < 16; i++) { gchar buf[3]; sprintf (buf, "%d", i); g_variant_builder_add (&builder, "{is}", i, buf); } return g_variant_builder_end (&builder); } ]|
- @p format_string is a #GVariant varargs format string.
- @p ... is arguments, as per @format_string.
- @r None.
add_parsed (string format, list varargs)

Adds to a #GVariantBuilder. This call is a convenience wrapper that is exactly equivalent to 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: |[ GVariant * make_pointless_dictionary (void) { GVariantBuilder builder; int i; g_variant_builder_init_static (&builder, G_VARIANT_TYPE_ARRAY); g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); return g_variant_builder_end (&builder); } ]|
- @p format is a text format #GVariant.
- @p ... is arguments as per @format.
- @r None.
add_value (object value)

Adds @value to @builder. It is an error to call this function in any way that would create an inconsistent value to be constructed. Some examples of this are putting different types of items into an array, putting the wrong types or number of items in a tuple, putting more than one value into a variant, etc. If @value is a floating reference (see g_variant_ref_sink()), the @builder instance takes ownership of @value.
- @p value is a #GVariant.
- @r None.
clear ()

Releases all memory associated with a #GVariantBuilder without freeing the #GVariantBuilder structure itself. It typically only makes sense to do this on a stack-allocated #GVariantBuilder if you want to abort building the value part-way through. This function need not be called if you call g_variant_builder_end() and it also doesn't need to be called on builders allocated with g_variant_builder_new() (see g_variant_builder_unref() for that). This function leaves the #GVariantBuilder structure set to all-zeros. It is valid to call this function on either an initialised #GVariantBuilder or one that is set to all-zeros but it is not valid to call this function on uninitialised memory.
- @r None.
close ()

Closes the subcontainer inside the given @builder that was opened by the most recent call to g_variant_builder_open(). It is an error to call this function in any way that would create an inconsistent value to be constructed (ie: too few values added to the subcontainer).
- @r None.
end ()

Ends the builder process and returns the constructed value. It is not permissible to use @builder in any way after this call except for reference counting operations (in the case of a heap-allocated #GVariantBuilder) or by reinitialising it with g_variant_builder_init() (in the case of stack-allocated). This means that for the stack-allocated builders there is no need to call g_variant_builder_clear() after the call to g_variant_builder_end(). It is an error to call this function in any way that would create an inconsistent value to be constructed (ie: insufficient number of items added to a container with a specific number of children required). It is also an error to call this function if the builder was created with an indefinite array or maybe type and no children have been added; in this case it is impossible to infer the type of the empty array.
- @r a new, floating, #GVariant.
init (object type)

Initialises a #GVariantBuilder structure. @type must be non-%NULL. It specifies the type of container to construct. It can be an indefinite type such as %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)". Maybe, array, tuple, dictionary entry and variant-typed values may be constructed. If using a static type such as one of the G_VARIANT_TYPE_* constants or a G_VARIANT_TYPE ("(ii)") macro, it is more performant to use g_variant_builder_init_static() rather than g_variant_builder_init(). After the builder is initialised, values are added using g_variant_builder_add_value() or g_variant_builder_add(). After all the child values are added, g_variant_builder_end() frees the memory associated with the builder and returns the #GVariant that was created. This function completely ignores the previous contents of
- @builder. On one hand this means that it is valid to pass in completely uninitialised memory. On the other hand, this means that if you are initialising over top of an existing #GVariantBuilder you need to first call g_variant_builder_clear() in order to avoid leaking memory. You must not call g_variant_builder_ref() or g_variant_builder_unref() on a #GVariantBuilder that was initialised with this function. If you ever pass a reference to a #GVariantBuilder outside of the control of your own code then you should assume that the person receiving that reference may try to use reference counting; you should use g_variant_builder_new() instead of this function.
- @p type is a container type.
- @r None.
init_static (object type)

Initialises a #GVariantBuilder structure. This function works exactly like g_variant_builder_init() but does not make a copy of @type. Therefore, @type must remain valid for the lifetime of @builder. This is always true of type constants like G_VARIANT_TYPE_* or G_VARIANT_TYPE ("(ii)").
- @p type is a container type.
- @r None.
open (object type)

Opens a subcontainer inside the given @builder. When done adding items to the subcontainer, g_variant_builder_close() must be called. @type is the type of the container: so to build a tuple of several values, @type must include the tuple itself. It is an error to call this function in any way that would cause an inconsistent value to be constructed (ie: adding too many values or a value of an incorrect type). Example of building a nested variant: |[ GVariantBuilder builder; guint32 some_number = get_number (); g_autoptr (GHashTable) some_dict = get_dict (); GHashTableIter iter; const gchar *key; const GVariant *value; g_autoptr (GVariant) output = NULL; g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})")); g_variant_builder_add (&builder, "u", some_number); g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}")); g_hash_table_iter_init (&iter, some_dict); while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value)) { g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}")); g_variant_builder_add (&builder, "s", key); g_variant_builder_add (&builder, "v", value); g_variant_builder_close (&builder); } g_variant_builder_close (&builder); output = g_variant_builder_end (&builder); ]|
- @p type is the #GVariantType of the container.
- @r None.
ref ()

Increases the reference count on @builder. Don't call this on stack-allocated #GVariantBuilder instances or bad things will happen.
- @r a new reference to @builder.
unref ()

Decreases the reference count on @builder. In the event that there are no more references, releases all memory associated with the #GVariantBuilder. Don't call this on stack-allocated #GVariantBuilder instances or bad things will happen.
- @r None.