System Integration API

Global capabilities for interacting with the operating system, not bound to any specific window. Includes protocol registration, global hotkeys, clipboard, cursor position, printing, and more.

If you only care about basic tool capabilities (version, paths, language, monitors, config read/write), see the Tools API.

Protocol & File Association

Custom URL Scheme (register_url_scheme / unregister_url_scheme)

Purpose: Register a custom URL scheme with the system (e.g. myapp://open/...), so that when the user clicks such a link in a browser or another application, it launches your exe and passes the URL through. When uninstalling or disabling the feature, call unregister to remove the registration.

int32_t register_url_scheme(const char* scheme);
int32_t unregister_url_scheme(const char* scheme);

JadeView_init must have succeeded so that the library knows your exe path. If single instance is enabled, the second launch may hand the command line to the first opened process via second-instance, making it convenient to handle the protocol URL only once.

File Type Association (register_file_association / unregister_file_association)

Purpose: Let the user double-click a certain extension (such as .mydata) to open it with the current application. friendly_name is the human-readable name shown in the "Open with" menu.

int32_t register_file_association(const char* extension, const char* friendly_name);
int32_t unregister_file_association(const char* extension);

The extension can be given with or without the leading dot; it is normalized internally. Likewise, initialization must already be complete so it associates with the correct exe.

Global Input

Global Hotkey (register_global_hotkey / unregister_global_hotkey)

Purpose: Register a global shortcut (which responds even when your window does not have focus), for example to summon the main window globally or to mute. When pressed, the library fires the global-hotkey event (the payload is JSON containing the hotkey id and key value), which you can handle in jade_on.

uint32_t register_global_hotkey(uint32_t modifiers, uint32_t vk);
int32_t unregister_global_hotkey(uint32_t hotkey_id);

For event field descriptions, see Event Types.

Cursor Position

Get Cursor Position (get_cursor_position) v2.2

Get the current cursor screen coordinates (global, not bound to a window).

int32_t get_cursor_position(char* buffer, int buffer_size);

• Parameters: buffer char* - output buffer; buffer_size int - buffer size
• Return value: 1 = success, the buffer is written with the JSON {"x":0,"y":0}; 0 = failure

Clipboard v2.2

Depends on the newly added arboard crate.

Read Clipboard Text (clipboard_read_text) v2.2

int32_t clipboard_read_text(char* buffer, int buffer_size);

• Parameters: buffer char* - output buffer; buffer_size int - buffer size
• Return value: 1 = success, 0 = failure

Write Clipboard Text (clipboard_write_text) v2.2

int32_t clipboard_write_text(const char* text);

• Parameters: text string - the text to write
• Return value: 1 = success, 0 = failure

Printing v2.2

Get Printer List (jade_get_printer_list) v2.2

Get the system printer list, returned as a JSON array string.

int32_t jade_get_printer_list(char* buffer, int buffer_size);

• Parameters: buffer char* - output buffer; buffer_size int - buffer size (bytes)
• Return value: >0 = number of printers, the buffer contains a JSON array; 0 = failure or no printers
• When the buffer is too small: it truncates the written output and still returns the printer count (no error); the JSON may be cut off, so reserve enough space or retry based on the returned count

Output example:

["Microsoft Print to PDF","HP LaserJet Pro MFP M428fdw","Fax"]

Print a File (jade_print_dialog)

Print a file on disk directly using the system-associated program (without going through the WebView); suitable for printing existing files such as PDFs and images.

int32_t jade_print_dialog(const char* file_path);

• Parameter: file_path string - the absolute path of the file to print; NULL or an empty string returns 0 immediately
• Return value: 1 = successfully submitted to the system for printing; 0 = failure (empty path / system call failed)

Login Autostart v2.3.0-beta.6

Set / query whether the app starts automatically on system login, cross-platform (Windows / Linux). The autostart identifier name is taken from the app_name passed to JadeView_init (falling back to the executable file name if absent); the autostart command is the current executable path (current_exe) plus the args you pass in.

Enable / Disable Login Autostart (set_login_autostart)

// enable: 1=enable, 0=disable; args: launch arguments appended after the exe path (NULL / empty = none)
int32_t set_login_autostart(int32_t enable, const char* args);

• Parameters:
  • enable int32_t - 1 = enable autostart, 0 = disable
  • args string - Launch arguments appended after the executable path on autostart (e.g. "--minimized"); pass NULL or an empty string for no arguments
• Return value: 1 = success, 0 = failure (no permission / IO error). When disabling, if the autostart entry does not exist in the first place, it is also treated as success

Query Whether Login Autostart Is Set (get_login_autostart)

int32_t get_login_autostart(void);

• Return value: 1 = autostart is set, 0 = not set

File Icon

Extract a File / Program Icon (get_file_icon) v2.3.0-beta.6

Gets the system-associated icon for any path (.exe / .lnk / a regular file / a folder), scales it to a PNG of the requested size, registers it as a jade:// secure resource, and writes the accessible URL into your buffer — the frontend can use that URL directly as <img src>. Commonly used for file managers, launchers, recent-file lists, and other UIs that need to show system icons.

// size: target edge length (16/32/48/64/128/256, <=0 uses 48)
// window_id: window the resource belongs to (0 = global)
// ttl_seconds: resource expiry in seconds (0 = default, 0xFFFFFFFF = never expires)
// url_buffer / buffer_size: output URL buffer (same format as register_resource)
int32_t get_file_icon(const char* path, int32_t size, uint32_t window_id,
                      uint32_t ttl_seconds, char* url_buffer, size_t buffer_size);

• Return value: 1 = success, url_buffer is written with a URL like /---jade---resource--?token=...; 0 = failure
• Internal flow: extract icon → Lanczos3 scaling → write PNG to %TEMP%/JadeView_icon_cache/ (deduplicated by path + size) → register as a jade:// resource → write out the URL

Network Time (NTP)

Get Network Timestamp (jade_ntp_now) v2.3

Get the current UTC timestamp from a network time server via the NTP protocol (UDP/123). It does not depend on the local system clock and can be used for anti-cheat, license validation, log time alignment, and similar scenarios.

It does not require JadeView_init and can be called independently. The local machine needs outbound UDP network access.

int64_t jade_ntp_now(const char* ntp_server);

Get the current network timestamp (UTC milliseconds; for Beijing time add 8 hours).

Behavior

• Passing a non-empty address: Only that server is queried, with a 3-second timeout per query; on failure it returns -1 directly and does not fall back to the built-in list.
• Passing NULL / empty string / whitespace: Queries the built-in list concurrently in order, using the first to arrive, and returns the first successful result; returns -1 if all fail.

Built-in Server List

In priority order (anycast / low latency first, overseas nodes as fallback):

Python Example

import ctypes, datetime
from ctypes import c_char_p, c_int64

dll = ctypes.WinDLL("JadeView.dll")
dll.jade_ntp_now.argtypes = [c_char_p]
dll.jade_ntp_now.restype = c_int64

# 1) Use the built-in list (pass NULL)
ms = dll.jade_ntp_now(None)
if ms >= 0:
    print("UTC:", datetime.datetime.utcfromtimestamp(ms / 1000.0))

# 2) Specify a custom server
ms = dll.jade_ntp_now(b"ntp.aliyun.com")

# 3) An empty string is equivalent to the built-in list
ms = dll.jade_ntp_now(b"")

# Returns -1 on failure
if ms < 0:
    print("NTP fetch failed")