streamCallBack - handle stream calls in OpenMaple
|
Calling Sequence
|
|
streamCallBack(data, name, nargs, args)
|
|
Parameters
|
|
data
|
-
|
user_data pointer passed to StartMaple (void*)
|
name
|
-
|
name of the stream called (char*)
|
nargs
|
-
|
number of arguments in the args array (M_INT)
|
args
|
-
|
array of string arguments (char**)
|
|
|
|
|
Description
|
|
•
|
The Maple math engine and the OpenMaple API communicate using logical streams. The Maple engine interprets a stream as an unevaluated call to a function with a name that begins with "INTERFACE_". Data is sent on a stream either implicitly by various operations (for example, the Maple print function sends its data on the INTERFACE_PRINT stream), or explicitly by a call to the Maple streamcall function. There are several predefined streams. In OpenMaple, most streams map to one of the callback functions. For a complete list of callback functions, see OpenMaple API.
|
•
|
Streams are usually used to output information (as is done by the INTERFACE_PRINT stream), but some streams can also be used to request information. For example, the INTERFACE_READLINE stream is used to request user input during execution of a Maple procedure. In OpenMaple, INTERFACE_READLINE is mapped to the readLineCallBack.
|
•
|
In addition to the predefined streams, a Maple user, or an OpenMaple developer, can create streams by passing a Maple expression of the form, INTERFACE_streamName(arguments), to the streamcall function. If the stream returns a result, the streamcall function returns that result. (You can also send to a stream by passing such an expression to the Maple print function, or by allowing such an expression to be the result of a computation, but in that case, no result can be passed on the stream back to Maple).
|
•
|
The streamCallBack function is called when Maple sends output as a stream that is not explicitly handled by the OpenMaple API.
|
•
|
The prototype for the function you can assign to the entry in the MCallBackVector must look like the following.
|
char * M_DECL streamCallBack( void *data, char *name,
|
M_INT nargs, char **args );
|
|
|
•
|
The name parameter specifies the name of the stream without the "INTERFACE_" prefix.
|
•
|
The nargs parameter indicates the number of arguments passed. If no arguments are passed, nargs is zero.
|
•
|
The args parameter points to an array of string pointers, one for each argument passed. Each string is a line-printed (1-D) Maple expression corresponding to that argument.
|
•
|
The streamCallBack function must return NULL, or a syntactically valid Maple command string.
|
•
|
User-defined streams are an alternative to using the callBackCallBack. Streams have several advantages. The stream name is passed. You can use multiple streams in Maple code, and quickly determine which operation to perform by examining the stream name in the streamCallBack function. Multiple arguments are passed as separate strings, unlike the callBackCallBack function to which multiple arguments are passed as a single comma-separated string. This reduces parsing requirements in the OpenMaple application. The number of arguments is passed, making it easier to test that the correct arguments are passed.
|
•
|
If no streamCallBack function is specified and output is sent to an unknown stream, the arguments to the stream are sent to the callback function to which Maple results are sent, generally, the textCallBack function.
|
•
|
The data parameter contains the same data as passed to StartMaple in the user_data parameter.
|
•
|
Source code for a streamCallBack example is provided in the samples/OpenMaple/HelpExamples subdirectory of your Maple installation.
|
|
|
Examples
|
|
>
|
|
|
|
See Also
|
|
callBackCallBack, CustomWrapper, errorCallBack, OpenMaple, OpenMaple/C/API, OpenMaple/C/Examples, queryInterrupt, readLineCallBack, redirectCallBack, StartMaple, statusCallBack, textCallBack
|
|