gtype.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

{
  GTypeFundamentalFlags  type_flags;
};
</programlisting>
<para>
A structure that provides information to the type system which is
used specifically for managing fundamental types.  
</para></refsect2>
<refsect2>
<title><anchor id="GInterfaceInfo">struct GInterfaceInfo</title>
<programlisting>struct GInterfaceInfo
{
  GInterfaceInitFunc     interface_init;
  GInterfaceFinalizeFunc interface_finalize;
  gpointer               interface_data;
};
</programlisting>
<para>
A structure that provides information to the type system which is
used specifically for managing interface types.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="GInterfaceInitFunc">GInterfaceInitFunc</link> <structfield>interface_init</structfield></entry>
<entry>	Location of the function that initializes the interface.
</entry>
</row>
<row>
<entry><link linkend="GInterfaceFinalizeFunc">GInterfaceFinalizeFunc</link> <structfield>interface_finalize</structfield></entry>
<entry>	Location of the function that finalizes the interface.
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> <structfield>interface_data</structfield></entry>
<entry>	Location of user data passed to the <parameter>interface_init</parameter> and
	 		<parameter>interface_finalize</parameter> functions (optional).

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GTypeValueTable">struct GTypeValueTable</title>
<programlisting>struct GTypeValueTable
{
  void     (*value_init)         (GValue       *value);
  void     (*value_free)         (GValue       *value);
  void     (*value_copy)         (const GValue *src_value,
				  GValue       *dest_value);
  /* varargs functionality (optional) */
  gpointer (*value_peek_pointer) (const GValue *value);
  gchar	    *collect_format;
  gchar*   (*collect_value)      (GValue       *value,
				  guint         n_collect_values,
				  GTypeCValue  *collect_values,
				  guint		collect_flags);
  gchar	    *lcopy_format;
  gchar*   (*lcopy_value)        (const GValue *value,
				  guint         n_collect_values,
				  GTypeCValue  *collect_values,
				  guint		collect_flags);
};
</programlisting>
<para>
The <link linkend="GTypeValueTable">GTypeValueTable</link> provides the functions required by the <link linkend="GValue">GValue</link> implementation,
to serve as a container for values of a type.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry>void (*<structfield>value_init</structfield>) (GValue       *value)</entry>
<entry>		Default initialize <parameter>values</parameter> contents by poking values
			directly into the value-&gt;data array. The data array of
			the <link linkend="GValue">GValue</link> passed into this function was zero-filled
			with memset, so no care has to be taken to free any
			old contents. E.g. for the implementation of a string
			value that may never be NULL, the implementation might
			look like:
<msgtext><programlisting>
{
  value-&gt;data[0].v_pointer = g_strdup ("");
}
</programlisting></msgtext>
</entry>
</row>
<row>
<entry>void (*<structfield>value_free</structfield>) (GValue       *value)</entry>
<entry>		Free any old contents that might be left in the
			data array of the passed in <parameter>value</parameter>. No resources may
			remain allocated through the <link linkend="GValue">GValue</link> contents after
			this function returns. E.g. for our above string type:
<msgtext><programlisting>
{
  /* only free strings without a specific flag for static storage */
  if (!(value-&gt;data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
    g_free (value-&gt;data[0].v_pointer);
}
</programlisting></msgtext>
</entry>
</row>
<row>
<entry>void (*<structfield>value_copy</structfield>) (const GValue *src_value,
				  GValue       *dest_value)</entry>
<entry>		<parameter>dest_value</parameter> is a <link linkend="GValue">GValue</link> with zero-filled data section
			and <parameter>src_value</parameter> is a properly setup <link linkend="GValue">GValue</link> of same or
			derived type.
			The purpose of this function is to copy the contents of
			<parameter>src_value</parameter> into <parameter>dest_value</parameter> in a way, that even after
			<parameter>src_value</parameter> has been freed, the contents of <parameter>dest_value</parameter>
			remain valid. String type example:
<msgtext><programlisting>
{
  dest_value-&gt;data[0].v_pointer = g_strdup (src_value-&gt;data[0].v_pointer);
}
</programlisting></msgtext>
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> (*<structfield>value_peek_pointer</structfield>) (const GValue *value)</entry>
<entry>	If the value contents fit into a pointer, such as objects
			or strings, return this pointer, so the caller can peek at
			the current contents. To extend on our above string example:
<msgtext><programlisting>
{
  return value-&gt;data[0].v_pointer;
}
</programlisting></msgtext>
</entry>
</row>
<row>
<entry><link linkend="gchar">gchar</link> *<structfield>collect_format</structfield></entry>
<entry>	A string format describing how to collect the contents of
			this value, bit-by-bit. Each character in the format represents
			an argument to be collected, the characters themselves indicate
			the type of the argument. Currently supported arguments are:
<msgtext><variablelist>
  <varlistentry><term></term><listitem><para>
        'i' - Integers. passed as collect_values[].v_int.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
        'l' - Longs. passed as collect_values[].v_long.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
        'd' - Doubles. passed as collect_values[].v_double.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
        'p' - Pointers. passed as collect_values[].v_pointer.
  </para></listitem></varlistentry>
</variablelist></msgtext>
			It should be noted, that for variable argument list construction,
			ANSI C promotes every type smaller than an integer to an int, and
			floats to doubles. So for collection of short int or char, 'i'
			needs to be used, and for collection of floats 'd'.
</entry>
</row>
<row>
<entry><link linkend="gchar">gchar</link>* (*<structfield>collect_value</structfield>) (GValue       *value,
				  guint         n_collect_values,
				  GTypeCValue  *collect_values,
				  guint		collect_flags)</entry>
<entry>	The <link linkend="collect-value">collect_value</link>() function is responsible for converting the
			values collected from a variable argument list into contents
			suitable for storage in a GValue. This function should setup
			<parameter>value</parameter> similar to <link linkend="value-init">value_init</link>(), e.g. for a string value that
			does not allow NULL pointers, it needs to either spew an error,
			or do an implicit conversion by storing an empty string.
			The <parameter>value</parameter> passed in to this function has a zero-filled data
			array, so just like for <parameter>value_init</parameter> it is guaranteed to not
			contain any old contents that might need freeing.
			<parameter>n_collect_values</parameter> is exactly the string length of <parameter>collect_format</parameter>,
			and <parameter>collect_values</parameter> is an array of unions <link linkend="GTypeCValue">GTypeCValue</link> with
			length <parameter>n_collect_values</parameter>, containing the collected values
			according to <parameter>collect_format</parameter>.
			<parameter>collect_flags</parameter> is an argument provided as a hint by the caller,
			which may contain the flag <link linkend="G-VALUE-NOCOPY-CONTENTS-CAPS">G_VALUE_NOCOPY_CONTENTS</link> indicating,
			that the collected value contents may be considered "static"
			for the duration of the #<parameter>value</parameter> lifetime.
			Thus an extra copy of the contents stored in <parameter>collect_values</parameter> is
			not required for assignment to <parameter>value</parameter>.
			For our above string example, we continue with:
<msgtext><programlisting>
{
  if (!collect_values[0].v_pointer)
    value->data[0].v_pointer = g_strdup ("");
  else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
    {
      value-&gt;data[0].v_pointer = collect_values[0].v_pointer;
      /* keep a flag for the <link linkend="value-free">value_free</link>() implementation to not free this string */
      value-&gt;data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
    }
  else
    value-&gt;data[0].v_pointer = g_strdup (collect_values[0].v_pointer);

  return NULL;
}
</programlisting></msgtext>
			It should be noted, that it is generally a bad idea to follow the
			<link linkend="G-VALUE-NOCOPY-CONTENTS-CAPS">G_VALUE_NOCOPY_CONTENTS</link> hint for reference counted types. Due to
			reentrancy requirements and reference count assertions performed
			by the GSignal code, reference counts should always be incremented
			for reference counted contents stored in the value-&gt;data array.
			To deviate from our string example for a moment, and taking a look
			at an exemplary implementation for <link linkend="collect-value">collect_value</link>() of <link linkend="GObject">GObject</link>:
<msgtext><programlisting>
{
  if (collect_values[0].v_pointer)
    {
      GObject *object = G_OBJECT (collect_values[0].v_pointer);

      /* never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types */
      value-&gt;data[0].v_pointer = g_object_ref (object);
      return NULL;
    }
  else
    return g_strdup_printf ("Object passed as invalid NULL pointer");
}
</programlisting></msgtext>
			The reference count for valid objects is always incremented,
			regardless of <parameter>collect_flags</parameter>. For invalid objects, the example
			returns a newly allocated string without altering <parameter>value</parameter>.
			Upon success, <link linkend="collect-value">collect_value</link>() needs to return NULL, if however
			a malicious condition occurred, <link linkend="collect-value">collect_value</link>() may spew an
			error by returning a newly allocated non-NULL string, giving
			a suitable description of the error condition.
			The calling code makes no assumptions about the <parameter>value</parameter>
			contents being valid upon error returns, <parameter>value</parameter>
			is simply thrown away without further freeing. As such, it is
			a good idea to not allocate <link linkend="GValue">GValue</link> contents, prior to returning
			an error, however, <link linkend="collect-values">collect_values</link>() is not obliged to return
			a correctly setup <parameter>value</parameter> for error returns, simply because
			any non-NULL return is considered a fatal condition so further
			program behaviour is undefined.
</entry>
</row>
<row>
<entry><link linkend="gchar">gchar</link> *<structfield>lcopy_format</structfield></entry>
<entry>		Format description of the arguments to collect for <parameter>lcopy_value</parameter>,
			analogous to <parameter>collect_format</parameter>. Usually, <parameter>lcopy_format</parameter> string consists
			only of 'p's to provide <link linkend="lcopy-value">lcopy_value</link>() with pointers to storage locations.
</entry>
</row>
<row>
<entry><link linkend="gchar">gchar</link>* (*<structfield>lcopy_value</structfield>) (const GValue *value,
				  guint         n_collect_values,
				  GTypeCValue  *collect_values,
				  guint		collect_flags)</entry>
<entry>		This function is responsible for storing the <parameter>value</parameter> contents into
			arguments passed through a variable argument list which got
			collected into <parameter>collect_values</parameter> according to <parameter>lcopy_format</parameter>.
			<parameter>n_collect_values</parameter> equals the string length of <parameter>lcopy_format</parameter>,
			and <parameter>collect_flags</parameter> may contain <link linkend="G-VALUE-NOCOPY-CONTENTS-CAPS">G_VALUE_NOCOPY_CONTENTS</link>.
			In contrast to <link linkend="collect-value">collect_value</link>(), <link linkend="lcopy-value">lcopy_value</link>() is obliged to
			always properly support <link linkend="G-VALUE-NOCOPY-CONTENTS-CAPS">G_VALUE_NOCOPY_CONTENTS</link>.
			Similar to <link linkend="collect-value">collect_value</link>() the function may prematurely abort
			by returning a newly allocated string describing an error condition.
			To complete the string example:
<msgtext><programlisting>
{
  gchar **string_p = collect_values[0].v_pointer;

  if (!string_p)
    return g_strdup_printf ("string location passed as NULL");

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

}
</programlisting></msgtext>
			And an exemplary version of <link linkend="lcopy-value">lcopy_value</link>() for
			reference-counted types:
<msgtext><programlisting>
{
  GObject **object_p = collect_values[0].v_pointer;