Tools API

Most of the functions here are not tied to a specific window. Instead, they: read the version, get system paths, read language and display information, store configuration in the data directory, clear data, and so on.

For interfaces deeply integrated with the system (URL protocols, file associations, global hotkeys, clipboard, printing, etc.), see System Integration API.

Version & System Information

Get JadeView version (jadeview_version)

Get the complete version number (including the build number) of the current JadeView dynamic library, for use in the About page, log headers, and reporting the version when troubleshooting.

int32_t jadeview_version(char* buffer, size_t buffer_size);

Get WebView version (get_webview_version)

Writes the local WebView2 runtime version number into buffer (UTF-8 + \0). This is not the version of the JadeView DLL itself (that is jadeview_version).

int32_t get_webview_version(char* buffer, size_t buffer_size);

Returns 1 on success and 0 on failure (insufficient buffer, invalid pointer, etc.).

Get system language (getLocale)

Reads the current Windows user interface language (regional setting) and returns a standard language tag string. Common uses: deciding whether the main process or web page should use a Chinese or English interface, and passing the language parameter to the renderer process for i18n.

int32_t getLocale(char* buffer, size_t buffer_size);

Example values written: zh-CN, en-US. This is not the keyboard layout, but the system display language / region set.

1 on success, 0 on failure (insufficient buffer, invalid pointer, etc.).

Check whether the system is Windows 11 (is_windows_11)

int32_t is_windows_11(void);

Returns 1 if the current system is Windows 11, otherwise 0. Used to determine whether features such as Mica or certain shell capabilities are available.

Paths & Displays

Get system path (getPath)

Use a fixed English keyword to query the absolute path of a category of directory, avoiding the need to assemble environment variables yourself in C or to handle paths with Chinese user names. For example, when you want to place logs, read "My Documents", or find the directory of the exe, you can ask this interface.

int32_t getPath(const char* name, char* buffer, size_t buffer_size);

On success, the path is written to buffer (UTF-8 + \0). Returns 0 on failure.

Get display information (get_displays_info)

Get the layout and resolution information of all displays on the machine at once, making it convenient to: decide on which screen a window appears in a multi-display setup, compute scaled logical coordinates, determine which is the primary screen, and adapt to high DPI.

int32_t get_displays_info(char* buffer, size_t buffer_size);

On success, buffer contains a UTF-8 JSON array, where each element corresponds to one screen. Common field meanings:

Returns 0 on failure (insufficient buffer, parse failure, etc.).

Clear the data directory (clear_data_directory)

Clears the contents of the data directory currently used by JadeView (cache, local configuration, etc.), equivalent to "resetting this application's data on this machine". You must pass the correct confirmation token to prevent accidental triggering.

int32_t clear_data_directory(const char* confirm_token);

confirm_token must be exactly equal to the string I_UNDERSTAND_CLEAR_DATA (consistent with the constant in the source code).

Text Processing

Smart text re-encoding (smart_convert_encoding) v2.2

Automatically detects the encoding of the input text and converts it to the target encoding.

int32_t smart_convert_encoding(
  const uint8_t* input_data,
  int32_t input_len,
  const char* target_encoding,
  char* output_buffer,
  int32_t buffer_size,
  char* detected_encoding,
  int32_t detected_encoding_size
);

Parameters:

• input_data const uint8_t* - Input byte stream
• input_len int32_t - Input byte length
• target_encoding const char* - Target encoding name, case-insensitive, supporting WhatWG standard names and aliases:
  • UTF-8: utf-8, utf8, unicode-1-1-utf-8
  • GBK: gbk, gb2312, gb18030, chinese, csgb2312
  • Shift_JIS: shift_jis, sjis, shift-jis, ms_kanji
  • Big5: big5, big5-hkscs, cn-big5, csbig5
  • EUC-KR: euc-kr, cseuckr, korean
  • windows-1252: windows-1252, ascii, latin1, iso-8859-1
  • For the complete list, see WhatWG Encoding Standard
• output_buffer char* - Output buffer (NUL-terminated)
• buffer_size int32_t - Output buffer size (bytes)
• detected_encoding char* - [output] The detected source encoding name (may be NULL)
• detected_encoding_size int32_t - detected_encoding buffer size

Return value:

Detection logic:

1. BOM takes priority (UTF-8 BOM / UTF-16 LE BOM / UTF-16 BE BOM)
2. When there is no BOM, chardetng smart detection is used
3. When the source encoding and target encoding are the same, it copies directly

Text memory management (jade_text_create / jade_text_free)

char* jade_text_create(const char* text);
void jade_text_free(char* ptr);

• jade_text_create: Copies a piece of UTF-8 text onto the heap and returns a pointer, used by register_ipc_handler and the like to return a dynamic-length response; after the library finishes reading the response it will call jade_text_free. Mixing this with manual malloc+free is error-prone, so please use this API in pairs.
• jade_text_free: Frees a pointer allocated by jade_text_create; do not call it on stack memory or on pointers from other malloc paths.

If invoke only needs default success with no custom JSON, you can return a placeholder such as NULL or (const char*)(uintptr_t)1 (this does not mean "block"; see IPC Communication API).