<refentry id="gobject-Boxed-Types">
<refmeta>
<refentrytitle role="top_of_page" id="gobject-Boxed-Types.top_of_page">Boxed Types</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GOBJECT Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Boxed Types</refname>
<refpurpose>A mechanism to wrap opaque C structures registered
    by the type system</refpurpose>
</refnamediv>

<refsynopsisdiv id="gobject-Boxed-Types.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib-object.h&gt;

<link linkend="gpointer">gpointer</link>            (<link linkend="GBoxedCopyFunc">*GBoxedCopyFunc</link>)                   (<link linkend="gpointer">gpointer</link> boxed);
<link linkend="void">void</link>                (<link linkend="GBoxedFreeFunc">*GBoxedFreeFunc</link>)                   (<link linkend="gpointer">gpointer</link> boxed);
<link linkend="gpointer">gpointer</link>            <link linkend="g-boxed-copy">g_boxed_copy</link>                        (<link linkend="GType">GType</link> boxed_type,
                                                         <link linkend="gconstpointer">gconstpointer</link> src_boxed);
<link linkend="void">void</link>                <link linkend="g-boxed-free">g_boxed_free</link>                        (<link linkend="GType">GType</link> boxed_type,
                                                         <link linkend="gpointer">gpointer</link> boxed);
<link linkend="GType">GType</link>               <link linkend="g-boxed-type-register-static">g_boxed_type_register_static</link>        (const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GBoxedCopyFunc">GBoxedCopyFunc</link> boxed_copy,
                                                         <link linkend="GBoxedFreeFunc">GBoxedFreeFunc</link> boxed_free);
<link linkend="GType">GType</link>               <link linkend="g-pointer-type-register-static">g_pointer_type_register_static</link>      (const <link linkend="gchar">gchar</link> *name);

#define             <link linkend="G-TYPE-HASH-TABLE--CAPS">G_TYPE_HASH_TABLE</link>
#define             <link linkend="G-TYPE-DATE--CAPS">G_TYPE_DATE</link>
#define             <link linkend="G-TYPE-GSTRING--CAPS">G_TYPE_GSTRING</link>
#define             <link linkend="G-TYPE-STRV--CAPS">G_TYPE_STRV</link>
#define             <link linkend="G-TYPE-REGEX--CAPS">G_TYPE_REGEX</link>
#define             <link linkend="G-TYPE-ARRAY--CAPS">G_TYPE_ARRAY</link>
#define             <link linkend="G-TYPE-BYTE-ARRAY--CAPS">G_TYPE_BYTE_ARRAY</link>
#define             <link linkend="G-TYPE-PTR-ARRAY--CAPS">G_TYPE_PTR_ARRAY</link>
typedef             <link linkend="GStrv">GStrv</link>;
</synopsis>
</refsynopsisdiv>









<refsect1 id="gobject-Boxed-Types.description" role="desc">
<title role="desc.title">Description</title>
<para>
GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
thing the type system needs to know about the structures is how to copy and
free them, beyond that they are treated as opaque chunks of memory.
</para>
<para>
Boxed types are useful for simple value-holder structures like rectangles or
points. They can also be used for wrapping structures defined in non-GObject
based libraries.</para>
<para>
</para>
</refsect1>

<refsect1 id="gobject-Boxed-Types.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GBoxedCopyFunc" role="function">
<title>GBoxedCopyFunc ()</title>
<indexterm zone="GBoxedCopyFunc"><primary sortas="BoxedCopyFunc">GBoxedCopyFunc</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            (*GBoxedCopyFunc)                   (<link linkend="gpointer">gpointer</link> boxed);</programlisting>
<para>
This function is provided by the user and should produce a copy of the passed
in boxed structure.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>boxed</parameter>&#160;:</term>
<listitem><simpara> The boxed structure to be copied.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The newly created copy of the boxed structure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GBoxedFreeFunc" role="function">
<title>GBoxedFreeFunc ()</title>
<indexterm zone="GBoxedFreeFunc"><primary sortas="BoxedFreeFunc">GBoxedFreeFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GBoxedFreeFunc)                   (<link linkend="gpointer">gpointer</link> boxed);</programlisting>
<para>
This function is provided by the user and should free the boxed
structure passed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>boxed</parameter>&#160;:</term>
<listitem><simpara> The boxed structure to be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-boxed-copy" role="function">
<title>g_boxed_copy ()</title>
<indexterm zone="g-boxed-copy"><primary sortas="boxed_copy">g_boxed_copy</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_boxed_copy                        (<link linkend="GType">GType</link> boxed_type,
                                                         <link linkend="gconstpointer">gconstpointer</link> src_boxed);</programlisting>
<para>
Provide a copy of a boxed structure <parameter>src_boxed</parameter> which is of type <parameter>boxed_type</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>boxed_type</parameter>&#160;:</term>
<listitem><simpara> The type of <parameter>src_boxed</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src_boxed</parameter>&#160;:</term>
<listitem><simpara> The boxed structure to be copied.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The newly created copy of the boxed structure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-boxed-free" role="function">
<title>g_boxed_free ()</title>
<indexterm zone="g-boxed-free"><primary sortas="boxed_free">g_boxed_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_boxed_free                        (<link linkend="GType">GType</link> boxed_type,
                                                         <link linkend="gpointer">gpointer</link> boxed);</programlisting>
<para>
Free the boxed structure <parameter>boxed</parameter> which is of type <parameter>boxed_type</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>boxed_type</parameter>&#160;:</term>
<listitem><simpara> The type of <parameter>boxed</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>boxed</parameter>&#160;:</term>
<listitem><simpara> The boxed structure to be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-boxed-type-register-static" role="function">
<title>g_boxed_type_register_static ()</title>
<indexterm zone="g-boxed-type-register-static"><primary sortas="boxed_type_register_static">g_boxed_type_register_static</primary></indexterm><programlisting><link linkend="GType">GType</link>               g_boxed_type_register_static        (const <link linkend="gchar">gchar</link> *name,
                                                         <link linkend="GBoxedCopyFunc">GBoxedCopyFunc</link> boxed_copy,
                                                         <link linkend="GBoxedFreeFunc">GBoxedFreeFunc</link> boxed_free);</programlisting>
<para>
This function creates a new <link linkend="G-TYPE-BOXED--CAPS"><literal>G_TYPE_BOXED</literal></link> derived type id for a new
boxed type with name <parameter>name</parameter>. Boxed type handling functions have to be
provided to copy and free opaque boxed structures of this type.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara> Name of the new boxed type.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>boxed_copy</parameter>&#160;:</term>
<listitem><simpara> Boxed structure copy function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>boxed_free</parameter>&#160;:</term>
<listitem><simpara> Boxed structure free function.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> New <link linkend="G-TYPE-BOXED--CAPS"><literal>G_TYPE_BOXED</literal></link> derived type id for <parameter>name</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-pointer-type-register-static" role="function">
<title>g_pointer_type_register_static ()</title>
<indexterm zone="g-pointer-type-register-static"><primary sortas="pointer_type_register_static">g_pointer_type_register_static</primary></indexterm><programlisting><link linkend="GType">GType</link>               g_pointer_type_register_static      (const <link linkend="gchar">gchar</link> *name);</programlisting>
<para>
Creates a new <link linkend="G-TYPE-POINTER--CAPS"><literal>G_TYPE_POINTER</literal></link> derived type id for a new
pointer type with name <parameter>name</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&#160;:</term>
<listitem><simpara> the name of the new pointer type.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="G-TYPE-POINTER--CAPS"><literal>G_TYPE_POINTER</literal></link> derived type id for <parameter>name</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-TYPE-HASH-TABLE--CAPS" role="macro" condition="since:2.10">
<title>G_TYPE_HASH_TABLE</title>
<indexterm zone="G-TYPE-HASH-TABLE--CAPS" role="2.10"><primary sortas="TYPE_HASH_TABLE">G_TYPE_HASH_TABLE</primary></indexterm><programlisting>#define	G_TYPE_HASH_TABLE (g_hash_table_get_type ())
</programlisting>
<para>
The <link linkend="GType"><type>GType</type></link> for a boxed type holding a <link linkend="GHashTable"><type>GHashTable</type></link> reference.</para>
<para>
</para><para role="since">Since 2.10</para></refsect2>
<refsect2 id="G-TYPE-DATE--CAPS" role="macro">
<title>G_TYPE_DATE</title>
<indexterm zone="G-TYPE-DATE--CAPS"><primary sortas="TYPE_DATE">G_TYPE_DATE</primary></indexterm><programlisting>#define	G_TYPE_DATE	        (g_date_get_type ())
</programlisting>
<para>
The <link linkend="GType"><type>GType</type></link> for <link linkend="GDate"><type>GDate</type></link>.</para>
<para>
</para></refsect2>
<refsect2 id="G-TYPE-GSTRING--CAPS" role="macro">
<title>G_TYPE_GSTRING</title>
<indexterm zone="G-TYPE-GSTRING--CAPS"><primary sortas="TYPE_GSTRING">G_TYPE_GSTRING</primary></indexterm><programlisting>#define	G_TYPE_GSTRING		(g_gstring_get_type ())
</programlisting>
<para>
The <link linkend="GType"><type>GType</type></link> for <link linkend="GString"><type>GString</type></link>.</para>
<para>
</para></refsect2>
<refsect2 id="G-TYPE-STRV--CAPS" role="macro" condition="since:2.4">
<title>G_TYPE_STRV</title>
<indexterm zone="G-TYPE-STRV--CAPS" role="2.4"><primary sortas="TYPE_STRV">G_TYPE_STRV</primary></indexterm><programlisting>#define	G_TYPE_STRV	        (g_strv_get_type ())
</programlisting>
<para>
The <link linkend="GType"><type>GType</type></link> for a boxed type holding a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings.
</para>
<para>
The code fragments in the following example show the use of a property of
type <link linkend="G-TYPE-STRV--CAPS"><type>G_TYPE_STRV</type></link> with <link linkend="g-object-class-install-property"><function>g_object_class_install_property()</function></link>, <link linkend="g-object-set"><function>g_object_set()</function></link>
and <link linkend="g-object-get"><function>g_object_get()</function></link>.
</para>
<para>
<informalexample><programlisting>
g_object_class_install_property (object_class,
                                 PROP_AUTHORS,
                                 g_param_spec_boxed ("authors",
                                                     _("Authors"),
                                                     _("List of authors"),
                                                     G_TYPE_STRV,
                                                     G_PARAM_READWRITE));


gchar *authors[] = { "Owen", "Tim", NULL };
g_object_set (obj, "authors", authors, NULL);


gchar *writers[];
g_object_get (obj, "authors", &amp;writers, NULL);
// do something with writers
g_strfreev (writers);
</programlisting></informalexample></para>
<para>
</para><para role="since">Since 2.4</para></refsect2>
<refsect2 id="G-TYPE-REGEX--CAPS" role="macro" condition="since:2.14">
<title>G_TYPE_REGEX</title>
<indexterm zone="G-TYPE-REGEX--CAPS" role="2.14"><primary sortas="TYPE_REGEX">G_TYPE_REGEX</primary></indexterm><programlisting>#define	G_TYPE_REGEX (g_regex_get_type ())
</programlisting>
<para>
The <link linkend="GType"><type>GType</type></link> for a boxed type holding a <link linkend="GRegex"><type>GRegex</type></link> reference.</para>
<para>
</para><para role="since">Since 2.14</para></refsect2>
<refsect2 id="G-TYPE-ARRAY--CAPS" role="macro" condition="since:2.22">
<title>G_TYPE_ARRAY</title>
<indexterm zone="G-TYPE-ARRAY--CAPS" role="2.22"><primary sortas="TYPE_ARRAY">G_TYPE_ARRAY</primary></indexterm><programlisting>#define	G_TYPE_ARRAY (g_array_get_type ())
</programlisting>
<para>
The <link linkend="GType"><type>GType</type></link> for a boxed type holding a <link linkend="GArray"><type>GArray</type></link> reference.</para>
<para>
</para><para role="since">Since 2.22</para></refsect2>
<refsect2 id="G-TYPE-BYTE-ARRAY--CAPS" role="macro" condition="since:2.22">
<title>G_TYPE_BYTE_ARRAY</title>
<indexterm zone="G-TYPE-BYTE-ARRAY--CAPS" role="2.22"><primary sortas="TYPE_BYTE_ARRAY">G_TYPE_BYTE_ARRAY</primary></indexterm><programlisting>#define	G_TYPE_BYTE_ARRAY (g_byte_array_get_type ())
</programlisting>
<para>
The <link linkend="GType"><type>GType</type></link> for a boxed type holding a <link linkend="GByteArray"><type>GByteArray</type></link> reference.</para>
<para>
</para><para role="since">Since 2.22</para></refsect2>
<refsect2 id="G-TYPE-PTR-ARRAY--CAPS" role="macro" condition="since:2.22">
<title>G_TYPE_PTR_ARRAY</title>
<indexterm zone="G-TYPE-PTR-ARRAY--CAPS" role="2.22"><primary sortas="TYPE_PTR_ARRAY">G_TYPE_PTR_ARRAY</primary></indexterm><programlisting>#define	G_TYPE_PTR_ARRAY (g_ptr_array_get_type ())
</programlisting>
<para>
The <link linkend="GType"><type>GType</type></link> for a boxed type holding a <link linkend="GPtrArray"><type>GPtrArray</type></link> reference.</para>
<para>
</para><para role="since">Since 2.22</para></refsect2>
<refsect2 id="GStrv" role="typedef">
<title>GStrv</title>
<indexterm zone="GStrv"><primary sortas="Strv">GStrv</primary></indexterm><programlisting>typedef gchar** GStrv;
</programlisting>
<para>
A C representable type name for <link linkend="G-TYPE-STRV--CAPS"><type>G_TYPE_STRV</type></link>.</para>
<para>
</para></refsect2>

</refsect1>



<refsect1 id="gobject-Boxed-Types.see-also">
<title>See Also</title>
#GParamSpecBoxed, <link linkend="g-param-spec-boxed"><function>g_param_spec_boxed()</function></link>
</refsect1>

</refentry>
