The "c" Package

These routines are meant to provide a general purpose callback management framework. Library packages and applications may use this package to implement their own callback mechanisms. This package removes the need for external code to maintain and traverse callback lists.

Library: karma
Link With: -lkarma

Functions

c_register_callback	Register a callback function with a list.
c_unregister_callback	Unregister a callback function.
c_call_callbacks	Call all registered callbacks for an object.
c_destroy_list	Destroy a callback list.
c_move_callback	Move a callback function.
c_list_dispatching	Test if a callback list is currently dispatching events.
c_list_dispatching2	Test if a callback list is currently dispatching events.
c_list_test_empty	Test if a callback list has any callbacks registered with it.
c_write_null_func	Write NULL to a pointer.
c_write_2nulls_func	Write NULL values to a structure containing two pointers.
c_unregister_callback2	Unregister a callback function.

Prototype Functions

c_PROTO_callback

Generic callback.

Functions

KCallbackFunc c_register_callback (KCallbackList *list, flag (*callback) (), void *object, void *client1_data, flag client1_indirect, void *client2_data, flag client2_indirect, flag quenchable)

This routine will register a function which should be called when the callbacks for an object should be called. When the object is destroyed a call should be made to c_destroy_list. The first callback registered is the first one called. Multiple callback functions may be registered per object.

Parameters:

list : A pointer to the callback list. This is changed. The initial value must be NULL.
callback : The function to be called when the object callbacks are called. The prototype function is c_PROTO_callback.
object : The object pointer passed to the callback. This may be NULL.
client1_data : The first client information pointer passed to the callback. This may be NULL.
client1_indirect : If TRUE the callback is passed a pointer to the storage containing client1_data, else client1_data is passed directly to the callback.
client2_data : The second client information pointer passed to the callback This may be NULL.
client2_indirect : If TRUE the callback is passed a pointer to the storage containing client2_data, else client2_data is passed directly to the callback.
quenchable : If TRUE then the routine is permitted to quench calls to the following callbacks in the list.

Returns: A KCallbackFunc on success. On failure, the process aborts.
Multithreading Level: Unsafe

void c_unregister_callback (KCallbackFunc callback)

Unregister a callback function.

Parameters:

callback : The callback function.

Returns: Nothing.
Multithreading Level: Unsafe

flag c_call_callbacks (KCallbackList list, void *call_data)

Call all registered callbacks for an object.

Parameters:

list : The callback list.
call_data : The arbitrary call information pointer.

Returns: TRUE if one of the callbacks quenched the further delivery of callbacks, else FALSE.
Multithreading Level: Unsafe

void c_destroy_list (KCallbackList list)

This routine will unregister all callbacks in a callback list and then destroys the list.

Parameters:

list : The callback list. This may be NULL (indicating an empty list).

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void c_move_callback (KCallbackFunc callback, flag last)

Move a callback function.

Parameters:

callback : The callback function.
last : If TRUE the callback is placed last in the list, else it is placed first in the list.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag c_list_dispatching (KCallbackList list)

Test if a callback list is currently dispatching events.

Parameters:

list : The callback list.

Returns: TRUE if the list is dispatching, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag c_list_dispatching2 (KCallbackFunc callback)

Test if a callback list is currently dispatching events.

Parameters:

callback : A callback in the list.

Returns: TRUE if the list is dispatching, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag c_list_test_empty (KCallbackList list)

Test if a callback list has any callbacks registered with it.

Parameters:

list : The callback list.

Returns: TRUE if the list is empty (no callbacks), else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void c_write_null_func (void **pointer)

Write NULL to a pointer.

Parameters:

pointer : The pointer to write NULL to.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void c_write_2nulls_func (void *pointer)

Write NULL values to a structure containing two pointers.

Parameters:

pointer : The pointer to the structure to write to.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void c_unregister_callback2 (KCallbackFunc callback)

Unregister a callback function.

Parameters:

callback : The callback function. If this is NULL, nothing is done.

Returns: Nothing.
Multithreading Level: Unsafe

Prototype Functions

flag c_PROTO_callback (void *object, void *client1_data, void *call_data, void *client2_data)

This routine is called when object callbacks are called.

Parameters:

object : The object information pointer.
client1_data : The first client information pointer.
call_data : The call information pointer.
client2_data : The second client information pointer.

Returns: TRUE if further callbacks should not be called, else FALSE.
Multithreading Level: Unsafe

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services