1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 2000-2001 Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17 * Boston, MA 02111-1307, USA.
25 #include "gtype-private.h"
27 #include "gvaluearray.h"
29 #include "gvaluecollector.h"
34 * @short_description: A mechanism to wrap opaque C structures registered
36 * @see_also: #GParamSpecBoxed, g_param_spec_boxed()
39 * GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
40 * thing the type system needs to know about the structures is how to copy and
41 * free them, beyond that they are treated as opaque chunks of memory.
43 * Boxed types are useful for simple value-holder structures like rectangles or
44 * points. They can also be used for wrapping structures defined in non-GObject
48 static inline void /* keep this function in sync with gvalue.c */
49 value_meminit (GValue *value,
52 value->g_type = value_type;
53 memset (value->data, 0, sizeof (value->data));
57 value_copy (gpointer boxed)
59 const GValue *src_value = boxed;
60 GValue *dest_value = g_new0 (GValue, 1);
62 if (G_VALUE_TYPE (src_value))
64 g_value_init (dest_value, G_VALUE_TYPE (src_value));
65 g_value_copy (src_value, dest_value);
71 value_free (gpointer boxed)
73 GValue *value = boxed;
75 if (G_VALUE_TYPE (value))
76 g_value_unset (value);
81 g_boxed_type_init (void)
83 static const GTypeInfo info = {
86 NULL, /* base_destroy */
87 NULL, /* class_init */
88 NULL, /* class_destroy */
89 NULL, /* class_data */
90 0, /* instance_size */
92 NULL, /* instance_init */
93 NULL, /* value_table */
95 const GTypeFundamentalInfo finfo = { G_TYPE_FLAG_DERIVABLE, };
100 type = g_type_register_fundamental (G_TYPE_BOXED, g_intern_static_string ("GBoxed"), &info, &finfo,
101 G_TYPE_FLAG_ABSTRACT | G_TYPE_FLAG_VALUE_ABSTRACT);
102 g_assert (type == G_TYPE_BOXED);
106 g_closure_get_type (void)
108 static GType type_id = 0;
111 type_id = g_boxed_type_register_static (g_intern_static_string ("GClosure"),
112 (GBoxedCopyFunc) g_closure_ref,
113 (GBoxedFreeFunc) g_closure_unref);
118 g_value_get_type (void)
120 static GType type_id = 0;
123 type_id = g_boxed_type_register_static (g_intern_static_string ("GValue"),
130 g_value_array_get_type (void)
132 static GType type_id = 0;
135 type_id = g_boxed_type_register_static (g_intern_static_string ("GValueArray"),
136 (GBoxedCopyFunc) g_value_array_copy,
137 (GBoxedFreeFunc) g_value_array_free);
142 gdate_copy (gpointer boxed)
144 const GDate *date = (const GDate*) boxed;
146 return g_date_new_julian (g_date_get_julian (date));
150 g_date_get_type (void)
152 static GType type_id = 0;
155 type_id = g_boxed_type_register_static (g_intern_static_string ("GDate"),
156 (GBoxedCopyFunc) gdate_copy,
157 (GBoxedFreeFunc) g_date_free);
162 g_strv_get_type (void)
164 static GType type_id = 0;
167 type_id = g_boxed_type_register_static (g_intern_static_string ("GStrv"),
168 (GBoxedCopyFunc) g_strdupv,
169 (GBoxedFreeFunc) g_strfreev);
174 gstring_copy (gpointer boxed)
176 const GString *src_gstring = boxed;
178 return g_string_new_len (src_gstring->str, src_gstring->len);
182 gstring_free (gpointer boxed)
184 GString *gstring = boxed;
186 g_string_free (gstring, TRUE);
190 g_gstring_get_type (void)
192 static GType type_id = 0;
195 type_id = g_boxed_type_register_static (g_intern_static_string ("GString"),
196 /* the naming is a bit odd, but GString is obviously not G_TYPE_STRING */
203 hash_table_copy (gpointer boxed)
205 GHashTable *hash_table = boxed;
206 return g_hash_table_ref (hash_table);
210 hash_table_free (gpointer boxed)
212 GHashTable *hash_table = boxed;
213 g_hash_table_unref (hash_table);
217 g_hash_table_get_type (void)
219 static GType type_id = 0;
221 type_id = g_boxed_type_register_static (g_intern_static_string ("GHashTable"),
222 hash_table_copy, hash_table_free);
227 g_regex_get_type (void)
229 static GType type_id = 0;
233 type_id = g_boxed_type_register_static (g_intern_static_string ("GRegex"),
234 (GBoxedCopyFunc) g_regex_ref,
235 (GBoxedFreeFunc) g_regex_unref);
242 g_array_get_type (void)
244 static GType type_id = 0;
246 type_id = g_boxed_type_register_static (g_intern_static_string ("GArray"),
247 (GBoxedCopyFunc) g_array_ref,
248 (GBoxedFreeFunc) g_array_unref);
253 g_ptr_array_get_type (void)
255 static GType type_id = 0;
257 type_id = g_boxed_type_register_static (g_intern_static_string ("GPtrArray"),
258 (GBoxedCopyFunc) g_ptr_array_ref,
259 (GBoxedFreeFunc) g_ptr_array_unref);
264 g_byte_array_get_type (void)
266 static GType type_id = 0;
268 type_id = g_boxed_type_register_static (g_intern_static_string ("GByteArray"),
269 (GBoxedCopyFunc) g_byte_array_ref,
270 (GBoxedFreeFunc) g_byte_array_unref);
276 g_variant_type_get_gtype (void)
278 static GType type_id = 0;
281 type_id = g_boxed_type_register_static (g_intern_static_string ("GVariantType"),
282 (GBoxedCopyFunc) g_variant_type_copy,
283 (GBoxedFreeFunc) g_variant_type_free);
289 * g_variant_get_gtype:
295 g_variant_get_gtype (void)
297 return G_TYPE_VARIANT;
301 g_error_get_type (void)
303 static GType type_id = 0;
306 type_id = g_boxed_type_register_static (g_intern_static_string ("GError"),
307 (GBoxedCopyFunc) g_error_copy,
308 (GBoxedFreeFunc) g_error_free);
314 boxed_proxy_value_init (GValue *value)
316 value->data[0].v_pointer = NULL;
320 boxed_proxy_value_free (GValue *value)
322 if (value->data[0].v_pointer && !(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
323 _g_type_boxed_free (G_VALUE_TYPE (value), value->data[0].v_pointer);
327 boxed_proxy_value_copy (const GValue *src_value,
330 if (src_value->data[0].v_pointer)
331 dest_value->data[0].v_pointer = _g_type_boxed_copy (G_VALUE_TYPE (src_value), src_value->data[0].v_pointer);
333 dest_value->data[0].v_pointer = src_value->data[0].v_pointer;
337 boxed_proxy_value_peek_pointer (const GValue *value)
339 return value->data[0].v_pointer;
343 boxed_proxy_collect_value (GValue *value,
344 guint n_collect_values,
345 GTypeCValue *collect_values,
348 if (!collect_values[0].v_pointer)
349 value->data[0].v_pointer = NULL;
352 if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
354 value->data[0].v_pointer = collect_values[0].v_pointer;
355 value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
358 value->data[0].v_pointer = _g_type_boxed_copy (G_VALUE_TYPE (value), collect_values[0].v_pointer);
365 boxed_proxy_lcopy_value (const GValue *value,
366 guint n_collect_values,
367 GTypeCValue *collect_values,
370 gpointer *boxed_p = collect_values[0].v_pointer;
373 return g_strdup_printf ("value location for `%s' passed as NULL", G_VALUE_TYPE_NAME (value));
375 if (!value->data[0].v_pointer)
377 else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
378 *boxed_p = value->data[0].v_pointer;
380 *boxed_p = _g_type_boxed_copy (G_VALUE_TYPE (value), value->data[0].v_pointer);
386 * g_boxed_type_register_static:
387 * @name: Name of the new boxed type.
388 * @boxed_copy: Boxed structure copy function.
389 * @boxed_free: Boxed structure free function.
391 * This function creates a new %G_TYPE_BOXED derived type id for a new
392 * boxed type with name @name. Boxed type handling functions have to be
393 * provided to copy and free opaque boxed structures of this type.
395 * Returns: New %G_TYPE_BOXED derived type id for @name.
398 g_boxed_type_register_static (const gchar *name,
399 GBoxedCopyFunc boxed_copy,
400 GBoxedFreeFunc boxed_free)
402 static const GTypeValueTable vtable = {
403 boxed_proxy_value_init,
404 boxed_proxy_value_free,
405 boxed_proxy_value_copy,
406 boxed_proxy_value_peek_pointer,
408 boxed_proxy_collect_value,
410 boxed_proxy_lcopy_value,
412 GTypeInfo type_info = {
414 NULL, /* base_init */
415 NULL, /* base_finalize */
416 NULL, /* class_init */
417 NULL, /* class_finalize */
418 NULL, /* class_data */
419 0, /* instance_size */
421 NULL, /* instance_init */
422 &vtable, /* value_table */
426 g_return_val_if_fail (name != NULL, 0);
427 g_return_val_if_fail (boxed_copy != NULL, 0);
428 g_return_val_if_fail (boxed_free != NULL, 0);
429 g_return_val_if_fail (g_type_from_name (name) == 0, 0);
431 type = g_type_register_static (G_TYPE_BOXED, name, &type_info, 0);
433 /* install proxy functions upon successfull registration */
435 _g_type_boxed_init (type, boxed_copy, boxed_free);
442 * @boxed_type: The type of @src_boxed.
443 * @src_boxed: The boxed structure to be copied.
445 * Provide a copy of a boxed structure @src_boxed which is of type @boxed_type.
447 * Returns: The newly created copy of the boxed structure.
450 g_boxed_copy (GType boxed_type,
451 gconstpointer src_boxed)
453 GTypeValueTable *value_table;
456 g_return_val_if_fail (G_TYPE_IS_BOXED (boxed_type), NULL);
457 g_return_val_if_fail (G_TYPE_IS_ABSTRACT (boxed_type) == FALSE, NULL);
458 g_return_val_if_fail (src_boxed != NULL, NULL);
460 value_table = g_type_value_table_peek (boxed_type);
462 g_return_val_if_fail (G_TYPE_IS_VALUE_TYPE (boxed_type), NULL);
464 /* check if our proxying implementation is used, we can short-cut here */
465 if (value_table->value_copy == boxed_proxy_value_copy)
466 dest_boxed = _g_type_boxed_copy (boxed_type, (gpointer) src_boxed);
469 GValue src_value, dest_value;
471 /* we heavily rely on third-party boxed type value vtable
472 * implementations to follow normal boxed value storage
473 * (data[0].v_pointer is the boxed struct, and
474 * data[1].v_uint holds the G_VALUE_NOCOPY_CONTENTS flag,
476 * but then, we can expect that since we layed out the
478 * data[1].v_uint&G_VALUE_NOCOPY_CONTENTS shouldn't be set
481 /* equiv. to g_value_set_static_boxed() */
482 value_meminit (&src_value, boxed_type);
483 src_value.data[0].v_pointer = (gpointer) src_boxed;
484 src_value.data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
486 /* call third-party code copy function, fingers-crossed */
487 value_meminit (&dest_value, boxed_type);
488 value_table->value_copy (&src_value, &dest_value);
490 /* double check and grouse if things went wrong */
491 if (dest_value.data[1].v_ulong)
492 g_warning ("the copy_value() implementation of type `%s' seems to make use of reserved GValue fields",
493 g_type_name (boxed_type));
495 dest_boxed = dest_value.data[0].v_pointer;
503 * @boxed_type: The type of @boxed.
504 * @boxed: The boxed structure to be freed.
506 * Free the boxed structure @boxed which is of type @boxed_type.
509 g_boxed_free (GType boxed_type,
512 GTypeValueTable *value_table;
514 g_return_if_fail (G_TYPE_IS_BOXED (boxed_type));
515 g_return_if_fail (G_TYPE_IS_ABSTRACT (boxed_type) == FALSE);
516 g_return_if_fail (boxed != NULL);
518 value_table = g_type_value_table_peek (boxed_type);
520 g_return_if_fail (G_TYPE_IS_VALUE_TYPE (boxed_type));
522 /* check if our proxying implementation is used, we can short-cut here */
523 if (value_table->value_free == boxed_proxy_value_free)
524 _g_type_boxed_free (boxed_type, boxed);
529 /* see g_boxed_copy() on why we think we can do this */
530 value_meminit (&value, boxed_type);
531 value.data[0].v_pointer = boxed;
532 value_table->value_free (&value);
538 * @value: a valid #GValue of %G_TYPE_BOXED derived type
540 * Get the contents of a %G_TYPE_BOXED derived #GValue.
542 * Returns: boxed contents of @value
545 g_value_get_boxed (const GValue *value)
547 g_return_val_if_fail (G_VALUE_HOLDS_BOXED (value), NULL);
548 g_return_val_if_fail (G_TYPE_IS_VALUE (G_VALUE_TYPE (value)), NULL);
550 return value->data[0].v_pointer;
555 * @value: a valid #GValue of %G_TYPE_BOXED derived type
557 * Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting,
558 * the boxed value is duplicated and needs to be later freed with
559 * g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value),
562 * Returns: boxed contents of @value
565 g_value_dup_boxed (const GValue *value)
567 g_return_val_if_fail (G_VALUE_HOLDS_BOXED (value), NULL);
568 g_return_val_if_fail (G_TYPE_IS_VALUE (G_VALUE_TYPE (value)), NULL);
570 return value->data[0].v_pointer ? g_boxed_copy (G_VALUE_TYPE (value), value->data[0].v_pointer) : NULL;
574 value_set_boxed_internal (GValue *value,
581 /* just resetting to NULL might not be desired, need to
582 * have value reinitialized also (for values defaulting
583 * to other default value states than a NULL data pointer),
584 * g_value_reset() will handle this
586 g_value_reset (value);
590 if (value->data[0].v_pointer && !(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
591 g_boxed_free (G_VALUE_TYPE (value), value->data[0].v_pointer);
592 value->data[1].v_uint = need_free ? 0 : G_VALUE_NOCOPY_CONTENTS;
593 value->data[0].v_pointer = need_copy ? g_boxed_copy (G_VALUE_TYPE (value), boxed) : (gpointer) boxed;
598 * @value: a valid #GValue of %G_TYPE_BOXED derived type
599 * @v_boxed: boxed value to be set
601 * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
604 g_value_set_boxed (GValue *value,
607 g_return_if_fail (G_VALUE_HOLDS_BOXED (value));
608 g_return_if_fail (G_TYPE_IS_VALUE (G_VALUE_TYPE (value)));
610 value_set_boxed_internal (value, boxed, TRUE, TRUE);
614 * g_value_set_static_boxed:
615 * @value: a valid #GValue of %G_TYPE_BOXED derived type
616 * @v_boxed: static boxed value to be set
618 * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
619 * The boxed value is assumed to be static, and is thus not duplicated
620 * when setting the #GValue.
623 g_value_set_static_boxed (GValue *value,
626 g_return_if_fail (G_VALUE_HOLDS_BOXED (value));
627 g_return_if_fail (G_TYPE_IS_VALUE (G_VALUE_TYPE (value)));
629 value_set_boxed_internal (value, boxed, FALSE, FALSE);
633 * g_value_set_boxed_take_ownership:
634 * @value: a valid #GValue of %G_TYPE_BOXED derived type
635 * @v_boxed: duplicated unowned boxed value to be set
637 * This is an internal function introduced mainly for C marshallers.
639 * Deprecated: 2.4: Use g_value_take_boxed() instead.
642 g_value_set_boxed_take_ownership (GValue *value,
645 g_value_take_boxed (value, boxed);
649 * g_value_take_boxed:
650 * @value: a valid #GValue of %G_TYPE_BOXED derived type
651 * @v_boxed: duplicated unowned boxed value to be set
653 * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed
654 * and takes over the ownership of the callers reference to @v_boxed;
655 * the caller doesn't have to unref it any more.
660 g_value_take_boxed (GValue *value,
663 g_return_if_fail (G_VALUE_HOLDS_BOXED (value));
664 g_return_if_fail (G_TYPE_IS_VALUE (G_VALUE_TYPE (value)));
666 value_set_boxed_internal (value, boxed, FALSE, TRUE);