# 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