![]() |
![]() |
![]() |
GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <glib.h> GHookList; void (*GHookFinalizeFunc) (GHookList *hook_list, GHook *hook); GHook; void (*GHookFunc) (gpointer data); gboolean (*GHookCheckFunc) (gpointer data); void g_hook_list_init (GHookList *hook_list, guint hook_size); void g_hook_list_invoke (GHookList *hook_list, gboolean may_recurse); void g_hook_list_invoke_check (GHookList *hook_list, gboolean may_recurse); void g_hook_list_marshal (GHookList *hook_list, gboolean may_recurse, GHookMarshaller marshaller, gpointer marshal_data); void (*GHookMarshaller) (GHook *hook, gpointer marshal_data); void g_hook_list_marshal_check (GHookList *hook_list, gboolean may_recurse, GHookCheckMarshaller marshaller, gpointer marshal_data); gboolean (*GHookCheckMarshaller) (GHook *hook, gpointer marshal_data); void g_hook_list_clear (GHookList *hook_list); GHook* g_hook_alloc (GHookList *hook_list); #define g_hook_append ( hook_list, hook ) void g_hook_prepend (GHookList *hook_list, GHook *hook); void g_hook_insert_before (GHookList *hook_list, GHook *sibling, GHook *hook); void g_hook_insert_sorted (GHookList *hook_list, GHook *hook, GHookCompareFunc func); gint (*GHookCompareFunc) (GHook *new_hook, GHook *sibling); gint g_hook_compare_ids (GHook *new_hook, GHook *sibling); GHook* g_hook_get (GHookList *hook_list, gulong hook_id); GHook* g_hook_find (GHookList *hook_list, gboolean need_valids, GHookFindFunc func, gpointer data); gboolean (*GHookFindFunc) (GHook *hook, gpointer data); GHook* g_hook_find_data (GHookList *hook_list, gboolean need_valids, gpointer data); GHook* g_hook_find_func (GHookList *hook_list, gboolean need_valids, gpointer func); GHook* g_hook_find_func_data (GHookList *hook_list, gboolean need_valids, gpointer func, gpointer data); GHook* g_hook_first_valid (GHookList *hook_list, gboolean may_be_in_call); GHook* g_hook_next_valid (GHookList *hook_list, GHook *hook, gboolean may_be_in_call); enum GHookFlagMask; #define G_HOOK_FLAGS (hook) #define G_HOOK_FLAG_USER_SHIFT #define G_HOOK (hook) #define G_HOOK_IS_VALID (hook) #define G_HOOK_ACTIVE (hook) #define G_HOOK_IN_CALL (hook) #define G_HOOK_IS_UNLINKED (hook) GHook * g_hook_ref (GHookList *hook_list, GHook *hook); void g_hook_unref (GHookList *hook_list, GHook *hook); void g_hook_free (GHookList *hook_list, GHook *hook); gboolean g_hook_destroy (GHookList *hook_list, gulong hook_id); void g_hook_destroy_link (GHookList *hook_list, GHook *hook);
The GHookList, GHook 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.
typedef struct { gulong seq_id; guint hook_size : 16; guint is_setup : 1; GHook *hooks; gpointer dummy3; GHookFinalizeFunc finalize_hook; gpointer dummy[2]; } GHookList;
The GHookList struct represents a list of hook functions.
gulong |
the next free GHook id |
guint |
the size of the GHookList elements, in bytes |
guint |
1 if the GHookList has been initialized |
GHook * |
the first GHook element in the list |
gpointer |
unused |
GHookFinalizeFunc |
the function to call to finalize a GHook element. The
default behaviour is to call the hooks destroy function
|
gpointer |
unused |
void (*GHookFinalizeFunc) (GHookList *hook_list, GHook *hook);
Defines the type of function to be called when a hook in a list of hooks gets finalized.
|
a GHookList |
|
the hook in hook_list that gets finalized
|
typedef struct { gpointer data; GHook *next; GHook *prev; guint ref_count; gulong hook_id; guint flags; gpointer func; GDestroyNotify destroy; } GHook;
The GHook struct represents a single hook function in a GHookList.
gpointer |
data which is passed to func when this hook is invoked |
GHook * |
pointer to the next hook in the list |
GHook * |
pointer to the previous hook in the list |
guint |
the reference count of this hook |
gulong |
the id of this hook, which is unique within its list |
guint |
flags which are set for this hook. See GHookFlagMask for predefined flags |
gpointer |
the function to call when this hook is invoked. The possible signatures for this function are GHookFunc and GHookCheckFunc |
GDestroyNotify |
the default finalize_hook function of a
GHookList calls this member of the hook that is being finalized
|
void (*GHookFunc) (gpointer data);
Defines the type of a hook function that can be invoked
by g_hook_list_invoke()
.
|
the data field of the GHook is passed to the hook function here |
gboolean (*GHookCheckFunc) (gpointer data);
Defines the type of a hook function that can be invoked
by g_hook_list_invoke_check()
.
void g_hook_list_init (GHookList *hook_list, guint hook_size);
Initializes a GHookList. This must be called before the GHookList is used.
void g_hook_list_invoke_check (GHookList *hook_list, gboolean may_recurse);
Calls all of the GHook functions in a GHookList.
Any function which returns FALSE
is removed from the GHookList.
void g_hook_list_marshal (GHookList *hook_list, gboolean may_recurse, GHookMarshaller marshaller, gpointer marshal_data);
Calls a function on each valid GHook.
void (*GHookMarshaller) (GHook *hook, gpointer marshal_data);
Defines the type of function used by g_hook_list_marshal()
.
|
a GHook |
|
user data |
void g_hook_list_marshal_check (GHookList *hook_list, gboolean may_recurse, GHookCheckMarshaller marshaller, gpointer marshal_data);
Calls a function on each valid GHook and destroys it if the
function returns FALSE
.
gboolean (*GHookCheckMarshaller) (GHook *hook, gpointer marshal_data);
Defines the type of function used by g_hook_list_marshal_check()
.
|
a GHook |
|
user data |
Returns : |
%FALSE if hook should be destroyed
|
void g_hook_list_clear (GHookList *hook_list);
Removes all the GHook elements from a GHookList.
|
a GHookList |
GHook* g_hook_alloc (GHookList *hook_list);
Allocates space for a GHook and initializes it.
void g_hook_insert_before (GHookList *hook_list, GHook *sibling, GHook *hook);
void g_hook_insert_sorted (GHookList *hook_list, GHook *hook, GHookCompareFunc func);
Inserts a GHook into a GHookList, sorted by the given function.
gint (*GHookCompareFunc) (GHook *new_hook, GHook *sibling);
Defines the type of function used to compare GHook elements in
g_hook_insert_sorted()
.
gint g_hook_compare_ids (GHook *new_hook, GHook *sibling);
Compares the ids of two GHook elements, returning a negative value if the second id is greater than the first.
GHook* g_hook_get (GHookList *hook_list, gulong hook_id);
Returns the GHook with the given id, or NULL
if it is not found.
GHook* g_hook_find (GHookList *hook_list, gboolean need_valids, GHookFindFunc func, gpointer data);
Finds a GHook in a GHookList using the given function to test for a match.
|
a GHookList |
|
%TRUE if GHook elements which have been destroyed should be skipped |
|
the function to call for each GHook, which should return TRUE when
the GHook has been found
|
|
the data to pass to func
|
Returns : |
the found GHook or NULL if no matching GHook is found
|
gboolean (*GHookFindFunc) (GHook *hook, gpointer data);
Defines the type of the function passed to g_hook_find()
.
|
a GHook |
|
user data passed to g_hook_find_func()
|
Returns : |
%TRUE if the required GHook has been found |
GHook* g_hook_find_data (GHookList *hook_list, gboolean need_valids, gpointer data);
GHook* g_hook_find_func (GHookList *hook_list, gboolean need_valids, gpointer func);
GHook* g_hook_find_func_data (GHookList *hook_list, gboolean need_valids, gpointer func, gpointer data);
Finds a GHook in a GHookList with the given function and data.
GHook* g_hook_first_valid (GHookList *hook_list, gboolean may_be_in_call);
Returns the first GHook in a GHookList which has not been destroyed.
The reference count for the GHook is incremented, so you must call
g_hook_unref()
to restore it when no longer needed. (Or call
g_hook_next_valid()
if you are stepping through the GHookList.)
GHook* g_hook_next_valid (GHookList *hook_list, GHook *hook, gboolean may_be_in_call);
Returns the next GHook in a GHookList which has not been destroyed.
The reference count for the GHook is incremented, so you must call
g_hook_unref()
to restore it when no longer needed. (Or continue to call
g_hook_next_valid()
until NULL
is returned.)
typedef enum { G_HOOK_FLAG_ACTIVE = 1 << 0, G_HOOK_FLAG_IN_CALL = 1 << 1, G_HOOK_FLAG_MASK = 0x0f } GHookFlagMask;
Flags used internally in the GHook implementation.
#define G_HOOK_FLAGS(hook) (G_HOOK (hook)->flags)
Returns the flags of a hook.
|
a GHook |
#define G_HOOK_FLAG_USER_SHIFT (4)
The position of the first bit which is not reserved for internal
use be the GHook implementation, i.e.
1 << G_HOOK_FLAG_USER_SHIFT
is the first bit
which can be used for application-defined flags.
#define G_HOOK_IS_VALID(hook)
Returns TRUE
if the GHook is valid, i.e. it is in a GHookList, it is active
and it has not been destroyed.
#define G_HOOK_ACTIVE(hook)
Returns TRUE
if the GHook is active, which is normally TRUE
until the GHook
is destroyed.
GHook * g_hook_ref (GHookList *hook_list, GHook *hook);
Increments the reference count for a GHook.
void g_hook_unref (GHookList *hook_list, GHook *hook);
Decrements the reference count of a GHook.
If the reference count falls to 0, the GHook is removed from the GHookList
and g_hook_free()
is called to free it.
void g_hook_free (GHookList *hook_list, GHook *hook);
Calls the GHookList finalize_hook
function if it exists, and frees the memory
allocated for the GHook.
gboolean g_hook_destroy (GHookList *hook_list, gulong hook_id);
Destroys a GHook, given its ID.