Function

GObjectTypeValueLCopyFunc

since: 2.78

Declaration

gchar*
(* GTypeValueLCopyFunc) (
  const GValue* value,
  guint n_collect_values,
  GTypeCValue* collect_values,
  guint collect_flags
)

Description

This function is responsible for storing the value contents into arguments passed through a variadic argument list which got collected into collect_values according to lcopy_format.

The n_collect_values argument equals the string length of lcopy_format, and collect_flags may contain G_VALUE_NOCOPY_CONTENTS.

In contrast to GTypeValueCollectFunc, this function is obliged to always properly support G_VALUE_NOCOPY_CONTENTS.

Similar to GTypeValueCollectFunc the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example:

gchar **string_p = collect_values[0].v_pointer;
g_return_val_if_fail (string_p != NULL,
  g_strdup ("string location passed as NULL"));

if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
  *string_p = value->data[0].v_pointer;
else
  *string_p = g_strdup (value->data[0].v_pointer);

And an illustrative version of this function for reference-counted types:

GObject **object_p = collect_values[0].v_pointer;
g_return_val_if_fail (object_p != NULL,
  g_strdup ("object location passed as NULL"));

if (value->data[0].v_pointer == NULL)
  *object_p = NULL;
else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour
  *object_p = value->data[0].v_pointer;
else
  *object_p = g_object_ref (value->data[0].v_pointer);

return NULL;

Available since: 2.78

Parameters

value

Type: GValue

The value to lcopy.

The data is owned by the caller of the function.

n_collect_values

Type: guint

The number of collected values.

collect_values

Type: An array of GTypeCValue

The collected locations for storage.

The length of the array is specified in the n_collect_values argument.

The data is owned by the caller of the function.

collect_flags

Type: guint

Optional flags.

Return value

Type: gchar*

NULL on success, otherwise a newly allocated error string on failure.

The caller of the function takes ownership of the data, and is responsible for freeing it.

The return value can be NULL.

The value is a NUL terminated UTF-8 string.