Callback Protocol

MaaFramework sends various status notifications and event messages to upper-layer applications through the MaaEventCallback callback function. All callback messages follow a unified format: message type (message) + detailed data (details).

Message Format

typedef void(MAA_CALL* MaaEventCallback)(void* handle, const char* message, const char* details_json, void* trans_arg);

• handle: Handle of the related object
  • MaaTasker* for MaaTasker event
  • MaaResource* for MaaResource event
  • MaaController* for MaaController event
  • MaaContext* for MaaContext event
• message: Message type string that identifies the event type
• details_json: JSON-formatted detailed data containing specific event information
• trans_arg: User-defined callback parameter

Message Types

Resource Loading Messages

Used to notify changes in resource loading status.

Resource.Loading.Starting

Sent when resource loading begins.

details_json structure:

{
    "res_id": 12345,
    "hash": "abc123def456",
    "path": "/path/to/resource"
}

• res_id: Resource ID (number)
• hash: Resource hash value (string)
• path: Resource path (string)

Resource.Loading.Succeeded

Sent when resource loading succeeds. Same data structure as above.

Resource.Loading.Failed

Sent when resource loading fails. Same data structure as above.

Controller Action Messages

Used to notify the status of controller action execution.

Controller.Action.Starting

Sent when the controller begins executing an action.

details_json structure:

{
    "ctrl_id": 12345,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "action": "Click",
    "param": {
        "x": 100,
        "y": 200
    }
}

• ctrl_id: Controller ID (number)
• uuid: Unique identifier (string)
• action: Action type (string)
• param: Action parameters (object)

Controller.Action.Succeeded

Sent when controller action execution succeeds. Same data structure as above.

Controller.Action.Failed

Sent when controller action execution fails. Same data structure as above.

Task Messages

Used to notify task execution status.

Tasker.Task.Starting

Sent when task execution begins.

details_json structure:

{
    "task_id": 12345,
    "entry": "MyTask",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "hash": "abc123def456"
}

• task_id: Task ID (number)
• entry: Entry task name (string)
• uuid: Unique identifier (string)
• hash: Task hash value (string)

Tasker.Task.Succeeded

Sent when task execution succeeds. Same data structure as above.

Tasker.Task.Failed

Sent when task execution fails. Same data structure as above.

Node Next List Messages

Used to notify the next action list of a node.

Node.NextList.Starting

Sent when a node begins determining its next action list.

details_json structure:

{
    "task_id": 12345,
    "name": "NodeA",
    "list": ["action1", "action2", "action3"],
    "focus": any,
}

• task_id: Task ID (number)
• name: Node name (string)
• list: Next action list (string array)
• focus: Focus-related data (any type)

Node.NextList.Succeeded

Sent when a node successfully determines its next action list. Same data structure as above.

Node.NextList.Failed

Sent when a node fails to determine its next action list. Same data structure as above.

Node Recognition Messages

Used to notify the status of node recognition processes.

Node.Recognition.Starting

Sent when node recognition begins.

details_json structure:

{
    "task_id": 12345,
    "reco_id": 67890,
    "name": "NodeA",
    "focus": any,
}

• task_id: Task ID (number)
• reco_id: Recognition ID (number)
• name: Node name (string)
• focus: Focus-related data (any type)

Node.Recognition.Succeeded

Sent when node recognition succeeds. Same data structure as above.

Node.Recognition.Failed

Sent when node recognition fails. Same data structure as above.

Node Action Messages

Used to notify the status of node action execution.

Node.Action.Starting

Sent when a node begins executing an action.

details_json structure:

{
    "task_id": 12345,
    "node_id": 67890,
    "name": "NodeA",
    "focus": any,
}

• task_id: Task ID (number)
• node_id: Node ID (number)
• name: Node name (string)
• focus: Focus-related data (any type)

Node.Action.Succeeded

Sent when node action execution succeeds. Same data structure as above.

Node.Action.Failed

Sent when node action execution fails. Same data structure as above.

Usage Example

void MyCallback(void* handle, const char* message, const char* details_json, void* callback_arg)
{
    // Parse message type
    if (strcmp(message, "Tasker.Task.Starting") == 0) {
        // Parse JSON to get task details
        // Update UI to show task starting status
    }
    else if (strcmp(message, "Node.Recognition.Succeeded") == 0) {
        // Handle recognition success event
        // Update recognition result display
    }
    // ... handle other message types
}

// Set callback
MaaTaskerAddSink(tasker, MyCallback, nullptr);
MaaTaskerAddNodeSink(tasker, MyCallback, nullptr);

Important Notes

1. JSON Parsing: The details_json parameter is always a valid JSON string. It's recommended to use a mature JSON library for parsing
2. Thread Safety: Callback functions may be called from different threads, so thread safety considerations are necessary
3. Performance: Callback functions should return quickly to avoid blocking the framework's execution flow
4. Error Handling: It's recommended to add exception handling in callback functions to prevent callback exceptions from affecting framework operation