update: add new api (#75)

jinzhongjia · web-flow · commit 2aaf441f4344 · 2024-12-23T17:15:35.000+08:00
* update: add new api
fix: malloc will check for success

* update dependency
diff --git a/build.zig.zon b/build.zig.zon
@@ -4,8 +4,8 @@
     .minimum_zig_version = "0.12.0",
     .dependencies = .{
         .webui = .{
-            .url = "https://github.com/webui-dev/webui/archive/a44283b04d1ec0dee6544533d5a60a7e560634e9.tar.gz",
-            .hash = "12206fc0555cec7364fba2adb1b9891face05acf14c5d3c54306cf85218b9e0cea4f",
+            .url = "https://github.com/webui-dev/webui/archive/0ff3b1351b9e24be4463b1baf2c26966caeae74a.tar.gz",
+            .hash = "12202382fb8300ffdb1e6f183d212a796b85321e8421162148137d04f2d470e8cf5b",
         },
     },
     .paths = .{
diff --git a/examples/serve_a_folder/main.zig b/examples/serve_a_folder/main.zig
@@ -106,9 +106,9 @@ fn my_files_handler(filename: []const u8) ?[]const u8 {
         // Const static file example
         return test_txt;
     } else if (std.mem.eql(u8, filename, "/dynamic.html")) {
-        const body = webui.malloc(1024);
+        const body = webui.malloc(1024) catch unreachable;
         defer webui.free(body);
-        const header_and_body = webui.malloc(1024);
+        const header_and_body = webui.malloc(1024) catch unreachable;
 
         count += 1;
 
diff --git a/src/c.zig b/src/c.zig
@@ -881,3 +881,97 @@ pub extern fn webui_interface_get_size_at(
     event_number: usize,
     index: usize,
 ) callconv(.C) usize;
+
+/// @brief Show a window using embedded HTML, or a file. If the window is already
+/// open, it will be refreshed. Single client.
+///
+/// @param window The window number
+/// @param event_number The event number
+/// @param content The HTML, URL, Or a local file
+///
+/// @return Returns True if showing the window is successed.
+///
+/// @example webui_show_client(e, "<html>...</html>"); |
+/// webui_show_client(e, "index.html"); | webui_show_client(e, "http://...");
+pub extern fn webui_interface_show_client(
+    window: usize,
+    event_number: usize,
+    content: [*:0]const u8,
+) callconv(.C) bool;
+
+/// @brief Close a specific client.
+///
+/// @param window The window number
+/// @param event_number The event number
+///
+/// @example webui_close_client(e);
+pub extern fn webui_interface_close_client(
+    window: usize,
+    event_number: usize,
+) callconv(.C) void;
+
+/// @brief Safely send raw data to the UI. Single client.
+///
+/// @param window The window number
+/// @param event_number The event number
+/// @param function The JavaScript function to receive raw data: `function
+/// myFunc(myData){}`
+/// @param raw The raw data buffer
+/// @param size The raw data size in bytes
+///
+/// @example webui_send_raw_client(e, "myJavaScriptFunc", myBuffer, 64);
+pub extern fn webui_interface_send_raw_client(
+    window: usize,
+    event_number: usize,
+    function: [*:0]const u8,
+    raw: [*c]const u8,
+    size: usize,
+) callconv(.C) void;
+
+/// @brief Navigate to a specific URL. Single client.
+///
+/// @param window The window number
+/// @param event_number The event number
+/// @param url Full HTTP URL
+///
+/// @example webui_navigate_client(e, "http://domain.com");
+pub extern fn webui_interface_navigate_client(
+    window: usize,
+    event_number: usize,
+    url: [*:0]const u8,
+) callconv(.C) void;
+
+/// @brief Run JavaScript without waiting for the response. Single client.
+///
+/// @param window The window number
+/// @param event_number The event number
+/// @param script The JavaScript to be run
+///
+/// @example webui_run_client(e, "alert('Hello');");
+pub extern fn webui_interface_run_client(
+    window: usize,
+    event_number: usize,
+    script: [*:0]const u8,
+) callconv(.C) void;
+
+/// @brief Run JavaScript and get the response back. Single client.
+/// Make sure your local buffer can hold the response.
+///
+/// @param window The window number
+/// @param event_number The event number
+/// @param script The JavaScript to be run
+/// @param timeout The execution timeout in seconds
+/// @param buffer The local buffer to hold the response
+/// @param buffer_length The local buffer size
+///
+/// @return Returns True if there is no execution error
+///
+/// @example bool err = webui_script_client(e, "return 4 + 6;", 0, myBuffer, myBufferSize);
+pub extern fn webui_interface_script_client(
+    window: usize,
+    event_number: usize,
+    script: [*:0]const u8,
+    timeout: usize,
+    buffer: [*c]u8,
+    buffer_length: usize,
+) callconv(.C) void;
diff --git a/src/webui.zig b/src/webui.zig
@@ -228,8 +228,8 @@ pub fn free(buf: []const u8) void {
 /// Safely allocate memory using the WebUI memory management system
 /// it can be safely freed using `free()` at any time.
 /// In general, you should not use this function
-pub fn malloc(size: usize) []u8 {
-    const ptr = c.webui_malloc(size).?; // TODO: Proper allocation failure check
+pub fn malloc(size: usize) ![]u8 {
+    const ptr = c.webui_malloc(size) orelse return error.AllocateFailed;
     return @as([*]u8, @ptrCast(ptr))[0..size];
 }
 
@@ -536,6 +536,41 @@ pub fn interfaceGetSizeAt(self: webui, event_number: usize, index: usize) usize
     return c.webui_interface_get_size_at(self.window_handle, event_number, index);
 }
 
+// Show a window using embedded HTML, or a file. If the window is already
+pub fn interfaceShowClient(self: webui, event_number: usize, content: [:0]const u8) bool {
+    return c.webui_interface_show_client(self.window_handle, event_number, content.ptr);
+}
+
+// Close a specific client.
+pub fn interfaceCloseClient(self: webui, event_number: usize) void {
+    c.webui_interface_close_client(self.window_handle, event_number);
+}
+
+// Safely send raw data to the UI. Single client.
+pub fn interfaceSendRawClient(
+    self: webui,
+    event_number: usize,
+    function: [:0]const u8,
+    raw: []const u8,
+) void {
+    c.webui_interface_send_raw_client(self.window_handle, event_number, function.ptr, raw.ptr, raw.len);
+}
+
+// Navigate to a specific URL. Single client.
+pub fn interfaceNavigateClient(self: webui, event_number: usize, url: [:0]const u8) void {
+    c.webui_interface_navigate_client(self.window_handle, event_number, url.ptr);
+}
+
+// Run JavaScript without waiting for the response. Single client.
+pub fn interfaceRunClient(self: webui, event_number: usize, script_content: [:0]const u8) void {
+    c.webui_interface_run_client(self.window_handle, event_number, script_content.ptr);
+}
+
+// Run JavaScript and get the response back. Single client.
+pub fn interfaceScriptClient(self: webui, event_number: usize, script_content: [:0]const u8, timeout: usize, buffer: []u8) void {
+    c.webui_interface_script_client(self.window_handle, event_number, script_content.ptr, timeout, buffer.ptr, buffer.len);
+}
+
 /// a very convenient function for binding callback.
 /// you just need to pase a function to get param.
 /// no need to care webui param api.
@@ -752,10 +787,12 @@ pub const Config = enum(c_int) {
     /// root folder gets changed.
     /// Default: False
     folder_monitor,
-    /// Allow multiple clients to connect to the same window,
-    /// This is helpful for web apps (non-desktop software),
-    /// Please see the documentation for more details.
-    /// Default: False
+    /// Allow or prevent WebUI from adding `webui_auth` cookies.
+    /// WebUI uses these cookies to identify clients and block
+    /// unauthorized access to the window content using a URL.
+    /// Please keep this option to `True` if you want only a single
+    /// client to access the window content.
+    /// Default: True
     multi_client,
     /// Allow multiple clients to connect to the same window,
     /// This is helpful for web apps (non-desktop software),
