[RFC] MAA Object Model

[dantmnf]

目标

通过IDL定义接口，然后使用代码生成器生成胶水代码，实现MaaCore和其他语言的（进程内）面向对象的双向互操作。后续暴露 RMI 接口供 Node/Python 等不便通过 FFI 实现进程内接口的语言/框架使用。

参考

• The Windows Runtime (WinRT) type system
• GObject Type System Concepts

类型系统

基本类型

• 定长整数
  • 无符号？（@java）
• 浮点数
• 字符串
• 布尔值

组合类型

• 枚举
• 结构体
• 数组
• 映射？

接口与实例

• 接口：预先定义的一组方法、属性及事件(?)
• 实例：指接口的实现以及其内部状态
  • 一个实例可以实现多个接口。
  • 传递实例时，必须选择一个接口进行传递。

泛型接口（？）

允许为不同类型定义相似的接口，避免在 IDL 中复读接口定义。参考 https://learn.microsoft.com/en-us/uwp/winrt-cref/winrt-type-system#parameterized-interfaces

委托（回调）

委托（回调）是由希望接收通知一方实现的指定接口，成员仅包含一个方法。

（或者仿照 Java 模式，直接使用接口？）

事件

基于委托的更高一层抽象，定义方式待定：

• 为每个事件定义独立的注册/取消注册方法对（类似 Windows Runtime）
• 定义事件ID，通过统一的函数/方法管理回调注册（类似 GObject/Qt，存在静态类型安全问题）

  • 可以实现为实例上的接口，如

    interface IEventSource {
        Token Connect(EVENT_ID_TYPE eventId, IEventHandler handler);
        void Disconnect(Token token);
    }

  • 或者使用类 GObject 模式，通过全局函数注册

接口定义语言（IDL）

选择易于通过程序结构化获取各个成员定义的语言作为 IDL，如 C# 或 Java：

enum PixelFormat {
    ...
}

interface IBuffer {
    int Length { get; }
    // IBuffer 在 ABI 层面提供指针访问，IDL 中不可定义指针类型
}

struct ScreenshotImage {
    IBuffer data;  // IBuffer 在 ABI 层面提供指针访问
    int width;
    int height;
    int stride;
    PixelFormat format;
}

enum EventAction {
    Move,
    Down,
    Up,
}

delegate void ControllerDisconnectedHandler(IController controller, EventArgs args);

interface IController {
    string TargetIdentifier { get; }
    ScreenshotImage GetScreenshot();
    void PointerDownUp(int x, int y);
    void PointerEvent(EventAction action, int pointerId, int x, int y);
    event ControllerDisconnectedHandler Disconnected;
}

进程内 ABI

参考 https://learn.microsoft.com/en-us/uwp/winrt-cref/winrt-type-system#interface-members

关键点：

• 基于 COM ABI，即

  接口指针	->	虚函数表指针	->	QueryInterface
  		私有数据		AddRef
  				Release
  				GetIids
  				方法1实现函数
  				方法2实现函数

  • 所有接口在 ABI 上都实现几个基础方法（参考 IUnknown、IInspectable）用于提供 RTTI（反射）信息以及引用计数操作。
  • 内存对齐及调用约定与该平台 C 编译器默认行为一致。在 64 位 Windows 平台上，同时与 Microsoft COM ABI 一致。
  • 其他选项：类 GObject ABI，参考 https://docs.gtk.org/gobject/concepts.html#non-instantiatable-classed-types-interfaces 以及 GLib 代码

• 全局函数：

  • MaaRtAlloc/MaaRtFree：统一的内存分配/释放入口
  • MString：ABI 字符串（类似JNI及HSTRING）
    • 字符串统一使用 UTF-8 编码，保证数据区末尾有 \0，允许中间存在 \0
    • 使用 MaaRtCreateString 函数创建字符串对象（复制数据），返回 MString 不透明指针
    • 字符串对象不可变，使用 MaaRtDuplicateString 函数增加引用计数
    • 使用 MaaRtDeleteString 函数减少引用计数
    • 使用 MaaRtGetStringData 获得长度以及数据
    • 待定：在栈上分配对应结构体，试图增加引用计数时再进行复制
    • 待定：MaaRtSubString 提取子字符串（根据大小决定增加引用计数或进行复制）
  • 错误处理相关
    • MaaRtSetLastError/MaaRtGetLastError：
      考虑到没有人想给每个可能的错误编码错误代码，通过这组函数设置和获取错误信息（字符串）
  • 基础对象工厂，提供面向对象 API 的入口

• 函数参数约定

  • 第一个参数为接口指针
  • C ABI 的返回值为错误代码（参考 HRESULT）
  • 如果方法定义的返回类型不是 void，最后一个参数为返回值出参
  • 字符串通过 MString 不透明指针传递
  • 数组类型需在 ABI 层面传递两个参数：
    • 入参及双向（填充）数组传递 T *first, uint64 length
    • 出参（返回）数组传递 T **first, uint64 *length，由被调用方申请内存，调用方使用 MaaRtFree 释放。

[neko-para]

做了一小部分
MaaObjectModel