The "chm" Package

These routines are meant to provide a generic and simple to use channel management facility (i.e. event processing on pipes, connections and terminals). A similar set of routines: chx_ provide identical functionality (with the exception of the polling routine), except that they rely on the Xt Intrinsics event dispatching system.

Library: karma
Link With: -lkarma

Functions

chm_manage	Manage a channel for activity by registering callback routines.
chm_unmanage	Terminate the management of a channel for activity.
chm_poll	Poll all managed channels for any activity.

Prototype Functions

CHM_PROTO_input_func	This routine is called when new input occurs on a channel.
CHM_PROTO_close_func	This routine is called when a channel closes.
CHM_PROTO_output_func	This routine is called when a channel becomes ready for writing.
CHM_PROTO_exception_func	This routine is called when an exception occurs on channel.

Functions

flag chm_manage ( Channel channel, void *info, flag (*input_func) (), void (*close_func) (), flag (*output_func) (), flag (*exception_func) () )

Manage a channel for activity by registering callback routines.

Parameters:

channel : The channel object to manage.
info : The arbitrary information pointer associated with the managed channel. This pointer may be modified by the callback routines.
input_func : This routine is called when new input occurs on the channel. If this is NULL, no callback routine is installed. The prototype function is CHM_PROTO_input_func.
close_func : This routine is called when the channel closes. If this is NULL, no callback routine is installed. The prototype function is CHM_PROTO_close_func. The channel object MUST be capable of detecting closure if this routine is supplied (i.e. this routine cannot be supplied for dock channels). Any unread buffered data in the channel will be lost upon closure. The call to this function is the last chance to read this buffered data.
output_func : This routine is called when the channel becomes ready for output. If this is NULL, no callback routine is installed. The prototype function is CHM_PROTO_output_func.
exception_func : This routine is called when exceptions occur on the channel. If this is NULL, no callback routine is installed. The prototype function is CHM_PROTO_exception_func.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

void chm_unmanage (Channel channel)

Terminate the management of a channel for activity.

Parameters:

channel : The channel object to unmanage.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

This routine will NOT close the channel (nor does it assume the channel is open).

void chm_poll (long timeout_ms)

Poll all managed channels for any activity.

Parameters:

timeout_ms : The time (in milliseconds) to poll. If this is less than 0 the routine will poll forever (until some activity occurs or a signal is caught).

Returns: Nothing.
Multithreading Level: Unsafe

Prototype Functions

flag CHM_PROTO_input_func (Channel channel, void **info)

This routine is called when new input occurs on a channel.

Parameters:

channel : The channel object.
info : A pointer to the arbitrary information pointer. This may be modified

Returns: TRUE if the channel is to remain managed and open, else FALSE (indicating that the channel is to be unmanaged and closed).
Multithreading Level: Unsafe
Note:

This routine MUST NOT unmanage or close the channel.
The close_func will be called if this routine returns FALSE.

void CHM_PROTO_close_func (Channel channel, void *info)

This routine is called when a channel closes.

Parameters:

channel : The channel object.
info : The arbitrary pointer for the channel.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

This routine MUST NOT unmanage the channel. The channel will be automatically unmanaged and deleted upon closure (even if no close_func is specified).

flag CHM_PROTO_output_func (Channel channel, void **info)

This routine is called when a channel becomes ready for writing.

Parameters:

channel : The channel object.
info : A pointer to the arbitrary information pointer. This may be modified

Returns: TRUE if the channel is to remain managed and open, else FALSE (indicating that the channel is to be unmanaged and closed).
Multithreading Level: Unsafe
Note:

This routine MUST NOT unmanage or close the channel.
The close_func will be called if this routine returns FALSE.

flag CHM_PROTO_exception_func (Channel channel, void **info)

This routine is called when an exception occurs on channel.

Parameters:

channel : The channel object.
info : A pointer to the arbitrary information pointer. This may be modified

Returns: TRUE if the channel is to remain managed and open, else FALSE (indicating that the channel is to be unmanaged and closed).
Multithreading Level: Unsafe
Note:

This routine MUST NOT unmanage or close the channel.
The close_func will be called if this routine returns FALSE.

Contact: Richard Gooch
Web Development: Ariel Internet Services