Hook Functions

GLib Reference Manual
<<< Previous Page	Home	Up	Next Page >>>

Details

struct GHookList

struct GHookList
{
  guint		 seq_id;
  guint		 hook_size;
  guint		 is_setup : 1;
  GHook		*hooks;
  GMemChunk	*hook_memchunk;
  GHookFreeFunc	 hook_free; /* virtual function */
  GHookFreeFunc	 hook_destroy; /* virtual function */
};

guint seq_id;	the next free GHook id.
guint hook_size;	the size of the GHookList elements, in bytes.
guint is_setup : 1;	1 if the GHookList has been initialized.
GHook *hooks;	the first GHook element in the list.
GMemChunk *hook_memchunk;	the GMemChunk used for allocating the GHook elements.
GHookFreeFunc hook_free;	the function to call to free a GHook element.
GHookFreeFunc hook_destroy;	the function to call to destory a GHook element.

struct GHook

struct GHook
{
  gpointer	 data;
  GHook		*next;
  GHook		*prev;
  guint		 ref_count;
  guint		 hook_id;
  guint		 flags;
  gpointer	 func;
  GDestroyNotify destroy;
};

gpointer data;	.
GHook *next;	.
GHook *prev;	.
guint ref_count;	.
guint hook_id;	.
guint flags;	.
gpointer data;	.
GDestroyNotify destroy;	.

GHookFunc ()

void        (*GHookFunc)                    (gpointer data);

data :

GHookCheckFunc ()

gboolean    (*GHookCheckFunc)               (gpointer data);

`data` :
Returns :

GHookMarshaller ()

void        (*GHookMarshaller)              (GHook *hook,
                                             gpointer data);

`hook` :
`data` :

GHookCheckMarshaller ()

gboolean    (*GHookCheckMarshaller)         (GHook *hook,
                                             gpointer data);

`hook` :
`data` :
Returns :

GHookFreeFunc ()

void        (*GHookFreeFunc)                (GHookList *hook_list,
                                             GHook *hook);

`hook_list` :
`hook` :

G_HOOK_DEFERRED_DESTROY

#define	G_HOOK_DEFERRED_DESTROY	((GHookFreeFunc) 0x01)

g_hook_list_init ()

void        g_hook_list_init                (GHookList *hook_list,
                                             guint hook_size);

Initializes a GHookList. This must be called before the GHookList is used.

`hook_list` :	a GHookList.
`hook_size` :	the size of each element in the GHookList, typically sizeof (GHook).

g_hook_list_invoke ()

void        g_hook_list_invoke              (GHookList *hook_list,
                                             gboolean may_recurse);

Calls all of the GHook functions in a GHookList.

`hook_list` :	a GHookList.
`may_recurse` :	TRUE if functions which are already running (e.g. in another thread) can be called. If set to FALSE, these are skipped.

g_hook_list_invoke_check ()

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 TRUE is removed from the GHookList.

`hook_list` :	a GHookList.
`may_recurse` :	TRUE if functions which are already running (e.g. in another thread) can be called. If set to FALSE, these are skipped.

g_hook_list_marshal ()

void        g_hook_list_marshal             (GHookList *hook_list,
                                             gboolean may_recurse,
                                             GHookMarshaller marshaller,
                                             gpointer data);

`hook_list` :	a GHookList.
`may_recurse` :
`marshaller` :
`data` :

g_hook_list_marshal_check ()

void        g_hook_list_marshal_check       (GHookList *hook_list,
                                             gboolean may_recurse,
                                             GHookCheckMarshaller marshaller,
                                             gpointer data);

`hook_list` :	a GHookList.
`may_recurse` :
`marshaller` :
`data` :

g_hook_list_clear ()

void        g_hook_list_clear               (GHookList *hook_list);

Removes all the GHook elements from a GHookList.

hook_list : a GHookList.

g_hook_alloc ()

GHook*      g_hook_alloc                    (GHookList *hook_list);

Allocates space for a GHook and initializes it.

`hook_list` :	a GHookList.
Returns :	a new GHook.

g_hook_append()

#define     g_hook_append( hook_list, hook )

Appends a GHook onto the end of a GHookList.

`hook_list` :	a GHookList.
`hook` :	the GHook to add to the end of `hook_list`.

g_hook_prepend ()

void        g_hook_prepend                  (GHookList *hook_list,
                                             GHook *hook);

Prepends a GHook on the start of a GHookList.

`hook_list` :	a GHookList.
`hook` :	the GHook to add to the start of `hook_list`.

g_hook_insert_before ()

void        g_hook_insert_before            (GHookList *hook_list,
                                             GHook *sibling,
                                             GHook *hook);

Inserts a GHook into a GHookList, before a given GHook.

`hook_list` :	a GHookList.
`sibling` :	the GHook to insert the new GHook before.
`hook` :	the GHook to insert.

g_hook_insert_sorted ()

void        g_hook_insert_sorted            (GHookList *hook_list,
                                             GHook *hook,
                                             GHookCompareFunc func);

Inserts a GHook into a GHookList, sorted by the given function.

`hook_list` :	a GHookList.
`hook` :	the GHook to insert.
`func` :	the comparison function used to sort the GHook elements.

GHookCompareFunc ()

gint        (*GHookCompareFunc)             (GHook *new_hook,
                                             GHook *sibling);

Defines the type of function used to compare GHook elements in g_hook_insert_sorted().

`new_hook` :	the GHook being inserted.
`sibling` :	the GHook to compare with `new_hook`.
Returns :	a value <= 0 if `new_hook` should be before `sibling`.

g_hook_compare_ids ()

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.

`new_hook` :	a GHook.
`sibling` :	a GHook to compare with `new_hook`.
Returns :	a value <= 0 if the id of `sibling` is >= the id of `new_hook`.

g_hook_get ()

GHook*      g_hook_get                      (GHookList *hook_list,
                                             guint hook_id);

Returns the GHook with the given id, or NULL if it is not found.

`hook_list` :	a GHookList.
`hook_id` :	a hook id.
Returns :	the GHook with the given id, or NULL if it is not found.

g_hook_find ()

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.

`hook_list` :	a GHookList.
`need_valids` :	TRUE if GHook elements which have been destroyed should be skipped.
`func` :	the function to call for each GHook, which should return TRUE when the GHook has been found.
`data` :	the data passed to `func`.
Returns :	the found GHook or NULL if no matching GHook is found.

g_hook_find_data ()

GHook*      g_hook_find_data                (GHookList *hook_list,
                                             gboolean need_valids,
                                             gpointer data);

Finds a GHook in a GHookList with the given data.

`hook_list` :	a GHookList.
`need_valids` :	TRUE if GHook elements which have been destroyed should be skipped.
`data` :	the data to find.
Returns :	the GHook with the given `data` or NULL if no matching GHook is found.

g_hook_find_func ()

GHook*      g_hook_find_func                (GHookList *hook_list,
                                             gboolean need_valids,
                                             gpointer func);

Finds a GHook in a GHookList with the given function.

`hook_list` :	a GHookList.
`need_valids` :	TRUE if GHook elements which have been destroyed should be skipped.
`func` :	the function to find.
Returns :	the GHook with the given `func` or NULL if no matching GHook is found.

GHookFindFunc ()

gboolean    (*GHookFindFunc)                (GHook *hook,
                                             gpointer data);

Defines the type of the function passed to g_hooK_find_func().

`hook` :	a GHook.
`data` :	user data passed to g_hook_find_func().
Returns :	TRUE if the required GHook has been found.

g_hook_find_func_data ()

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.

`hook_list` :	a GHookList.
`need_valids` :	TRUE if GHook elements which have been destroyed should be skipped.
`func` :	the function to find.
`data` :	the data to find.
Returns :	the GHook with the given `func` and `data` or NULL if no matching GHook is found.

g_hook_first_valid ()

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.)

`hook_list` :	a GHookList.
`may_be_in_call` :	TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to FALSE, these are skipped.
Returns :	the first valid GHook, or NULL if none are valid.

g_hook_next_valid ()

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.)

`hook_list` :	a GHookList.
`hook` :	the current GHook.
`may_be_in_call` :	TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to FALSE, these are skipped.
Returns :	the next valid GHook, or NULL if none are valid.

enum GHookFlagMask

typedef enum
{
  G_HOOK_FLAG_ACTIVE	= 1 << 0,
  G_HOOK_FLAG_IN_CALL	= 1 << 1,
  G_HOOK_FLAG_MASK	= 0x0f
} GHookFlagMask;

G_HOOK_FLAG_USER_SHIFT

#define G_HOOK_FLAG_USER_SHIFT	(4)

G_HOOK_IS_VALID()

#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.

`hook` :	a GHook.
Returns :	TRUE if the GHook is valid.

G_HOOK_ACTIVE()

#define     G_HOOK_ACTIVE(hook)

Returns TRUE if the GHook is active, which is normally TRUE until the GHook is destroyed.

`hook` :	a GHook.
Returns :	TRUE if the GHook is active.

G_HOOK_IN_CALL()

#define     G_HOOK_IN_CALL(hook)

Returns TRUE if the GHook function is currently executing.

`hook` :	a GHook.
Returns :	TRUE if the GHook function is currently executing.

G_HOOK_IS_UNLINKED()

#define     G_HOOK_IS_UNLINKED(hook)

Returns TRUE if the GHook is not in a GHookList.

`hook` :	a GHook.
Returns :	TRUE if the GHook is not in a GHookList.

g_hook_ref ()

void        g_hook_ref                      (GHookList *hook_list,
                                             GHook *hook);

Increments the reference count for a GHook.

`hook_list` :	a GHookList.
`hook` :	the GHook to increment the reference count of.

g_hook_unref ()

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.

`hook_list` :	a GHookList.
`hook` :

g_hook_free ()

void        g_hook_free                     (GHookList *hook_list,
                                             GHook *hook);

Calls the GHookList hook_free function if it exists, and frees the memory allocated for the GHook.

`hook_list` :	a GHookList.
`hook` :	the GHook to free.

g_hook_destroy ()

gboolean    g_hook_destroy                  (GHookList *hook_list,
                                             guint hook_id);

Destroys a GHook, given its ID.

`hook_list` :	a GHookList.
`hook_id` :	a hook ID.
Returns :	TRUE if the GHook was found in the GHookList and destroyed.

g_hook_destroy_link ()

void        g_hook_destroy_link             (GHookList *hook_list,
                                             GHook *hook);

Removes one GHook from a GHookList, calling the hook_destroy function in the GHookList, and the destroy function of the GHook, if they exist.

`hook_list` :	a GHookList.
`hook` :	the GHook to remove.