Skip to content

Latest commit

 

History

History
31 lines (24 loc) · 3.36 KB

4.2-标准化接口设计.md

File metadata and controls

31 lines (24 loc) · 3.36 KB

标准化的高级语言面向对象接口设计

binding 可以分为两步:

  1. 对 C API 进行标准化的 OOP 封装。由于 MaaFW 接口相对较为稳定,在完成后不需要长期进行维护。
  2. 在 1 的基础上,解析回调 message, detail json, pipeline_override 等参数,封装成不同的函数及结构。这些字段可能会随着 MaaFW 更新不断变化,需要长期跟进 MaaFW 新版本修改。

若您希望为 MaaFW 添加某个语言的封装,可根据自身时间精力等安排,任选一种方式进行。

标准化接口

  1. MaaTasker, MaaResource, MaaController 需包装成对象,而非过程化的接口。例如 MaaContextGetTasker 这类的接口,也需要返回对象,而非 handle。可以考虑两种模型:
    1. 增加一个全局 handle - 对象引用 字典,通过 handle 去找原对象再返回。
    2. 对象无状态,仅负责引用 handle ,直接创建新对象返回。(可参考 python binding 中 own 字段)
  2. MaaTaskId, MaaCtrlId, MaaResId 等异步动作 id ,不对集成方返回。由 binding 封装成 Job 类,提供 wait, status, get 等方法。
  3. Job 类需提供可以由本 id 进行操作的所有方法的封装,例如 TaskJob 的 get 方法需返回 MaaTaskerGetTaskDetail 查询到的数据的封装。
  4. MaaRecoId, MaaNodeId 等查询类 id ,不对集成方返回。由 binding 调用 MaaTaskerGetRecoDetail 等接口查询,并包装成 RecoDetail, NodeDetail 等结构体再返回。
  5. CustomAction, CustomRecognition, NotificationCallback 等,需要包装一份 agent ,最好是虚基类。实际传给 maafw 的是 agent 对象中的指针,由 agent 将各个参数转换为本语言常用类型后,再交给集成方。
  6. CustomAction, CustomRecognition 的 agent 中请将 MaaCustomRecognitionCallback/MaaCustomActionCallback 的除 context 外的参数封装成结构体再交给集成方,避免后续 Callback 新增参数造成的集成方代码不兼容。返回值也请封装成结构。
  7. SetOption 中每个枚举拆分成独立的接口,例如 set_screenshot_target_long_side 等,而不将具体枚举提供给集成方。
  8. StringBuffer, ImageBuffer 等缓冲区,不对集成方返回。需要转换成本语言惯用的 string, image 类型再给出。
  9. BindResource, BindController, RegisterCustom 等接口需注意留一份引用,避免 gc 。
  10. MaaToolkit 中 Find 系列接口,直接返回封装过的结构体数组。
  11. 要求提供 sample ,其中展示的接口调用不应少于 python sample 。

额外的解析封装

  1. NotificationCallback 包装的接口,解析 message 再派发到不同的方法中(参考 MaaMsg.h)。如 on_resource_loading_starting(data)。也可将 ResourceLoading 作为 Event 枚举,Starting 作为 Type 枚举派发,如 on_notification(event, type, data)。其中 data 为 detail_json 解析出的结构体,而不是直接给出原始 json 。
  2. NotificationCallback 包装的接口,可以考虑增加 on_unknown_notification 方法,用于暂时应对 MaaFW 后续新增的消息。detail_json 解析出的结构体中也可考虑加入 raw 字段或其他表示未知内容的字段。
  3. MaaTaskerGetRecognitionDetail 获取的 detail_json,请拆分成 all_results, filtered_results, best_result(注意 best 可能为 null),并根据 algorithm 解析成不同的结构体
  4. 更多:TODO...