Add C URL opener example and instance-based C API

Add a new examples/url_opener_c_example (CMakeLists + main.c) and include it in the top-level CMakeLists. Change the C API to use an opaque native_url_opener_t instance: add native_url_opener_create() and native_url_opener_destroy(), update native_url_opener_is_supported() and native_url_opener_open() to accept the instance, and add FFI_PLUGIN_EXPORT for symbol visibility. Implement GetUrlOpener helper, improve null checks and error handling in src/capi/url_opener_c.cpp, and keep the existing result cleanup API.

Author: lijy91

CMakeLists.txt

@@ -26,6 +26,7 @@ add_subdirectory(examples/storage_example)
 add_subdirectory(examples/storage_c_example)
 add_subdirectory(examples/tray_icon_example)
 add_subdirectory(examples/tray_icon_c_example)
+add_subdirectory(examples/url_opener_c_example)
 add_subdirectory(examples/window_c_example)
 add_subdirectory(examples/window_example)
 

examples/url_opener_c_example/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.10)
+
+project(url_opener_c_example)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+
+add_executable(url_opener_c_example main.c)
+
+target_link_libraries(url_opener_c_example nativeapi)
+
+target_include_directories(url_opener_c_example PRIVATE ../../include)

examples/url_opener_c_example/main.c

@@ -0,0 +1,35 @@
+#include <nativeapi.h>
+#include <stdio.h>
+
+int main(void) {
+  printf("URL Opener C API Example\n");
+  printf("========================\n\n");
+
+  native_url_opener_t opener = native_url_opener_create();
+  if (!opener) {
+    fprintf(stderr, "Failed to create URL opener instance.\n");
+    return 1;
+  }
+
+  if (!native_url_opener_is_supported(opener)) {
+    printf("URL opening is not supported on this platform.\n");
+    native_url_opener_destroy(opener);
+    return 0;
+  }
+
+  printf("URL opening is supported.\n");
+  printf("Opening https://example.com ...\n");
+
+  native_url_open_result_t result = native_url_opener_open(opener, "https://example.com");
+  if (result.success) {
+    printf("URL opened successfully.\n");
+  } else {
+    fprintf(stderr, "Failed to open URL.\n");
+    fprintf(stderr, "Error code: %d\n", (int)result.error_code);
+    fprintf(stderr, "Message: %s\n", result.error_message ? result.error_message : "(none)");
+  }
+
+  native_url_open_result_free(&result);
+  native_url_opener_destroy(opener);
+  return result.success ? 0 : 1;
+}

src/capi/url_opener_c.cpp

@@ -10,6 +10,10 @@ using namespace nativeapi;
 
 namespace {
 
+UrlOpener* GetUrlOpener(native_url_opener_t opener) {
+  return static_cast<UrlOpener*>(opener);
+}
+
 native_url_open_error_code_t ToCErrorCode(UrlOpenErrorCode code) {
   switch (code) {
     case UrlOpenErrorCode::kNone:
@@ -41,22 +45,41 @@ native_url_open_result_t MakeResult(bool success,
 
 }  // namespace
 
-bool native_url_opener_is_supported(void) {
+native_url_opener_t native_url_opener_create(void) {
+  try {
+    return static_cast<native_url_opener_t>(new UrlOpener());
+  } catch (...) {
+    return nullptr;
+  }
+}
+
+void native_url_opener_destroy(native_url_opener_t opener) {
+  delete GetUrlOpener(opener);
+}
+
+bool native_url_opener_is_supported(native_url_opener_t opener) {
+  if (!opener) {
+    return false;
+  }
+
   try {
     return UrlOpener::IsSupported();
   } catch (...) {
     return false;
   }
 }
 
-native_url_open_result_t native_url_opener_open(const char* url) {
+native_url_open_result_t native_url_opener_open(native_url_opener_t opener, const char* url) {
+  if (!opener) {
+    return MakeResult(false, NATIVE_URL_OPEN_ERROR_INVOCATION_FAILED, "URL opener is null.");
+  }
+
   if (!url) {
     return MakeResult(false, NATIVE_URL_OPEN_ERROR_INVALID_URL_EMPTY, "URL is empty.");
   }
 
   try {
-    UrlOpener opener;
-    const UrlOpenResult result = opener.Open(std::string(url));
+    const UrlOpenResult result = GetUrlOpener(opener)->Open(std::string(url));
     return MakeResult(result.success, ToCErrorCode(result.error_code), result.error_message);
   } catch (const std::exception& e) {
     return MakeResult(false, NATIVE_URL_OPEN_ERROR_INVOCATION_FAILED, e.what());

src/capi/url_opener_c.h

@@ -1,10 +1,21 @@
 #pragma once
 
+#include <stdbool.h>
+
+#if _WIN32
+#define FFI_PLUGIN_EXPORT __declspec(dllexport)
+#else
+#define FFI_PLUGIN_EXPORT
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-#include <stdbool.h>
+/**
+ * @brief Opaque handle for a URL opener instance.
+ */
+typedef void* native_url_opener_t;
 
 /**
  * @brief Error codes returned by URL opening APIs.
@@ -27,21 +38,36 @@ typedef struct {
   char* error_message;
 } native_url_open_result_t;
 
+/**
+ * @brief Create a URL opener instance.
+ */
+FFI_PLUGIN_EXPORT
+native_url_opener_t native_url_opener_create(void);
+
+/**
+ * @brief Destroy a URL opener instance.
+ */
+FFI_PLUGIN_EXPORT
+void native_url_opener_destroy(native_url_opener_t opener);
+
 /**
  * @brief Check whether URL opening is supported on this platform.
  */
-bool native_url_opener_is_supported(void);
+FFI_PLUGIN_EXPORT
+bool native_url_opener_is_supported(native_url_opener_t opener);
 
 /**
  * @brief Attempt to open URL with the system default browser.
  *
  * Caller must release result.error_message via native_url_open_result_free().
  */
-native_url_open_result_t native_url_opener_open(const char* url);
+FFI_PLUGIN_EXPORT
+native_url_open_result_t native_url_opener_open(native_url_opener_t opener, const char* url);
 
 /**
  * @brief Free owned memory inside a native_url_open_result_t.
  */
+FFI_PLUGIN_EXPORT
 void native_url_open_result_free(native_url_open_result_t* result);
 
 #ifdef __cplusplus