streamCallBack - handle stream calls in OpenMaple
|
Calling Sequence
|
|
streamCallBack(data, name, nargs, args)
|
|
Parameters
|
|
data
|
-
|
user_data pointer passed to StartMaple (Long)
|
name
|
-
|
name of the stream called (byte array pointer)
|
nargs
|
-
|
number of arguments in the args array (Long)
|
args
|
-
|
array of string arguments (array of byte arrays)
|
|
|
|
|
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 typically 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 MapleCallBack must look like the following.
|
Function lpStreamCallBack(ByVal data As Long,
|
ByVal name as Long,
|
ByVal nargs as Long,
|
ByVal args As Long) as Long
|
|
|
•
|
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 the argument list. The ith argument can be fetched using the following command.
|
arg = MaplePointerToString(MapleGetArg(args, i))
|
|
|
|
Each string is a line-printed (1-D) Maple expression corresponding to that argument. The first argument is at i=0, and the last is at i=nargs-1. Using MapleGetArg() outside this range is invalid.
|
•
|
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.
|
|
|
Examples
|
|
Function StreamCallBack(ByVal data As Long, ByVal name As Long, _
|
ByVal nargs As Long, ByVal args As Long) As Long
|
Dim r, arg, fname As String
|
Dim i As Long
|
fname = MaplePointerToString(name)
|
If fname = "TEST" Then
|
r = "0"
|
For i = 0 To nargs - 1
|
arg = MaplePointerToString(MapleGetArg(args, i))
|
r = r + " + " + arg
|
Next i
|
StreamCallBack = MapleStringToPointer(r + ";")
|
Else
|
StreamCallBack = MapleStringToPointer("0;")
|
End If
|
End Function
|
' assignment to MapleCallback entry
|
cb.lpStreamCallBack = GetProc(AddressOf StreamCallBack)
|
' test statement that will invoke the CallBackCallBack
|
EvalMapleStatement kv, "streamcall(INTERFACE_TEST(x^2,3*x,1));"
|
|
|
|
|
See Also
|
|
callBackCallBack, errorCallBack, OpenMaple, OpenMaple/VB/API, OpenMaple/VB/Examples, queryInterrupt, readLineCallBack, redirectCallBack, StartMaple, statusCallBack, textCallBack
|
|