feat: add cross-platform UrlOpener API and C bindings

Author: lijy91

CMakeLists.txt

@@ -2,6 +2,8 @@ cmake_minimum_required(VERSION 3.10)
 
 project(nativeapi_library VERSION 0.0.1 LANGUAGES CXX C)
 
+include(CTest)
+
 # Add library subdirectory
 add_subdirectory(src)
 
@@ -24,3 +26,7 @@ add_subdirectory(examples/tray_icon_example)
 add_subdirectory(examples/tray_icon_c_example)
 add_subdirectory(examples/window_c_example)
 add_subdirectory(examples/window_example)
+
+if(BUILD_TESTING)
+  add_subdirectory(tests)
+endif()

include/nativeapi.h

@@ -29,6 +29,7 @@
 #include "../src/tray_icon.h"
 #include "../src/tray_icon_event.h"
 #include "../src/tray_manager.h"
+#include "../src/url_opener.h"
 #include "../src/window.h"
 #include "../src/window_event.h"
 #include "../src/window_manager.h"
@@ -52,5 +53,6 @@
 #include "../src/capi/string_utils_c.h"
 #include "../src/capi/tray_icon_c.h"
 #include "../src/capi/tray_manager_c.h"
+#include "../src/capi/url_opener_c.h"
 #include "../src/capi/window_c.h"
 #include "../src/capi/window_manager_c.h"

src/capi/url_opener_c.cpp

@@ -0,0 +1,80 @@
+#include "url_opener_c.h"
+
+#include <exception>
+#include <string>
+
+#include "../url_opener.h"
+#include "string_utils_c.h"
+
+using namespace nativeapi;
+
+namespace {
+
+native_url_open_error_code_t ToCErrorCode(UrlOpenErrorCode code) {
+  switch (code) {
+    case UrlOpenErrorCode::kNone:
+      return NATIVE_URL_OPEN_ERROR_NONE;
+    case UrlOpenErrorCode::kInvalidUrlEmpty:
+      return NATIVE_URL_OPEN_ERROR_INVALID_URL_EMPTY;
+    case UrlOpenErrorCode::kInvalidUrlMissingScheme:
+      return NATIVE_URL_OPEN_ERROR_INVALID_URL_MISSING_SCHEME;
+    case UrlOpenErrorCode::kInvalidUrlUnsupportedScheme:
+      return NATIVE_URL_OPEN_ERROR_INVALID_URL_UNSUPPORTED_SCHEME;
+    case UrlOpenErrorCode::kUnsupportedPlatform:
+      return NATIVE_URL_OPEN_ERROR_UNSUPPORTED_PLATFORM;
+    case UrlOpenErrorCode::kInvocationFailed:
+      return NATIVE_URL_OPEN_ERROR_INVOCATION_FAILED;
+    default:
+      return NATIVE_URL_OPEN_ERROR_INVOCATION_FAILED;
+  }
+}
+
+native_url_open_result_t MakeResult(bool success,
+                                    native_url_open_error_code_t error_code,
+                                    const std::string& message) {
+  native_url_open_result_t result = {};
+  result.success = success;
+  result.error_code = error_code;
+  result.error_message = message.empty() ? nullptr : to_c_str(message);
+  return result;
+}
+
+}  // namespace
+
+bool native_url_opener_is_supported(void) {
+  try {
+    return UrlOpener::IsSupported();
+  } catch (...) {
+    return false;
+  }
+}
+
+native_url_open_result_t native_url_opener_open(const char* url) {
+  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));
+    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());
+  } catch (...) {
+    return MakeResult(false, NATIVE_URL_OPEN_ERROR_INVOCATION_FAILED,
+                      "Unexpected error while opening URL.");
+  }
+}
+
+void native_url_open_result_free(native_url_open_result_t* result) {
+  if (!result) {
+    return;
+  }
+
+  if (result->error_message) {
+    free_c_str(result->error_message);
+    result->error_message = nullptr;
+  }
+  result->success = false;
+  result->error_code = NATIVE_URL_OPEN_ERROR_NONE;
+}

src/capi/url_opener_c.h

@@ -0,0 +1,49 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdbool.h>
+
+/**
+ * @brief Error codes returned by URL opening APIs.
+ */
+typedef enum {
+  NATIVE_URL_OPEN_ERROR_NONE = 0,
+  NATIVE_URL_OPEN_ERROR_INVALID_URL_EMPTY = 1,
+  NATIVE_URL_OPEN_ERROR_INVALID_URL_MISSING_SCHEME = 2,
+  NATIVE_URL_OPEN_ERROR_INVALID_URL_UNSUPPORTED_SCHEME = 3,
+  NATIVE_URL_OPEN_ERROR_UNSUPPORTED_PLATFORM = 4,
+  NATIVE_URL_OPEN_ERROR_INVOCATION_FAILED = 5,
+} native_url_open_error_code_t;
+
+/**
+ * @brief Result payload for URL open attempts.
+ */
+typedef struct {
+  bool success;
+  native_url_open_error_code_t error_code;
+  char* error_message;
+} native_url_open_result_t;
+
+/**
+ * @brief Check whether URL opening is supported on this platform.
+ */
+bool native_url_opener_is_supported(void);
+
+/**
+ * @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);
+
+/**
+ * @brief Free owned memory inside a native_url_open_result_t.
+ */
+void native_url_open_result_free(native_url_open_result_t* result);
+
+#ifdef __cplusplus
+}
+#endif

src/platform/android/url_opener_android.cpp

@@ -0,0 +1,26 @@
+#include "../../url_opener.h"
+#include "../../url_opener_internal.h"
+
+namespace nativeapi {
+namespace {
+
+UrlLaunchOutcome LaunchUnsupported(const std::string& url) {
+  (void)url;
+  return {false, "URL opening is not implemented on Android in this native layer."};
+}
+
+}  // namespace
+
+bool UrlOpener::IsSupported() {
+  return false;
+}
+
+UrlOpenResult UrlOpener::Open(const std::string& url) const {
+  UrlOpenResult result = OpenUrlWithLauncher(url, LaunchUnsupported);
+  if (!result.success && result.error_code == UrlOpenErrorCode::kInvocationFailed) {
+    result.error_code = UrlOpenErrorCode::kUnsupportedPlatform;
+  }
+  return result;
+}
+
+}  // namespace nativeapi

src/platform/ios/url_opener_ios.mm

@@ -0,0 +1,87 @@
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+#include <dispatch/dispatch.h>
+
+#include "../../url_opener.h"
+#include "../../url_opener_internal.h"
+
+namespace nativeapi {
+namespace {
+
+UrlLaunchOutcome LaunchUrlOnMainThread(const std::string& url) {
+  @autoreleasepool {
+    UIApplication* app = [UIApplication sharedApplication];
+    if (!app) {
+      return {false, "UIApplication is unavailable."};
+    }
+
+    NSString* ns_url = [NSString stringWithUTF8String:url.c_str()];
+    if (!ns_url) {
+      return {false, "Failed to build NSURL from UTF-8 input."};
+    }
+
+    NSURL* target = [NSURL URLWithString:ns_url];
+    if (!target) {
+      return {false, "Failed to parse URL."};
+    }
+
+    if (![app canOpenURL:target]) {
+      return {false, "No handler available for URL."};
+    }
+
+    if (@available(iOS 10.0, *)) {
+      __block BOOL open_result = NO;
+      dispatch_semaphore_t semaphore = dispatch_semaphore_create(0);
+      [app openURL:target
+          options:@{}
+completionHandler:^(BOOL success) {
+  open_result = success;
+  dispatch_semaphore_signal(semaphore);
+}];
+
+      const long wait_result =
+          dispatch_semaphore_wait(semaphore, dispatch_time(DISPATCH_TIME_NOW, 3 * NSEC_PER_SEC));
+      if (wait_result != 0) {
+        return {false, "Timed out waiting for openURL completion."};
+      }
+      if (!open_result) {
+        return {false, "UIApplication failed to open URL."};
+      }
+      return {true, ""};
+    }
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+    const BOOL opened = [app openURL:target];
+#pragma clang diagnostic pop
+    if (!opened) {
+      return {false, "UIApplication failed to open URL."};
+    }
+    return {true, ""};
+  }
+}
+
+UrlLaunchOutcome LaunchUrl(const std::string& url) {
+  if ([NSThread isMainThread]) {
+    return LaunchUrlOnMainThread(url);
+  }
+
+  __block UrlLaunchOutcome outcome;
+  dispatch_sync(dispatch_get_main_queue(), ^{
+    outcome = LaunchUrlOnMainThread(url);
+  });
+  return outcome;
+}
+
+}  // namespace
+
+bool UrlOpener::IsSupported() {
+  return true;
+}
+
+UrlOpenResult UrlOpener::Open(const std::string& url) const {
+  return OpenUrlWithLauncher(url, LaunchUrl);
+}
+
+}  // namespace nativeapi

src/platform/linux/url_opener_linux.cpp

@@ -0,0 +1,35 @@
+#include <gio/gio.h>
+
+#include "../../url_opener.h"
+#include "../../url_opener_internal.h"
+
+namespace nativeapi {
+namespace {
+
+UrlLaunchOutcome LaunchUrl(const std::string& url) {
+  GError* error = nullptr;
+  const gboolean ok = g_app_info_launch_default_for_uri(url.c_str(), nullptr, &error);
+  if (!ok) {
+    std::string message = "Failed to launch URL via desktop defaults.";
+    if (error && error->message) {
+      message = error->message;
+    }
+    if (error) {
+      g_error_free(error);
+    }
+    return {false, message};
+  }
+  return {true, ""};
+}
+
+}  // namespace
+
+bool UrlOpener::IsSupported() {
+  return true;
+}
+
+UrlOpenResult UrlOpener::Open(const std::string& url) const {
+  return OpenUrlWithLauncher(url, LaunchUrl);
+}
+
+}  // namespace nativeapi

src/platform/macos/url_opener_macos.mm

@@ -0,0 +1,40 @@
+#import <Cocoa/Cocoa.h>
+#import <Foundation/Foundation.h>
+
+#include "../../url_opener.h"
+#include "../../url_opener_internal.h"
+
+namespace nativeapi {
+namespace {
+
+UrlLaunchOutcome LaunchUrl(const std::string& url) {
+  @autoreleasepool {
+    NSString* ns_url = [NSString stringWithUTF8String:url.c_str()];
+    if (!ns_url) {
+      return {false, "Failed to build NSURL from UTF-8 input."};
+    }
+
+    NSURL* target = [NSURL URLWithString:ns_url];
+    if (!target) {
+      return {false, "Failed to parse URL."};
+    }
+
+    const BOOL opened = [[NSWorkspace sharedWorkspace] openURL:target];
+    if (!opened) {
+      return {false, "NSWorkspace could not open the URL."};
+    }
+    return {true, ""};
+  }
+}
+
+}  // namespace
+
+bool UrlOpener::IsSupported() {
+  return true;
+}
+
+UrlOpenResult UrlOpener::Open(const std::string& url) const {
+  return OpenUrlWithLauncher(url, LaunchUrl);
+}
+
+}  // namespace nativeapi

src/platform/ohos/url_opener_ohos.cpp

@@ -0,0 +1,26 @@
+#include "../../url_opener.h"
+#include "../../url_opener_internal.h"
+
+namespace nativeapi {
+namespace {
+
+UrlLaunchOutcome LaunchUnsupported(const std::string& url) {
+  (void)url;
+  return {false, "URL opening is not implemented on OHOS in this native layer."};
+}
+
+}  // namespace
+
+bool UrlOpener::IsSupported() {
+  return false;
+}
+
+UrlOpenResult UrlOpener::Open(const std::string& url) const {
+  UrlOpenResult result = OpenUrlWithLauncher(url, LaunchUnsupported);
+  if (!result.success && result.error_code == UrlOpenErrorCode::kInvocationFailed) {
+    result.error_code = UrlOpenErrorCode::kUnsupportedPlatform;
+  }
+  return result;
+}
+
+}  // namespace nativeapi