Differences between GlkApi and the C Glk API

There are a few differences between glkapi.js and the C Glk API.

Array parameters

When a function needs an array the C API takes a pointer and a length. One example is glk_request_line_event.

void glk_request_line_event( winid_t win, char *buf, glui32 maxlen, glui32 initlen );

GlkApi instead takes only one parameter, which is an array of maxlen length. This can be a typed array, or a normal array.

glk_request_line_event_uni( mainwin, Array( len ), initlen );
glk_request_line_event_uni( mainwin, new Uint32Array( len ), initlen );

String functions

String functions like glk_put_string go one step further, and need the string array to be pre-converted to a JS string.

void glk_put_string(char *s);

glk_put_string( "string" );

glk_fileref_create_by_prompt

The C API version of glk_fileref_create_by_prompt is synchronous: you call it, and (from the perspective of your code) immediately get back the response.

The GlkApi version is asynchronous: control will be passed to GlkOte, and once the file reference has been created VM.resume will be called again, with the fref as the first (and only) argument. If the VM uses GiDispa then the fref is also returned through it. The VM.resume function must be written such that it can handle being called after either glk_fileref_create_by_prompt or glk_select.