| Top | |
|
|
|
There are many possible ways to set up a gluniversal_t array, and it's
illegal to call gidispatch_call() with an array which doesn't match the
function. Furthermore, some references are passed in, some passed out, and
some both. How do you know how to handle the argument list?
One possibility is to recognize each function selector, and set up the arguments appropriately. However, this entails writing special code for each Glk function; which is exactly what we don't want to do.
Instead, you can call gidispatch_prototype().
char *
gidispatch_prototype (glui32 funcnum);
This returns a string which encodes the proper argument list for the given
function. If there is no such function in the library, this returns NULL.
The prototype string for the glk_glomp<!---->() function described above would be:
"4IuQa&Iu&Qb:".
The "4" is the number of arguments (including the return value, if there is
one, which in this case there isn't.)
"Iu" denotes an unsigned integer; "Qa" is an opaque object of class 0
(window).
"&Iu" is a reference to an unsigned integer, and
"&Qb" is a reference to a stream.
The colon at the end terminates the argument list; the return value would
follow it, if there was one.
Note that the initial number ("4" in this case) is the number of logical
arguments, not the number of gluniversal_t objects which will be passed to
gidispatch_call().
The glk_glomp<!---->() call uses anywhere from four to six gluniversal_t objects,
as demonstrated above.
The basic type codes:
|
Unsigned and signed 32-bit integer. |
|
Character, unsigned char, and signed char. Of course |
|
A C-style string (null-terminated array of char). In Glk,
strings are always treated as read-only and used immediately; the library
does not retain a reference to a string between Glk calls. A Glk call that
wants to use writable char arrays will use an array type
( |
|
A zero-terminated array of 32-bit integers. This is
primarily intended as a Unicode equivalent of |
|
A floating-point value. Glk does not currently use floating-point values, but we might as well define a code for them. |
|
A reference to an opaque object. The second letter
determines which class is involved. (The number of classes can be gleaned
from If Glk expands to have more than 26 classes, we'll think of something. |
Any type code can be prefixed with one or more of the following characters:
|
A reference to the type; or, if you like, a variable passed
by reference. The reference is passed both in and out, so you must copy the
value in before calling |
|
A reference which is pass-out only. The initial value is ignored, so you only need copy out the value after the call. |
|
A reference which is pass-in only. This is not generally used for simple types, but is useful for structures and arrays. |
|
Combined with
Note that even though the |
|
The colon separates the arguments from the return value, or
terminates the string if there is no return value. Since return values are
always non- |
|
Combined with
For example, the prototype string for Currently, structures in Glk contain only basic types. |
|
Combined with Depending on the design of your program, you may wish to pass a pointer directly to your program's memory, or allocate an array and copy the contents in and out. See [Arrays][chimara-Arrays]. |
|
Combined with
For example, |
The order of these characters and prefixes is not completely arbitrary. Here is a formal grammar for the prototype strings.
Thanks to Neil Cerutti for working this out.
|