feat: 重构MaaToolkitDesktopWindow相关API

docs/en_us/2.2-IntegratedInterfaceOverview.md

@@ -1012,34 +1012,55 @@ Get window at specified index in window list
 
 - `window`: Window
 
-Get window handle
+Get window handle (common field)
 
 > [!NOTE]
 >
-> - On Win32, the returned value is a native `HWND`.
-> - On macOS, the returned value represents the window `windowID` (`CGWindowID` / `SCWindow.windowID`). It is force-cast to `void*` at the API layer, so it is not a Cocoa `NSWindow*` pointer.
+> - On Win32, the returned value is a native `HWND` (cast to `uint64`).
+> - On macOS, the returned value is the window `windowID` (`CGWindowID` / `SCWindow.windowID`).
+> - On Linux, the returned value is the Wayland window ID.
 
-### MaaToolkitDesktopWindowGetClassName
+### MaaToolkitDesktopWindowGetWindowName
 
 - `window`: Window
 
-Get window class name
+Get window name (common field)
 
 > [!NOTE]
 >
-> - On Win32, the returned value is the window class name.
-> - On macOS, the returned value is the Bundle ID (`SCWindow.owningApplication.bundleIdentifier`).
+> - On Win32, the returned value is the window name.
+> - On macOS, the returned value is the window title (`SCWindow.title`).
+> - On Linux, the returned value is the Wayland socket name.
 
-### MaaToolkitDesktopWindowGetWindowName
+### MaaToolkitDesktopWindowGetWin32ClassName
 
 - `window`: Window
 
-Get window name
+Get window class name (Win32-specific field)
 
-> [!NOTE]
->
-> - On Win32, the returned value is the window name.
-> - On macOS, the returned value is the window title (`SCWindow.title`).
+### MaaToolkitDesktopWindowGetMacOSPID
+
+- `window`: Window
+
+Get process ID (macOS-specific field)
+
+### MaaToolkitDesktopWindowGetMacOSBundleID
+
+- `window`: Window
+
+Get application bundle ID (macOS-specific field, `SCWindow.owningApplication.bundleIdentifier`)
+
+### MaaToolkitDesktopWindowGetMacOSApplicationName
+
+- `window`: Window
+
+Get application name (macOS-specific field, `SCWindow.owningApplication.applicationName`)
+
+### MaaToolkitDesktopWindowGetLinuxSocketPath
+
+- `window`: Window
+
+Get Wayland socket path (Linux-specific field)
 
 ## MaaAgentClientAPI.h
 

docs/zh_cn/2.2-集成接口一览.md

@@ -1011,34 +1011,55 @@
 
 - `window`: 窗口
 
-获取窗口句柄
+获取窗口句柄（通用字段）
 
 > [!NOTE]
 >
-> - Win32 下，返回值语义为原生 `HWND`。
-> - macOS 下，返回值语义为窗口的 `windowID`（`CGWindowID` / `SCWindow.windowID`），在接口层会强制转换为 `void*` 返回，因此它不是 Cocoa `NSWindow*` 指针。
+> - Win32 下，返回值语义为原生 `HWND`（转换为 `uint64`）。
+> - macOS 下，返回值语义为窗口的 `windowID`（`CGWindowID` / `SCWindow.windowID`）。
+> - Linux 下，返回值语义为 Wayland 窗口 ID。
 
-### MaaToolkitDesktopWindowGetClassName
+### MaaToolkitDesktopWindowGetWindowName
 
 - `window`: 窗口
 
-获取窗口类名
+获取窗口名称（通用字段）
 
 > [!NOTE]
 >
-> - Win32 下，返回值语义为窗口类名。
-> - macOS 下，返回值语义为应用包名（`SCWindow.owningApplication.bundleIdentifier`）。
+> - Win32 下，返回值语义为窗口名称。
+> - macOS 下，返回值语义为窗口标题（`SCWindow.title`）。
+> - Linux 下，返回值语义为 Wayland socket 名称。
 
-### MaaToolkitDesktopWindowGetWindowName
+### MaaToolkitDesktopWindowGetWin32ClassName
 
 - `window`: 窗口
 
-获取窗口名称
+获取窗口类名（Win32 专有字段）
 
-> [!NOTE]
->
-> - Win32 下，返回值语义为窗口名称。
-> - macOS 下，返回值语义为窗口标题（`SCWindow.title`）。
+### MaaToolkitDesktopWindowGetMacOSPID
+
+- `window`: 窗口
+
+获取进程 ID（macOS 专有字段）
+
+### MaaToolkitDesktopWindowGetMacOSBundleID
+
+- `window`: 窗口
+
+获取应用包名（macOS 专有字段，`SCWindow.owningApplication.bundleIdentifier`）
+
+### MaaToolkitDesktopWindowGetMacOSApplicationName
+
+- `window`: 窗口
+
+获取应用程序名称（macOS 专有字段，`SCWindow.owningApplication.applicationName`）
+
+### MaaToolkitDesktopWindowGetLinuxSocketPath
+
+- `window`: 窗口
+
+获取 Wayland socket 路径（Linux 专有字段）
 
 ## MaaAgentClientAPI.h
 

include/MaaToolkit/DesktopWindow/MaaToolkitDesktopWindow.h

@@ -17,17 +17,20 @@ extern "C"
     MAA_TOOLKIT_API MaaSize MaaToolkitDesktopWindowListSize(const MaaToolkitDesktopWindowList* list);
     MAA_TOOLKIT_API const MaaToolkitDesktopWindow* MaaToolkitDesktopWindowListAt(const MaaToolkitDesktopWindowList* list, MaaSize index);
 
-    // Win32: HWND
-    // macOS: CGWindowID (SCWindow.windowID), force-cast to void*, NOT NSWindow*
-    MAA_TOOLKIT_API void* MaaToolkitDesktopWindowGetHandle(const MaaToolkitDesktopWindow* window);
+    // 通用字段
+    MAA_TOOLKIT_API uint64_t MaaToolkitDesktopWindowGetHandle(const MaaToolkitDesktopWindow* window);
+    MAA_TOOLKIT_API const char* MaaToolkitDesktopWindowGetWindowName(const MaaToolkitDesktopWindow* window);
 
-    // Win32: window class name
-    // macOS: bundle identifier (SCWindow.owningApplication.bundleIdentifier)
-    MAA_TOOLKIT_API const char* MaaToolkitDesktopWindowGetClassName(const MaaToolkitDesktopWindow* window);
+    // Win32 专有字段
+    MAA_TOOLKIT_API const char* MaaToolkitDesktopWindowGetWin32ClassName(const MaaToolkitDesktopWindow* window);
 
-    // Win32: window name
-    // macOS: window title (SCWindow.title)
-    MAA_TOOLKIT_API const char* MaaToolkitDesktopWindowGetWindowName(const MaaToolkitDesktopWindow* window);
+    // MacOS 专有字段
+    MAA_TOOLKIT_API int32_t MaaToolkitDesktopWindowGetMacOSPID(const MaaToolkitDesktopWindow* window);                 // macOS 进程ID
+    MAA_TOOLKIT_API const char* MaaToolkitDesktopWindowGetMacOSBundleID(const MaaToolkitDesktopWindow* window);        // macOS Bundle ID
+    MAA_TOOLKIT_API const char* MaaToolkitDesktopWindowGetMacOSApplicationName(const MaaToolkitDesktopWindow* window); // macOS 应用程序名称
+
+    // Linux 专有字段
+    MAA_TOOLKIT_API const char* MaaToolkitDesktopWindowGetLinuxSocketPath(const MaaToolkitDesktopWindow* window);
 
 #ifdef __cplusplus
 }

sample/cpp/main.cpp

@@ -126,11 +126,11 @@ MaaController* create_win32_controller()
 
     for (size_t i = 0; i < size; ++i) {
         auto window_handle = MaaToolkitDesktopWindowListAt(list_handle, i);
-        std::string class_name = MaaToolkitDesktopWindowGetClassName(window_handle);
         std::string window_name = MaaToolkitDesktopWindowGetWindowName(window_handle);
+        std::string class_name = MaaToolkitDesktopWindowGetWin32ClassName(window_handle);
 
         if (window_name.find("二重螺旋") != std::string::npos) {
-            hwnd = MaaToolkitDesktopWindowGetHandle(window_handle);
+            hwnd = reinterpret_cast<void*>(MaaToolkitDesktopWindowGetHandle(window_handle));
             break;
         }
     }
@@ -169,7 +169,7 @@ MaaController* create_macos_controller()
         std::string window_name = MaaToolkitDesktopWindowGetWindowName(window_handle);
 
         if (window_name.find("关于本机") != std::string::npos) {
-            window_id = reinterpret_cast<uintptr_t>(MaaToolkitDesktopWindowGetHandle(window_handle));
+            window_id = MaaToolkitDesktopWindowGetHandle(window_handle);
             break;
         }
     }

source/MaaPiCli/CLI/interactor.cpp

@@ -776,9 +776,9 @@ bool Interactor::select_win32_hwnd(const MAA_PROJECT_INTERFACE_NS::InterfaceData
         Configuration::Win32Config rt_config;
 
         auto window_handle = MaaToolkitDesktopWindowListAt(list_handle, i);
-        rt_config.hwnd = MaaToolkitDesktopWindowGetHandle(window_handle);
-        rt_config.class_name = MAA_NS::to_u16(MaaToolkitDesktopWindowGetClassName(window_handle));
+        rt_config.hwnd = reinterpret_cast<void*>(MaaToolkitDesktopWindowGetHandle(window_handle));
         rt_config.window_name = MAA_NS::to_u16(MaaToolkitDesktopWindowGetWindowName(window_handle));
+        rt_config.class_name = MAA_NS::to_u16(MaaToolkitDesktopWindowGetWin32ClassName(window_handle));
 
         if (boost::regex_search(rt_config.class_name, *class_regex) && boost::regex_search(rt_config.window_name, *window_regex)) {
             matched_config.emplace_back(std::move(rt_config));
@@ -836,9 +836,9 @@ void Interactor::select_gamepad(const MAA_PROJECT_INTERFACE_NS::InterfaceData::C
             Configuration::GamepadConfig rt_config;
 
             auto window_handle = MaaToolkitDesktopWindowListAt(list_handle, i);
-            rt_config.hwnd = MaaToolkitDesktopWindowGetHandle(window_handle);
-            rt_config.class_name = MAA_NS::to_u16(MaaToolkitDesktopWindowGetClassName(window_handle));
+            rt_config.hwnd = reinterpret_cast<void*>(MaaToolkitDesktopWindowGetHandle(window_handle));
             rt_config.window_name = MAA_NS::to_u16(MaaToolkitDesktopWindowGetWindowName(window_handle));
+            rt_config.class_name = MAA_NS::to_u16(MaaToolkitDesktopWindowGetWin32ClassName(window_handle));
 
             if (boost::regex_search(rt_config.class_name, *class_regex) && boost::regex_search(rt_config.window_name, *window_regex)) {
                 matched_config.emplace_back(std::move(rt_config));
@@ -927,9 +927,7 @@ void Interactor::select_macos(const MAA_PROJECT_INTERFACE_NS::InterfaceData::Con
                 std::string window_name = MaaToolkitDesktopWindowGetWindowName(window_handle);
 
                 if (boost::regex_search(MAA_NS::to_u16(window_name), *title_regex)) {
-                    void* hwnd = MaaToolkitDesktopWindowGetHandle(window_handle);
-                    // On macOS, hwnd is (void*)(uintptr_t)windowID, so extract uint32_t
-                    uint32_t window_id = static_cast<uint32_t>(reinterpret_cast<uintptr_t>(hwnd));
+                    uint32_t window_id = MaaToolkitDesktopWindowGetHandle(window_handle);
                     matched_windows.emplace_back(window_id, window_name);
                 }
             }
@@ -1054,7 +1052,7 @@ void Interactor::select_wlroots_auto_detect()
 
         auto id = MaaToolkitDesktopWindowGetHandle(compositor);
         std::string name = MaaToolkitDesktopWindowGetWindowName(compositor);
-        std::string path = MaaToolkitDesktopWindowGetClassName(compositor);
+        std::string path = MaaToolkitDesktopWindowGetLinuxSocketPath(compositor);
 
         std::cout << MAA_NS::utf8_to_crt(std::format("\t{}. {}\n\t\t{}\n\t\t{}\n", i + 1, id, name, path));
     }
@@ -1065,7 +1063,7 @@ void Interactor::select_wlroots_auto_detect()
 
     auto compositor = MaaToolkitDesktopWindowListAt(list_handle, index);
 
-    wlr_config.wlr_socket_path = MaaToolkitDesktopWindowGetClassName(compositor);
+    wlr_config.wlr_socket_path = MaaToolkitDesktopWindowGetLinuxSocketPath(compositor);
 }
 
 void Interactor::select_wlroots_manual_input()

source/MaaToolkit/API/MaaToolkitBufferTypes.hpp

@@ -22,8 +22,15 @@ struct MaaToolkitDesktopWindow
 {
 public:
     virtual ~MaaToolkitDesktopWindow() = default;
-
-    virtual void* handle() const = 0;
-    virtual const std::string& class_name() const = 0;
+    // 通用字段
+    virtual uint64_t handle() const = 0;
     virtual const std::string& window_name() const = 0;
+    // Win32 字段
+    virtual const std::string& win32_class_name() const = 0;
+    // MacOS 字段
+    virtual int32_t macos_pid() const = 0;                         // macOS 进程ID
+    virtual const std::string& macos_bundle_id() const = 0;        // macOS Bundle ID
+    virtual const std::string& macos_application_name() const = 0; // macOS 应用程序名称
+    // Linux 字段
+    virtual const std::string& linux_socket_path() const = 0;
 };

source/MaaToolkit/API/MaaToolkitDesktopWindow.cpp

@@ -73,32 +73,76 @@ const MaaToolkitDesktopWindow* MaaToolkitDesktopWindowListAt(const MaaToolkitDes
     return &list->at(index);
 }
 
-void* MaaToolkitDesktopWindowGetHandle(const MaaToolkitDesktopWindow* window)
+// 通用字段
+uint64_t MaaToolkitDesktopWindowGetHandle(const MaaToolkitDesktopWindow* window)
 {
     if (!window) {
         LogError << "window is null";
-        return nullptr;
+        return 0;
     }
 
     return window->handle();
 }
 
-const char* MaaToolkitDesktopWindowGetClassName(const MaaToolkitDesktopWindow* window)
+const char* MaaToolkitDesktopWindowGetWindowName(const MaaToolkitDesktopWindow* window)
 {
     if (!window) {
         LogError << "window is null";
         return "";
     }
 
-    return window->class_name().c_str();
+    return window->window_name().c_str();
 }
 
-const char* MaaToolkitDesktopWindowGetWindowName(const MaaToolkitDesktopWindow* window)
+// Win32 专有字段
+const char* MaaToolkitDesktopWindowGetWin32ClassName(const MaaToolkitDesktopWindow* window)
 {
     if (!window) {
         LogError << "window is null";
         return "";
     }
 
-    return window->window_name().c_str();
+    return window->win32_class_name().c_str();
+}
+
+// MacOS 专有字段
+int32_t MaaToolkitDesktopWindowGetMacOSPID(const MaaToolkitDesktopWindow* window)
+{
+    if (!window) {
+        LogError << "window is null";
+        return 0;
+    }
+
+    return window->macos_pid();
+}
+
+const char* MaaToolkitDesktopWindowGetMacOSBundleID(const MaaToolkitDesktopWindow* window)
+{
+    if (!window) {
+        LogError << "window is null";
+        return "";
+    }
+
+    return window->macos_bundle_id().c_str();
+}
+
+const char* MaaToolkitDesktopWindowGetMacOSApplicationName(const MaaToolkitDesktopWindow* window)
+{
+    if (!window) {
+        LogError << "window is null";
+        return "";
+    }
+
+    return window->macos_application_name().c_str();
+}
+
+// Linux 专有字段
+const char* MaaToolkitDesktopWindowGetLinuxSocketPath(const MaaToolkitDesktopWindow* window)
+{
+    if (!window) {
+        LogError << "window is null";
+        return "";
+    }
+
+    return window->linux_socket_path().c_str();
 }