ghook.h

00001 /* GLIB - Library of useful routines for C programming
00002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
00003  * Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.
00004  *
00005  * This library is free software; you can redistribute it and/or
00006  * modify it under the terms of the GNU Lesser General Public
00007  * License as published by the Free Software Foundation; either
00008  * version 2 of the License, or (at your option) any later version.
00009  *
00010  * This library is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013  * Lesser General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU Lesser General Public
00016  * License along with this library; if not, write to the
00017  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00018  * Boston, MA 02111-1307, USA.
00019  */
00020 
00021 /*
00022  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
00023  * file for a list of people on the GLib Team.  See the ChangeLog
00024  * files for a list of changes.  These files are distributed with
00025  * GLib at ftp://ftp.gtk.org/pub/gtk/. 
00026  */
00027 
00028 #ifndef __G_HOOK_H__
00029 #define __G_HOOK_H__
00030 
00031 #include <_ansi.h>
00032 #include <glib/gmem.h>
00033 
00034 G_BEGIN_DECLS
00035 
00036 
00037 /* --- typedefs --- */
00038 typedef struct _GHook           GHook;
00039 typedef struct _GHookList       GHookList;
00040 
00041 typedef gint            (*GHookCompareFunc)     (GHook          *new_hook,
00042                                                  GHook          *sibling);
00043 typedef gboolean        (*GHookFindFunc)        (GHook          *hook,
00044                                                  gpointer        data);
00045 typedef void            (*GHookMarshaller)      (GHook          *hook,
00046                                                  gpointer        marshal_data);
00047 typedef gboolean        (*GHookCheckMarshaller) (GHook          *hook,
00048                                                  gpointer        marshal_data);
00049 typedef void            (*GHookFunc)            (gpointer        data);
00050 typedef gboolean        (*GHookCheckFunc)       (gpointer        data);
00051 typedef void            (*GHookFinalizeFunc)    (GHookList      *hook_list,
00052                                                  GHook          *hook);
00053 typedef enum
00054 {
00055   G_HOOK_FLAG_ACTIVE        = 1 << 0,
00056   G_HOOK_FLAG_IN_CALL       = 1 << 1,
00057   G_HOOK_FLAG_MASK          = 0x0f
00058 } GHookFlagMask;
00059 #define G_HOOK_FLAG_USER_SHIFT  (4)
00060 
00061 
00062 /* --- structures --- */
00063 struct _GHookList
00064 {
00065   gulong            seq_id;
00066   guint             hook_size : 16;
00067   guint             is_setup : 1;
00068   GHook            *hooks;
00069   gpointer          dummy3;
00070   GHookFinalizeFunc finalize_hook;
00071   gpointer          dummy[2];
00072 };
00073 struct _GHook
00074 {
00075   gpointer       data;
00076   GHook         *next;
00077   GHook         *prev;
00078   guint          ref_count;
00079   gulong         hook_id;
00080   guint          flags;
00081   gpointer       func;
00082   GDestroyNotify destroy;
00083 };
00084 
00085 
00086 /* --- macros --- */
00087 #define G_HOOK(hook)                    ((GHook*) (hook))
00088 #define G_HOOK_FLAGS(hook)              (G_HOOK (hook)->flags)
00089 #define G_HOOK_ACTIVE(hook)             ((G_HOOK_FLAGS (hook) & \
00090                                           G_HOOK_FLAG_ACTIVE) != 0)
00091 #define G_HOOK_IN_CALL(hook)            ((G_HOOK_FLAGS (hook) & \
00092                                           G_HOOK_FLAG_IN_CALL) != 0)
00093 #define G_HOOK_IS_VALID(hook)           (G_HOOK (hook)->hook_id != 0 && \
00094                                          (G_HOOK_FLAGS (hook) & \
00095                                           G_HOOK_FLAG_ACTIVE))
00096 #define G_HOOK_IS_UNLINKED(hook)        (G_HOOK (hook)->next == NULL && \
00097                                          G_HOOK (hook)->prev == NULL && \
00098                                          G_HOOK (hook)->hook_id == 0 && \
00099                                          G_HOOK (hook)->ref_count == 0)
00100 
00101 
00102 /* --- prototypes --- */
00103 /* callback maintenance functions */
00104 IMPORT_C void    g_hook_list_init               (GHookList              *hook_list,
00105                                          guint                   hook_size);
00106 IMPORT_C void    g_hook_list_clear              (GHookList              *hook_list);
00107 IMPORT_C GHook*  g_hook_alloc                   (GHookList              *hook_list);
00108 IMPORT_C void    g_hook_free                    (GHookList              *hook_list,
00109                                          GHook                  *hook);
00110 IMPORT_C GHook *         g_hook_ref                     (GHookList              *hook_list,
00111                                          GHook                  *hook);
00112 IMPORT_C void    g_hook_unref                   (GHookList              *hook_list,
00113                                          GHook                  *hook);
00114 IMPORT_C gboolean g_hook_destroy                        (GHookList              *hook_list,
00115                                          gulong                  hook_id);
00116 IMPORT_C void    g_hook_destroy_link            (GHookList              *hook_list,
00117                                          GHook                  *hook);
00118 IMPORT_C void    g_hook_prepend                 (GHookList              *hook_list,
00119                                          GHook                  *hook);
00120 IMPORT_C void    g_hook_insert_before           (GHookList              *hook_list,
00121                                          GHook                  *sibling,
00122                                          GHook                  *hook);
00123 IMPORT_C void    g_hook_insert_sorted           (GHookList              *hook_list,
00124                                          GHook                  *hook,
00125                                          GHookCompareFunc        func);
00126 IMPORT_C GHook*  g_hook_get                     (GHookList              *hook_list,
00127                                          gulong                  hook_id);
00128 IMPORT_C GHook*  g_hook_find                    (GHookList              *hook_list,
00129                                          gboolean                need_valids,
00130                                          GHookFindFunc           func,
00131                                          gpointer                data);
00132 IMPORT_C GHook*  g_hook_find_data               (GHookList              *hook_list,
00133                                          gboolean                need_valids,
00134                                          gpointer                data);
00135 IMPORT_C GHook*  g_hook_find_func               (GHookList              *hook_list,
00136                                          gboolean                need_valids,
00137                                          gpointer                func);
00138 IMPORT_C GHook*  g_hook_find_func_data          (GHookList              *hook_list,
00139                                          gboolean                need_valids,
00140                                          gpointer                func,
00141                                          gpointer                data);
00142 /* return the first valid hook, and increment its reference count */
00143 IMPORT_C GHook*  g_hook_first_valid             (GHookList              *hook_list,
00144                                          gboolean                may_be_in_call);
00145 /* return the next valid hook with incremented reference count, and
00146  * decrement the reference count of the original hook
00147  */
00148 IMPORT_C GHook*  g_hook_next_valid              (GHookList              *hook_list,
00149                                          GHook                  *hook,
00150                                          gboolean                may_be_in_call);
00151 /* GHookCompareFunc implementation to insert hooks sorted by their id */
00152 IMPORT_C gint    g_hook_compare_ids             (GHook                  *new_hook,
00153                                          GHook                  *sibling);
00154 /* convenience macros */
00155 #define  g_hook_append( hook_list, hook )  \
00156      g_hook_insert_before ((hook_list), NULL, (hook))
00157 /* invoke all valid hooks with the (*GHookFunc) signature.
00158  */
00159 IMPORT_C void    g_hook_list_invoke             (GHookList              *hook_list,
00160                                          gboolean                may_recurse);
00161 /* invoke all valid hooks with the (*GHookCheckFunc) signature,
00162  * and destroy the hook if FALSE is returned.
00163  */
00164 IMPORT_C void    g_hook_list_invoke_check       (GHookList              *hook_list,
00165                                          gboolean                may_recurse);
00166 /* invoke a marshaller on all valid hooks.
00167  */
00168 IMPORT_C void    g_hook_list_marshal            (GHookList              *hook_list,
00169                                          gboolean                may_recurse,
00170                                          GHookMarshaller         marshaller,
00171                                          gpointer                marshal_data);
00172 IMPORT_C void    g_hook_list_marshal_check      (GHookList              *hook_list,
00173                                          gboolean                may_recurse,
00174                                          GHookCheckMarshaller    marshaller,
00175                                          gpointer                marshal_data);
00176 
00177 G_END_DECLS
00178 
00179 #endif /* __G_HOOK_H__ */
00180