Rivl Library Procedures - <B><B>Rivl_GetSignal</B></B> manual page

NAME

Rivl_GetSignal, Rivl_GetSignalList, Rivl_NameOfSignal, Rivl_SignalResult, Rivl_EvalToSignal - translate between signals and their Tcl handles

SYNOPSIS

#include <rivl.h>
int
Rivl_GetSignal(interp, string, signalPtr, validMediaTypes)
int
Rivl_GetSignalList(interp, list, signalsCountPtr, signalsPtr, validMediaTypes)
char *
Rivl_NameOfSignal(signal)
void
Rivl_SignalResult(interp, signal)
int
Rivl_EvalToSignal(interp, command, signalPtr)

ARGUMENTS

Tcl_Interp *interp (in): The Tcl interpreter.
char *string (in): String containing a signal handle.
Rivl_Signal *signalPtr (out): Pointer to location in which to store signal.
char *list (in): String containing a Tcl list of signal handles.
Rivl_Signal **signalsPtr (out): Pointer to location in which to store list of signals.
int *signalsCountPtr (out): Pointer to integer in which to store the length of the list.
int validMediaTypes (in): One or more Rivl_MediaType values OR'd together.
Rivl_Signal signal (in): A signal.
char *command (in): Tcl command which returns a signal handle.

DESCRIPTION

Rivl_GetSignal places in *signalPtr the signal corresponding to string.

Rivl_GetSignalList places in *signalsPtr an array of signals corresponding to the handles in list, and in *signalsCountPtr the length of the list. list must be a well-formed Tcl list suitable for passing to Tcl_SplitList. The array placed in *signalsPtr is dynamically allocated; it is the caller's responsibility to free it.

The validMediaTypes argument in both procedures contains one or more media type constants OR'd together. The retrieved signal or signals must be one of those media types. If validMediaTypes is ANY_MEDIA_TYPE, then any media type is acceptable.

Under normal circumstances these procedures return TCL_OK and leave interp alone. If string or list is not well formed or contains an invalid handle then TCL_ERROR is returned, an error message is left in interp->result, and nothing is stored at *signalPtr, *signalsPtr or *signalsCountPtr.

Rivl_NameOfSignal is the logical inverse of Rivl_GetSignal. It returns a statically-allocated string corresponding to signal.

Rivl_SignalResult places the result of Rivl_NameOfSignal in interp->result.

Rivl_EvalToSignal calls Tcl_Eval to evaluate the command in interp. If the command returns successfully with a signal handle result then the signal corresponding to the handle is placed in *signalPtr, interp->result is reset, and TCL_OK is returned. If the command returns unsucessfully or with a result that is not a vaild signal handle, then an error message is placed in interp->result and TCL_ERROR is returned.