<refentry id="gobject-Boxed-Types">
<refmeta>
<refentrytitle>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>
</refnamediv>

<refsynopsisdiv><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-GSTRING-CAPS">G_TYPE_GSTRING</link>
#define     <link linkend="G-TYPE-STRV-CAPS">G_TYPE_STRV</link>
typedef     <link linkend="GStrv">GStrv</link>;


</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GBoxedCopyFunc"/>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> :</term><listitem><simpara>The newly created copy of the boxed structure.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GBoxedFreeFunc"/>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"/>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> :</term><listitem><simpara>   The newly created copy of the boxed structure.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-boxed-free"/>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"/>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 <literal>G_TYPE_BOXED</literal> 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> :</term><listitem><simpara>New <literal>G_TYPE_BOXED</literal> derived type id for <parameter>name</parameter>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-pointer-type-register-static"/>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 <literal>G_TYPE_POINTER</literal> 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> :</term><listitem><simpara>a new <literal>G_TYPE_POINTER</literal> derived type id for <parameter>name</parameter>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-TYPE-GSTRING-CAPS"/>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"/>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 <literal>NULL</literal>-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>Since 2.4


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

</refentry>
