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

<refnamediv>
<refname>GBoxed</refname>
<refpurpose>A mechanism to wrap opaque C structures registered by the type system</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv 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>
typedef             <link linkend="GStrv">GStrv</link>;


</synopsis>
</refsynopsisdiv>









<refsect1 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>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="GBoxedCopyFunc" role="function"/>GBoxedCopyFunc ()</title>
<indexterm><primary>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><variablelist role="params">
<varlistentry><term><parameter>boxed</parameter>&nbsp;:</term>
<listitem><simpara>  The boxed structure to be copied.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>The newly created copy of the boxed structure.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GBoxedFreeFunc" role="function"/>GBoxedFreeFunc ()</title>
<indexterm><primary>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><variablelist role="params">
<varlistentry><term><parameter>boxed</parameter>&nbsp;:</term>
<listitem><simpara>The boxed structure to be freed.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-boxed-copy" role="function"/>g_boxed_copy ()</title>
<indexterm><primary>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><variablelist role="params">
<varlistentry><term><parameter>boxed_type</parameter>&nbsp;:</term>
<listitem><simpara>The type of <parameter>src_boxed</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src_boxed</parameter>&nbsp;:</term>
<listitem><simpara> The boxed structure to be copied.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>   The newly created copy of the boxed structure.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-boxed-free" role="function"/>g_boxed_free ()</title>
<indexterm><primary>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><variablelist role="params">
<varlistentry><term><parameter>boxed_type</parameter>&nbsp;:</term>
<listitem><simpara>The type of <parameter>boxed</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>boxed</parameter>&nbsp;:</term>
<listitem><simpara>     The boxed structure to be freed.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-boxed-type-register-static" role="function"/>g_boxed_type_register_static ()</title>
<indexterm><primary>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><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara>Name of the new boxed type.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>boxed_copy</parameter>&nbsp;:</term>
<listitem><simpara>Boxed structure copy function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>boxed_free</parameter>&nbsp;:</term>
<listitem><simpara>Boxed structure free function.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</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>
<title><anchor id="g-pointer-type-register-static" role="function"/>g_pointer_type_register_static ()</title>
<indexterm><primary>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><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara>the name of the new pointer type.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</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>
<title><anchor id="G-TYPE-HASH-TABLE:CAPS" role="macro" condition="since:2.10"/>G_TYPE_HASH_TABLE</title>
<indexterm role="2.10"><primary>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 role="since">Since 2.10


</para></refsect2>
<refsect2>
<title><anchor id="G-TYPE-DATE:CAPS" role="macro"/>G_TYPE_DATE</title>
<indexterm><primary>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></refsect2>
<refsect2>
<title><anchor id="G-TYPE-GSTRING:CAPS" role="macro"/>G_TYPE_GSTRING</title>
<indexterm><primary>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></refsect2>
<refsect2>
<title><anchor id="G-TYPE-STRV:CAPS" role="macro" condition="since:2.4"/>G_TYPE_STRV</title>
<indexterm role="2.4"><primary>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>
<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 role="since">Since 2.4


</para></refsect2>
<refsect2>
<title><anchor id="G-TYPE-REGEX:CAPS" role="macro" condition="since:2.14"/>G_TYPE_REGEX</title>
<indexterm role="2.14"><primary>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 role="since">Since 2.14


</para></refsect2>
<refsect2>
<title><anchor id="GStrv" role="typedef"/>GStrv</title>
<indexterm><primary>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></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<link linkend="GParamSpecBoxed"><type>GParamSpecBoxed</type></link>, <link linkend="g-param-spec-boxed"><function>g_param_spec_boxed()</function></link>
</para>
</refsect1>


<refsect1><refsect2 /><refsect2 /></refsect1>
</refentry>
