348 lines
9.9 KiB
Racket
348 lines
9.9 KiB
Racket
#lang scribble/manual
|
||
|
||
@title{Public API Specification for the Qt–Backed WebView Bridge}
|
||
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
|
||
|
||
@italic{For use with Racket FFI}
|
||
|
||
This document defines the public C-level API of the Qt-based WebView bridge.
|
||
It targets Racket developers integrating the C library via the Racket FFI.
|
||
It specifies the interface, result values, memory ownership rules, event formats,
|
||
expected behavior, and recommended calling patterns. Internal architecture is documented separately.
|
||
|
||
@section{Calling Convention and Structure}
|
||
|
||
All functions are C functions with normal C linkage.
|
||
Window handles are simple integers that uniquely identify native windows.
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{Header: @tt{rktwebview.h}}
|
||
@item{ABI: plain C, no name mangling}
|
||
@item{Handles remain valid from creation until the window is fully closed}
|
||
]
|
||
|
||
|
||
@section{Opaque and Helper Types}
|
||
|
||
@subsection{Window Handle}
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{typedef int rktwebview_t}: Valid for any window created by @tt{rkt_webview_create} until closed.}
|
||
]
|
||
|
||
@subsection{Event Callback Types}
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{typedef struct \{ rktwebview_t wv; char* event; \} rkt_event_t}: JSON event payload for the host (UTF‐8).}
|
||
@item{@tt{typedef void (*event_cb_t)(rkt_event_t*)}: Host-supplied callback for event delivery.}
|
||
]
|
||
|
||
@subsection{JS Result Structure}
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{typedef struct \{ result_t result; char* value; \} rkt_js_result_t}: @tt{result} is always @tt{oke} or @tt{eval_js_failed}; @tt{value} holds a UTF‐8 JSON string describing the JS outcome.}
|
||
]
|
||
|
||
|
||
@section{Enumerations}
|
||
|
||
@subsection{result_t}
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{oke = 0}}
|
||
@item{@tt{set_html_failed = 1}}
|
||
@item{@tt{set_navigate_failed = 2}}
|
||
@item{@tt{eval_js_failed = 3}}
|
||
@item{@tt{move_failed = 12}}
|
||
@item{@tt{resize_failed = 13}}
|
||
@item{@tt{choose_dir_failed = 14}}
|
||
@item{@tt{open_file_failed = 15}}
|
||
@item{@tt{save_file_failed = 16}}
|
||
@item{@tt{failed = 17}}
|
||
]
|
||
|
||
@subsection{window_state_t}
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{invalid = -1}}
|
||
@item{@tt{normal = 0}}
|
||
@item{@tt{minimized = 1}}
|
||
@item{@tt{maximized = 2}}
|
||
@item{@tt{hidden = 3}}
|
||
@item{@tt{normal_active = 16}}
|
||
@item{@tt{maximized_active = 18}}
|
||
]
|
||
|
||
|
||
@section{Threading Model}
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{All GUI work occurs on the Qt GUI thread.}
|
||
@item{Public calls block until the posted internal command has completed.}
|
||
@item{The host is expected to drive Qt by calling @tt{rkt_webview_process_events}.}
|
||
]
|
||
|
||
|
||
@section{Memory Ownership}
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{rkt_event_t*} must be freed using @tt{rkt_webview_destroy_event}.}
|
||
@item{@tt{rkt_js_result_t*} must be freed using @tt{rkt_webview_destroy_js_result}.}
|
||
@item{All returned strings are UTF‐8 and owned by the library until destroyed with the corresponding function.}
|
||
]
|
||
|
||
|
||
@section{Function Reference (C signatures)}
|
||
|
||
The following are literal C signatures with behavioral descriptions.
|
||
|
||
@subsection{Initialization and Event Pumping}
|
||
|
||
@codeblock{
|
||
void rkt_webview_init(void);
|
||
}
|
||
Initializes Qt and internal state. Safe to call multiple times (subsequent calls are no-ops).
|
||
|
||
@codeblock{
|
||
void rkt_webview_process_events(int for_ms);
|
||
}
|
||
Pumps the Qt event loop for approximately @tt{for_ms} milliseconds.
|
||
|
||
Idea for implementation in racket:
|
||
Use a @emph{cooperative thread} with @emph{time slicing}. A practical starting point:
|
||
@itemlist[#:style 'compact
|
||
@item{~3 ms Qt pumping per iteration: @tt{(rkt_webview_process_events 3)}}
|
||
@item{~10 ms Racket time (scheduler): @tt{(sleep 0.01)}}
|
||
]
|
||
Tune these values for your application.
|
||
|
||
Example:
|
||
|
||
@verbatim|{
|
||
(define running? (box #t))
|
||
|
||
(define (pump-loop)
|
||
(let loop ()
|
||
(when (unbox running?)
|
||
(rkt_webview_process_events 3) ; ~3 ms Qt
|
||
(sleep 0.01) ; ~10 ms for Racket scheduler
|
||
(loop))))
|
||
|
||
(define pump-thread (thread pump-loop))
|
||
|
||
;; ... later on shutdown:
|
||
(set-box! running? #f)
|
||
(thread-wait pump-thread)
|
||
}|
|
||
|
||
|
||
@subsection{Window Lifecycle}
|
||
|
||
@codeblock{
|
||
rktwebview_t rkt_webview_create(rktwebview_t parent, event_cb_t cb);
|
||
}
|
||
Creates a window, optionally modal if @tt{parent} exists. Registers @tt{cb}.
|
||
The window is shown before returning.
|
||
|
||
@codeblock{
|
||
void rkt_webview_close(rktwebview_t wv);
|
||
}
|
||
Requests closure of @tt{wv}.
|
||
|
||
Behavior:
|
||
@itemlist[#:style 'compact
|
||
@item{If the user tries to close via the window manager (close button, Alt–F4, etc.), the library intercepts it and emits @tt{"can-close?"}. The window remains open.}
|
||
@item{To actually close after receiving @tt{"can-close?"}, the host must call @tt{rkt_webview_close}.}
|
||
@item{When the final close occurs, @tt{"closed"} is emitted and the handle becomes invalid.}
|
||
]
|
||
|
||
@codeblock{
|
||
bool rkt_webview_valid(rktwebview_t wv);
|
||
}
|
||
Returns whether @tt{wv} refers to an active window.
|
||
|
||
|
||
@subsection{Navigation and Content}
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_set_url(rktwebview_t wv, const char* url);
|
||
}
|
||
Navigate to @tt{url}. Returns @tt{oke} or @tt{set_navigate_failed}.
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_set_html(rktwebview_t wv, const char* html);
|
||
}
|
||
Set page content from @tt{html}. Returns @tt{oke} or @tt{set_html_failed}.
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_set_title(rktwebview_t wv, const char* title);
|
||
}
|
||
Set the native window title. Returns @tt{oke} or @tt{failed}.
|
||
|
||
|
||
@subsection{JavaScript Execution}
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_run_js(rktwebview_t wv, const char* js);
|
||
}
|
||
Fire-and-forget JavaScript execution. Returns @tt{oke} or @tt{eval_js_failed}.
|
||
|
||
@codeblock{
|
||
rkt_js_result_t* rkt_webview_call_js(rktwebview_t wv, const char* js);
|
||
}
|
||
Synchronous JS call. Guarantees:
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{result} is @tt{oke} or @tt{eval_js_failed}.}
|
||
@item{@tt{value} is JSON: @tt{{"oke": <bool>, "result": <value-or-false>, "exn": <string-or-false>}}.}
|
||
]
|
||
Must be freed with @tt{rkt_webview_destroy_js_result()}.
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_destroy_js_result(rkt_js_result_t* r);
|
||
}
|
||
Frees JS result memory. Returns @tt{oke}.
|
||
|
||
|
||
@subsection{Developer Tools}
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_open_devtools(rktwebview_t wv);
|
||
}
|
||
Open devtools. Returns @tt{oke} or @tt{no_devtools_on_platform} (platform-dependent).
|
||
|
||
|
||
@subsection{Window Geometry and Visibility}
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_move(rktwebview_t wv, int x, int y);
|
||
}
|
||
Waits until move is acknowledged. Returns @tt{oke} or @tt{move_failed}.
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_resize(rktwebview_t wv, int w, int h);
|
||
}
|
||
Waits until resize is acknowledged. Returns @tt{oke} or @tt{resize_failed}.
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_hide(rktwebview_t wv);
|
||
}
|
||
@codeblock{
|
||
result_t rkt_webview_show(rktwebview_t wv);
|
||
}
|
||
@codeblock{
|
||
result_t rkt_webview_show_normal(rktwebview_t wv);
|
||
}
|
||
@codeblock{
|
||
result_t rkt_webview_present(rktwebview_t wv);
|
||
}
|
||
@codeblock{
|
||
result_t rkt_webview_maximize(rktwebview_t wv);
|
||
}
|
||
@codeblock{
|
||
result_t rkt_webview_minimize(rktwebview_t wv);
|
||
}
|
||
All return @tt{oke} or @tt{failed} (when the operation cannot be applied).
|
||
|
||
@codeblock{
|
||
window_state_t rkt_webview_window_state(rktwebview_t wv);
|
||
}
|
||
Returns a simplified window state.
|
||
|
||
|
||
@subsection{Event & Dialog Systems}
|
||
|
||
@codeblock{
|
||
result_t rkt_webview_destroy_event(rkt_event_t* e);
|
||
}
|
||
Frees event memory. Returns @tt{oke}.
|
||
|
||
|
||
@subsection{Native Dialogs}
|
||
|
||
@codeblock{
|
||
rkt_js_result_t* rkt_webview_choose_dir(rktwebview_t wv, const char* title, const char* base_dir);
|
||
}
|
||
Returns JSON:
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{"state":"choosen","dir":"..."}}
|
||
@item{@tt{"state":"canceled","dir":"..."}}
|
||
]
|
||
Must be freed with @tt{rkt_webview_destroy_js_result}.
|
||
|
||
@codeblock{
|
||
rkt_js_result_t* rkt_webview_file_open(rktwebview_t wv, const char* title, const char* base_dir, const char* permitted_exts);
|
||
}
|
||
@codeblock{
|
||
rkt_js_result_t* rkt_webview_file_save(rktwebview_t wv, const char* title, const char* base_dir, const char* permitted_exts);
|
||
}
|
||
Return JSON:
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{"state":"choosen","file":"...","used-filter":"..."}}
|
||
@item{@tt{"state":"canceled","file":"","used-filter":"..."}}
|
||
]
|
||
Must be freed with @tt{rkt_webview_destroy_js_result}.
|
||
|
||
|
||
@subsection{Security}
|
||
|
||
@codeblock{
|
||
void rkt_webview_set_ou_token(rktwebview_t wv, const char* token);
|
||
}
|
||
|
||
This function configures a per-window "OU acceptance token" that affects how
|
||
certificate errors are handled inside the internal @tt{QWebEnginePage}.
|
||
|
||
When a TLS certificate error occurs, the internal page examines the certificate
|
||
chain. If all the following conditions are met:
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{the certificate is self-signed,}
|
||
@item{the certificate contains an Organizational Unit (OU) field,}
|
||
@item{the OU value exactly matches the token previously set with @tt{rkt_webview_set_ou_token},}
|
||
]
|
||
|
||
then the certificate is programmatically accepted and the load is allowed to
|
||
continue.
|
||
|
||
This mechanism is intended for controlled environments (e.g., local development
|
||
servers or private deployments) where a known self-signed certificate is used
|
||
and its OU value is part of the trust boundary.
|
||
|
||
Note: starting with Qt 6.10, @tt{QWebEnginePage} introduces an API for providing
|
||
a specific certificate to be accepted directly by the page. However, this API is
|
||
very new ("bleeding edge") and not yet used or relied upon in this WebView
|
||
bridge.
|
||
|
||
|
||
@section{Event JSON Format}
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{@tt{"event":"page-loaded","oke": <bool>}}
|
||
@item{@tt{"event":"show"}}
|
||
@item{@tt{"event":"hide"}}
|
||
@item{@tt{"event":"move","x": <int>,"y": <int>}}
|
||
@item{@tt{"event":"resize","w": <int>,"h": <int>}}
|
||
@item{@tt{"event":"can-close?"}}
|
||
@item{@tt{"event":"closed"}}
|
||
@item{@tt{"event":"js-evt","js-evt": <object>}}
|
||
]
|
||
|
||
|
||
@section{Typical Usage Pattern}
|
||
|
||
@itemlist[#:style 'compact
|
||
@item{Initialize once.}
|
||
@item{Create windows.}
|
||
@item{Run a cooperative time-sliced pump loop (e.g., ~3 ms Qt, ~10 ms Racket).}
|
||
@item{Invoke JS run/call functions.}
|
||
@item{Handle and free events.}
|
||
@item{Close windows explicitly.}
|
||
]
|
||
|
||
|
||
@section{Summary}
|
||
|
||
This API provides a stable, simple interface for embedding a Qt WebEngine
|
||
webview inside a Racket program via FFI. The API is synchronous, uses compact
|
||
JSON for results, and defines clear memory ownership rules.
|
||
`` |