hooks.sgml

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

<refentry id="glib-Hook-Functions">
<refmeta>
<refentrytitle>Hook Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Hook Functions</refname><refpurpose>support for manipulating lists of hook functions.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GHookList">GHookList</link>;
void        (<link linkend="GHookFinalizeFunc">*GHookFinalizeFunc</link>)            (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *hook);
struct      <link linkend="GHook">GHook</link>;
void        (<link linkend="GHookFunc">*GHookFunc</link>)                    (<link linkend="gpointer">gpointer</link> data);
<link linkend="gboolean">gboolean</link>    (<link linkend="GHookCheckFunc">*GHookCheckFunc</link>)               (<link linkend="gpointer">gpointer</link> data);

void        <link linkend="g-hook-list-init">g_hook_list_init</link>                (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="guint">guint</link> hook_size);
void        <link linkend="g-hook-list-invoke">g_hook_list_invoke</link>              (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gboolean">gboolean</link> may_recurse);
void        <link linkend="g-hook-list-invoke-check">g_hook_list_invoke_check</link>        (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gboolean">gboolean</link> may_recurse);
void        <link linkend="g-hook-list-marshal">g_hook_list_marshal</link>             (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gboolean">gboolean</link> may_recurse,
                                             <link linkend="GHookMarshaller">GHookMarshaller</link> marshaller,
                                             <link linkend="gpointer">gpointer</link> marshal_data);
void        (<link linkend="GHookMarshaller">*GHookMarshaller</link>)              (<link linkend="GHook">GHook</link> *hook,
                                             <link linkend="gpointer">gpointer</link> marshal_data);
void        <link linkend="g-hook-list-marshal-check">g_hook_list_marshal_check</link>       (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gboolean">gboolean</link> may_recurse,
                                             <link linkend="GHookCheckMarshaller">GHookCheckMarshaller</link> marshaller,
                                             <link linkend="gpointer">gpointer</link> marshal_data);
<link linkend="gboolean">gboolean</link>    (<link linkend="GHookCheckMarshaller">*GHookCheckMarshaller</link>)         (<link linkend="GHook">GHook</link> *hook,
                                             <link linkend="gpointer">gpointer</link> marshal_data);
void        <link linkend="g-hook-list-clear">g_hook_list_clear</link>               (<link linkend="GHookList">GHookList</link> *hook_list);

<link linkend="GHook">GHook</link>*      <link linkend="g-hook-alloc">g_hook_alloc</link>                    (<link linkend="GHookList">GHookList</link> *hook_list);
#define     <link linkend="g-hook-append">g_hook_append</link>                   ( hook_list, hook )
void        <link linkend="g-hook-prepend">g_hook_prepend</link>                  (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *hook);
void        <link linkend="g-hook-insert-before">g_hook_insert_before</link>            (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *sibling,
                                             <link linkend="GHook">GHook</link> *hook);
void        <link linkend="g-hook-insert-sorted">g_hook_insert_sorted</link>            (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *hook,
                                             <link linkend="GHookCompareFunc">GHookCompareFunc</link> func);
<link linkend="gint">gint</link>        (<link linkend="GHookCompareFunc">*GHookCompareFunc</link>)             (<link linkend="GHook">GHook</link> *new_hook,
                                             <link linkend="GHook">GHook</link> *sibling);
<link linkend="gint">gint</link>        <link linkend="g-hook-compare-ids">g_hook_compare_ids</link>              (<link linkend="GHook">GHook</link> *new_hook,
                                             <link linkend="GHook">GHook</link> *sibling);

<link linkend="GHook">GHook</link>*      <link linkend="g-hook-get">g_hook_get</link>                      (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gulong">gulong</link> hook_id);
<link linkend="GHook">GHook</link>*      <link linkend="g-hook-find">g_hook_find</link>                     (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gboolean">gboolean</link> need_valids,
                                             <link linkend="GHookFindFunc">GHookFindFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="gboolean">gboolean</link>    (<link linkend="GHookFindFunc">*GHookFindFunc</link>)                (<link linkend="GHook">GHook</link> *hook,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="GHook">GHook</link>*      <link linkend="g-hook-find-data">g_hook_find_data</link>                (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gboolean">gboolean</link> need_valids,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="GHook">GHook</link>*      <link linkend="g-hook-find-func">g_hook_find_func</link>                (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gboolean">gboolean</link> need_valids,
                                             <link linkend="gpointer">gpointer</link> func);
<link linkend="GHook">GHook</link>*      <link linkend="g-hook-find-func-data">g_hook_find_func_data</link>           (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gboolean">gboolean</link> need_valids,
                                             <link linkend="gpointer">gpointer</link> func,
                                             <link linkend="gpointer">gpointer</link> data);

<link linkend="GHook">GHook</link>*      <link linkend="g-hook-first-valid">g_hook_first_valid</link>              (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gboolean">gboolean</link> may_be_in_call);
<link linkend="GHook">GHook</link>*      <link linkend="g-hook-next-valid">g_hook_next_valid</link>               (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *hook,
                                             <link linkend="gboolean">gboolean</link> may_be_in_call);
enum        <link linkend="GHookFlagMask">GHookFlagMask</link>;
#define     <link linkend="G-HOOK-FLAGS-CAPS">G_HOOK_FLAGS</link>                    (hook)
#define     <link linkend="G-HOOK-FLAG-USER-SHIFT-CAPS">G_HOOK_FLAG_USER_SHIFT</link>

#define     <link linkend="G-HOOK-CAPS">G_HOOK</link>                          (hook)
#define     <link linkend="G-HOOK-IS-VALID-CAPS">G_HOOK_IS_VALID</link>                 (hook)
#define     <link linkend="G-HOOK-ACTIVE-CAPS">G_HOOK_ACTIVE</link>                   (hook)
#define     <link linkend="G-HOOK-IN-CALL-CAPS">G_HOOK_IN_CALL</link>                  (hook)
#define     <link linkend="G-HOOK-IS-UNLINKED-CAPS">G_HOOK_IS_UNLINKED</link>              (hook)

void        <link linkend="g-hook-ref">g_hook_ref</link>                      (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *hook);
void        <link linkend="g-hook-unref">g_hook_unref</link>                    (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *hook);
void        <link linkend="g-hook-free">g_hook_free</link>                     (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *hook);
<link linkend="gboolean">gboolean</link>    <link linkend="g-hook-destroy">g_hook_destroy</link>                  (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="gulong">gulong</link> hook_id);
void        <link linkend="g-hook-destroy-link">g_hook_destroy_link</link>             (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *hook);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The <link linkend="GHookList">GHookList</link>, <link linkend="GHook">GHook</link> and their related functions provide support for
lists of hook functions. Functions can be added and removed from the lists,
and the list of hook functions can be invoked.

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GHookList">struct GHookList</title>
<programlisting>struct GHookList
{
  gulong	    seq_id;
  guint		    hook_size : 16;
  guint		    is_setup : 1;
  GHook		   *hooks;
  GMemChunk	   *hook_memchunk;
  GHookFinalizeFunc finalize_hook;
  gpointer	    dummy[2];
};
</programlisting>
<para>
The <structname>GHookList</structname> struct represents a 
list of hook functions.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="gulong">gulong</link> <structfield>seq_id</structfield></entry>
<entry>the next free <link linkend="GHook">GHook</link> id.
</entry>
</row>
<row>
<entry><link linkend="guint">guint</link> <structfield>hook_size</structfield> : 16</entry>
<entry>the size of the <link linkend="GHookList">GHookList</link> elements, in bytes.
</entry>
</row>
<row>
<entry><link linkend="guint">guint</link> <structfield>is_setup</structfield> : 1</entry>
<entry>1 if the <link linkend="GHookList">GHookList</link> has been initialized.
</entry>
</row>
<row>
<entry><link linkend="GHook">GHook</link> *<structfield>hooks</structfield></entry>
<entry>the first <link linkend="GHook">GHook</link> element in the list.
</entry>
</row>
<row>
<entry><link linkend="GMemChunk">GMemChunk</link> *<structfield>hook_memchunk</structfield></entry>
<entry>the <link linkend="GMemChunk">GMemChunk</link> used for allocating the <link linkend="GHook">GHook</link> elements.
</entry>
</row>
<row>
<entry><link linkend="GHookFinalizeFunc">GHookFinalizeFunc</link> <structfield>finalize_hook</structfield></entry>
<entry>the function to call to finalize a <link linkend="GHook">GHook</link> element. The
default behaviour is to call the hooks <function>destroy</function> function.
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> <structfield>dummy</structfield>[2]</entry>
<entry>

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GHookFinalizeFunc">GHookFinalizeFunc ()</title>
<programlisting>void        (*GHookFinalizeFunc)            (<link linkend="GHookList">GHookList</link> *hook_list,
                                             <link linkend="GHook">GHook</link> *hook);</programlisting>
<para>
Defines the type of function to be called when a hook in a 
list of hooks gets finalized.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hook_list</parameter>&nbsp;:</entry>
<entry>a <link linkend="GHookList">GHookList</link>.
</entry></row>
<row><entry align="right"><parameter>hook</parameter>&nbsp;:</entry>
<entry>the hook in <parameter>hook_list</parameter> that gets finalized.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GHook">struct GHook</title>
<programlisting>struct GHook
{
  gpointer	 data;
  GHook		*next;
  GHook		*prev;
  guint		 ref_count;
  gulong	 hook_id;
  guint		 flags;
  gpointer	 func;
  GDestroyNotify destroy;
};
</programlisting>
<para>
The <structname>GHook</structname> struct represents a single hook 
function in a <link linkend="GHookList">GHookList</link>.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="gpointer">gpointer</link> <structfield>data</structfield></entry>
<entry>data which is passed to func when this hook is invoked.
</entry>
</row>
<row>
<entry><link linkend="GHook">GHook</link> *<structfield>next</structfield></entry>
<entry>pointer to the next hook in the list.
</entry>
</row>
<row>
<entry><link linkend="GHook">GHook</link> *<structfield>prev</structfield></entry>
<entry>pointer to the previous hook in the list.
</entry>
</row>
<row>
<entry><link linkend="guint">guint</link> <structfield>ref_count</structfield></entry>
<entry>the reference count of this hook.
</entry>
</row>
<row>
<entry><link linkend="gulong">gulong</link> <structfield>hook_id</structfield></entry>
<entry>the id of this hook, which is unique within its list.
</entry>
</row>
<row>
<entry><link linkend="guint">guint</link> <structfield>flags</structfield></entry>
<entry>flags which are set for this hook. See <link linkend="GHookFlagMask">GHookFlagMask</link> for
predefined flags.
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> <structfield>func</structfield></entry>
<entry>the function to call when this hook is invoked. The possible 
signatures for this function are <link linkend="GHookFunc">GHookFunc</link> and <link linkend="GHookCheckFunc">GHookCheckFunc</link>.
</entry>
</row>
<row>
<entry><link linkend="GDestroyNotify">GDestroyNotify</link> <structfield>destroy</structfield></entry>
<entry>the default <function>finalize_hook</function> function of a 
<link linkend="GHookList">GHookList</link> calls this member of the hook that is being finalized.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GHookFunc">GHookFunc ()</title>
<programlisting>void        (*GHookFunc)                    (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Defines the type of a hook function that can be invoked
by <link linkend="g-hook-list-invoke">g_hook_list_invoke</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data field of the <link linkend="GHook">GHook</link> is passed to the hook function here.