binding 可以分为两步:
- 对 C API 进行标准化的 OOP 封装。由于 MaaFW 接口相对较为稳定,在完成后不需要长期进行维护。
- 在 1 的基础上,解析回调 message, detail json, pipeline_override 等参数,封装成不同的函数及结构。这些字段可能会随着 MaaFW 更新不断变化,需要长期跟进 MaaFW 新版本修改。
若您希望为 MaaFW 添加某个语言的封装,可根据自身时间精力等安排,任选一种方式进行。
- MaaTasker, MaaResource, MaaController 需包装成对象,而非过程化的接口。例如 MaaContextGetTasker 这类的接口,也需要返回对象,而非 handle。可以考虑两种模型:
- 增加一个全局 handle - 对象引用 字典,通过 handle 去找原对象再返回。
- 对象无状态,仅负责引用 handle ,直接创建新对象返回。(可参考 python binding 中 own 字段)
- MaaTaskId, MaaCtrlId, MaaResId 等异步动作 id ,不对集成方返回。由 binding 封装成 Job 类,提供 wait, status, get 等方法。
- Job 类需提供可以由本 id 进行操作的所有方法的封装,例如 TaskJob 的 get 方法需返回 MaaTaskerGetTaskDetail 查询到的数据的封装。
- MaaRecoId, MaaNodeId 等查询类 id ,不对集成方返回。由 binding 调用 MaaTaskerGetRecoDetail 等接口查询,并包装成 RecoDetail, NodeDetail 等结构体再返回。
- CustomAction, CustomRecognition, NotificationCallback 等,需要包装一份 agent ,最好是虚基类。实际传给 maafw 的是 agent 对象中的指针,由 agent 将各个参数转换为本语言常用类型后,再交给集成方。
- CustomAction, CustomRecognition 的 agent 中请将 MaaCustomRecognitionCallback/MaaCustomActionCallback 的除 context 外的参数封装成结构体再交给集成方,避免后续 Callback 新增参数造成的集成方代码不兼容。返回值也请封装成结构。
- SetOption 中每个枚举拆分成独立的接口,例如 set_screenshot_target_long_side 等,而不将具体枚举提供给集成方。
- StringBuffer, ImageBuffer 等缓冲区,不对集成方返回。需要转换成本语言惯用的 string, image 类型再给出。
- BindResource, BindController, RegisterCustom 等接口需注意留一份引用,避免 gc 。
- MaaToolkit 中 Find 系列接口,直接返回封装过的结构体数组。
- 要求提供 sample ,其中展示的接口调用不应少于 python sample 。
- NotificationCallback 包装的接口,解析 message 再派发到不同的方法中(参考 MaaMsg.h)。如
on_resource_loading_starting(data)
。也可将 ResourceLoading 作为 Event 枚举,Starting 作为 Type 枚举派发,如on_notification(event, type, data)
。其中data
为 detail_json 解析出的结构体,而不是直接给出原始 json 。 - NotificationCallback 包装的接口,可以考虑增加 on_unknown_notification 方法,用于暂时应对 MaaFW 后续新增的消息。detail_json 解析出的结构体中也可考虑加入 raw 字段或其他表示未知内容的字段。
MaaTaskerGetRecognitionDetail
获取的 detail_json,请拆分成 all_results, filtered_results, best_result(注意 best 可能为 null),并根据 algorithm 解析成不同的结构体- 更多:TODO...