Racket

C API for Racket Integration🔗ℹ

This section describes the C API exactly as defined in rktwebview.h and rktwebview_types.h. The API is used from Racket through FFI, but is documented here in its native C/C++ form.

The interface is deliberately small. Handles are integers, most operations return a result_t, and structured values are returned as rkt_data_t *. The latter are caller-owned and must be released with rkt_webview_free_data().

1 Version, Export, and Basic Types🔗ℹ

The public API version is:

#define RKT_WEBVIEW_API_MAJOR 0

#define RKT_WEBVIEW_API_MINOR 1

#define RKT_WEBVIEW_API_PATCH 1

The export macro RKTWEBVIEW_EXPORT expands to __declspec(dllexport) or __declspec(dllimport) on Windows, and to an empty definition on other platforms.

The two basic handle types are:

typedef int rktwebview_t;

typedef int rkt_wv_context_t;

rktwebview_t identifies a webview. rkt_wv_context_t identifies a context.

2 Enums and Structured Data🔗ℹ

The API defines the following enums: rkt_webview_loglevel_t, result_t, window_state_t, rkt_messagetype_t, and rkt_data_kind_t. The corresponding values are exactly those given in rktwebview_types.h.

Structured return data uses these types:

typedef struct {

rktwebview_t wv;

char *event;

} rkt_event_t;

typedef struct {

result_t result;

char *value;

} rkt_js_result_t;

typedef struct {

int api_major;

int api_minor;

int api_patch;

} rkt_version_t;

typedef struct {

int shm_usage;

int shm_free_depth;

int shm_free_size;

int shm_item_depth;

int shm_item_size;

double shm_item_usage_factor;

int open_windows;

int function_calls;

int events;

char *log_file;

} rkt_metrics_t;

typedef struct {

rkt_data_kind_t kind;

union {

rkt_version_t version;

rkt_event_t event;

rkt_js_result_t js_result;

rkt_metrics_t metrics;

} data;

} rkt_data_t;

The kind field determines which member of data is valid.

3 Ownership🔗ℹ

Any function returning rkt_data_t * returns allocated memory. The caller must release it using:

RKTWEBVIEW_EXPORT void rkt_webview_free_data(rkt_data_t *d);

This applies to values returned by rkt_webview_info(), rkt_webview_version(), rkt_webview_get_event(), and rkt_webview_call_js().

4 Environment and Runtime Control🔗ℹ

procedure
(rkt_webview_env env_cmds) → void?
env_cmds : any/c

C signature:

RKTWEBVIEW_EXPORT void rkt_webview_env(const char *env_cmds[]);

Sets environment variables before the backend is initialized. The argument is a null-terminated array of const char *, each string typically having the form "NAME=value".

Return value: none.

procedure
(rkt_webview_init) → void?

C signature:

RKTWEBVIEW_EXPORT void rkt_webview_init();

Initializes the backend, creates the shared memory transport, and starts the helper process.

Return value: none.

procedure
(rkt_webview_cleanup) → void?

C signature:

RKTWEBVIEW_EXPORT void rkt_webview_cleanup();

Stops the backend and releases its shared resources. After this call, all previously returned context and webview handles are invalid.

Return value: none.

procedure
(rkt_webview_set_loglevel l) → void?
l : any/c

C signature:

RKTWEBVIEW_EXPORT void rkt_webview_set_loglevel(rkt_webview_loglevel_t l);

Sets the backend log level.

Return value: none.

procedure
(rkt_webview_info) → any/c

C signature:

RKTWEBVIEW_EXPORT rkt_data_t *rkt_webview_info();

Returns a pointer to rkt_data_t. The returned object has kind == metrics; the valid payload is therefore data.metrics.

Return value: rkt_data_t *, caller-owned.

procedure
(rkt_webview_version) → any/c

C signature:

RKTWEBVIEW_EXPORT rkt_data_t *rkt_webview_version();

Returns a pointer to rkt_data_t. The returned object has kind == version; the valid payload is therefore data.version.

Return value: rkt_data_t *, caller-owned.

4.1 Events🔗ℹ

procedure
(rkt_webview_events_waiting) → exact-integer?

C signature:

RKTWEBVIEW_EXPORT int rkt_webview_events_waiting();

Returns the number of events currently waiting in the event queue.

Return value: int.

procedure
(rkt_webview_get_event) → any/c

C signature:

RKTWEBVIEW_EXPORT rkt_data_t *rkt_webview_get_event();

Returns the next pending event. The returned object has kind == event; the valid payload is therefore data.event. If no event is available, the returned pointer may be null.

Return value: rkt_data_t *, caller-owned, or null.

4.1.1 Event Polling🔗ℹ

Events are retrieved explicitly by polling. In normal use, polling should be performed regularly; a polling interval of about 10 ms is appropriate.

This keeps the event queue flowing, allows asynchronous operations such as dialogs to complete in a timely manner, and avoids the impression that the system has stalled while the Racket side is simply not looking.

5 Contexts🔗ℹ

procedure
(rkt_webview_new_context boilerplate_js
optional_server_cert_pem)
→ exact-integer?
boilerplate_js : string?
optional_server_cert_pem : string?

C signature:

RKTWEBVIEW_EXPORT rkt_wv_context_t rkt_webview_new_context(const char *boilerplate_js, const char *optional_server_cert_pem);

Creates a new context. A context corresponds to a QWebEngineProfile; it defines injected JavaScript and optional trust configuration using a trusted self-signed certificate.

Return value: rkt_wv_context_t.

6 Webviews🔗ℹ

procedure
(rkt_webview_create context parent) → exact-integer?
context : exact-integer?
parent : exact-integer?

C signature:

RKTWEBVIEW_EXPORT int rkt_webview_create(rkt_wv_context_t context, rktwebview_t parent);

Creates a new webview in the given context. If parent refers to an existing webview, the new webview is created as a modal child of that parent; otherwise it is created as a top-level window.

Return value: webview handle as int.

procedure
(rkt_webview_close wv) → void?
wv : exact-integer?

C signature:

RKTWEBVIEW_EXPORT void rkt_webview_close(rktwebview_t wv);

Closes the specified webview.

Return value: none.

procedure
(rkt_webview_valid wv) → boolean?
wv : exact-integer?

C signature:

RKTWEBVIEW_EXPORT bool rkt_webview_valid(rktwebview_t wv);

Checks whether wv is a valid webview handle.

Return value: bool.

procedure
(rkt_webview_set_title wv title) → exact-integer?
wv : exact-integer?
title : string?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_set_title(rktwebview_t wv, const char *title);

Sets the window title of the specified webview.

Return value: result_t.

procedure
(rkt_webview_set_ou_token wv token) → void?
wv : exact-integer?
token : string?

C signature:

RKTWEBVIEW_EXPORT void rkt_webview_set_ou_token(rktwebview_t wv, const char *token);

Sets the organizational-unit token used during certificate validation for the specified webview.

Return value: none.

7 Navigation and JavaScript🔗ℹ

procedure
(rkt_webview_set_url wv url) → exact-integer?
wv : exact-integer?
url : string?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_set_url(rktwebview_t wv, const char *url);

Navigates the specified webview to the given URL.

Return value: result_t.

procedure
(rkt_webview_set_html wv html) → exact-integer?
wv : exact-integer?
html : string?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_set_html(rktwebview_t wv, const char *html);

Loads raw HTML into the specified webview.

Return value: result_t.

procedure
(rkt_webview_run_js wv js) → exact-integer?
wv : exact-integer?
js : string?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_run_js(rktwebview_t wv, const char *js);

Executes JavaScript asynchronously in the specified webview.

Return value: result_t.

procedure
(rkt_webview_call_js wv js) → any/c
wv : exact-integer?
js : string?

C signature:

RKTWEBVIEW_EXPORT rkt_data_t *rkt_webview_call_js(rktwebview_t wv, const char *js);

Executes JavaScript synchronously in the specified webview.

The provided JavaScript must end with a return statement. The returned value must be convertible to JSON using JSON.stringify, as the result is serialized and returned as a JSON string.

The returned object has kind == js_result; the valid payload is therefore data.js_result. The field data.js_result.value contains the JSON result string.

Return value: rkt_data_t *, caller-owned.

procedure
(rkt_webview_open_devtools wv) → exact-integer?
wv : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_open_devtools(rktwebview_t wv);

Opens developer tools for the specified webview.

Return value: result_t.

8 Window Management🔗ℹ

procedure
(rkt_webview_move w x y) → exact-integer?
  w : exact-integer?
  x : exact-integer?
  y : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_move(rktwebview_t w, int x, int y);

Moves the specified window to the given screen coordinates.

Return value: result_t.

procedure
(rkt_webview_resize w width height) → exact-integer?
  w : exact-integer?
  width : exact-integer?
  height : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_resize(rktwebview_t w, int width, int height);

Resizes the specified window.

Return value: result_t.

procedure
(rkt_webview_hide w) → exact-integer?
w : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_hide(rktwebview_t w);

Hides the specified window.

Return value: result_t.

procedure
(rkt_webview_show w) → exact-integer?
w : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_show(rktwebview_t w);

Shows the specified window.

Return value: result_t.

procedure
(rkt_webview_show_normal w) → exact-integer?
w : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_show_normal(rktwebview_t w);

Restores the specified window to its normal state.

Return value: result_t.

procedure
(rkt_webview_present w) → exact-integer?
w : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_present(rktwebview_t w);

Presents the specified window to the user.

Return value: result_t.

procedure
(rkt_webview_maximize w) → exact-integer?
w : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_maximize(rktwebview_t w);

Maximizes the specified window.

Return value: result_t.

procedure
(rkt_webview_minimize w) → exact-integer?
w : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_minimize(rktwebview_t w);

Minimizes the specified window.

Return value: result_t.

procedure
(rkt_webview_window_state w) → exact-integer?
w : exact-integer?

C signature:

RKTWEBVIEW_EXPORT window_state_t rkt_webview_window_state(rktwebview_t w);

Returns the current state of the specified window.

Return value: window_state_t.

9 Dialogs🔗ℹ

The dialog functions are asynchronous. They request that the dialog be opened on the Qt side, but do not block the Racket side while the dialog is shown. This is intentional: the Qt event loop and the Racket runtime should not stall each other.

Completion of a dialog is therefore observed through events, not by blocking the calling thread.

procedure
(rkt_webview_choose_dir w title base_dir) → exact-integer?
  w : exact-integer?
  title : string?
  base_dir : string?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_choose_dir(rktwebview_t w, const char *title, const char *base_dir);

Opens a directory chooser associated with the specified webview. This call is asynchronous. The function returns immediately; dialog completion is reported through events.

Return value: result_t.

procedure
(rkt_webview_file_open w
title
base_dir
permitted_exts) → exact-integer?
  w : exact-integer?
  title : string?
  base_dir : string?
  permitted_exts : string?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_file_open(rktwebview_t w, const char *title, const char *base_dir, const char *permitted_exts);

Opens a file-open dialog associated with the specified webview. This call is asynchronous. The function returns immediately; dialog completion is reported through events.

Return value: result_t.

procedure
(rkt_webview_file_save w
title
base_dir
permitted_exts) → exact-integer?
  w : exact-integer?
  title : string?
  base_dir : string?
  permitted_exts : string?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_file_save(rktwebview_t w, const char *title, const char *base_dir, const char *permitted_exts);

Opens a file-save dialog associated with the specified webview. This call is asynchronous. The function returns immediately; dialog completion is reported through events.

Return value: result_t.

procedure
(rkt_webview_message_box w
title
message
submessage
type) → exact-integer?
  w : exact-integer?
  title : string?
  message : string?
  submessage : string?
  type : exact-integer?

C signature:

RKTWEBVIEW_EXPORT result_t rkt_webview_message_box(rktwebview_t w, const char *title, const char *message, const char *submessage, rkt_messagetype_t type);

Opens a message box of the given type, associated with the specified webview. This call is asynchronous. The function returns immediately; dialog completion is reported through events.

Return value: result_t.

10 Remarks🔗ℹ

The API is queue-based. Commands are issued through function calls; events are retrieved explicitly using rkt_webview_events_waiting() and rkt_webview_get_event(). The boundary stays clear: integer handles on the outside, Qt objects on the inside.

Dialog functions are asynchronous and do not block the Racket side while a dialog is shown. Their completion is observed through events.

In normal use, event polling should be performed regularly. A polling interval of about 10 ms is appropriate.

1	Version, Export, and Basic Types
2	Enums and Structured Data
3	Ownership
4	Environment and Runtime Control
5	Contexts
6	Webviews
7	Navigation and Java Script
8	Window Management
9	Dialogs
10	Remarks