Struct Context 

pub struct Context { /* private fields */ }

Represents the execution context of a task.

This struct provides an interface for interacting with the current task’s runtime state. Capabilities include:

• Executing sub-tasks.
• Overriding pipeline configurations dynamically.
• Performing direct recognition and actions.
• Managing node hit counts and control flow anchors.

Safety

Context is a wrapper around a non-owning pointer (MaaContext). The underlying resources are managed by the Tasker. Users must ensure the Context does not outlive the validity of the underlying task or callback scope.

Implementations

impl Context

pub fn run_task(&self, entry: &str, pipeline_override: &str) -> MaaResult<i64>

Submits a new task for execution.

Arguments

• entry - The name of the task entry point.
• pipeline_override - A JSON string specifying pipeline parameter overrides.

Returns

Returns the job ID (MaaId) associated with the submitted task.

pub fn override_pipeline(&self, override_json: &str) -> MaaResult<()>

Overrides pipeline parameters for the current context.

Arguments

• override_json - A JSON string containing the parameters to override.

Examples found in repository

examples/main.rs (line 73)

    fn analyze(
        &self,
        context: &Context,
        _task_id: sys::MaaTaskId,
        node_name: &str,
        custom_recognition_name: &str,
        custom_recognition_param: &str,
        _image: &maa_framework::buffer::MaaImageBuffer,
        _roi: &maa_framework::common::Rect,
    ) -> Option<(maa_framework::common::Rect, String)> {
        println!(
            "[MyRecognition] analyze called: node={}, name={}, param={}",
            node_name, custom_recognition_name, custom_recognition_param
        );

        // --- Context API Demo ---

        // 1. Run sub-pipeline recognition with override
        let pp_override = r#"{"MyCustomOCR": {"recognition": "OCR", "roi": [100, 100, 200, 300]}}"#;
        if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
            let reco_id = context.run_recognition("MyCustomOCR", pp_override, &img_buf);
            println!("  run_recognition result: {:?}", reco_id);
        }

        // 2. Take a new screenshot via tasker's controller
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Note: In real usage, you would use the Tasker's controller reference
            println!("  tasker handle available for controller access");
        }

        // 3. Async click - post now, will wait later
        // (In real code, you'd get controller from context.tasker)
        println!("  [Demo] Would post async click at (10, 20)");

        // 4. Override pipeline for all subsequent operations in this context
        let _ = context.override_pipeline(r#"{"MyCustomOCR": {"roi": [1, 1, 114, 514]}}"#);

        // 5. Check if tasker is stopping - IMPORTANT for responsive cancellation
        // Note: Context provides tasker_handle() which returns a raw pointer.
        // In production code, you should wrap this or use the Tasker instance directly.
        // Here we demonstrate the raw API call for completeness.
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Using sys:: directly requires unsafe - this matches C API usage
            let is_stopping = unsafe { sys::MaaTaskerStopping(tasker_ptr) != 0 };
            if is_stopping {
                println!("  Task is stopping, returning early!");
                return Some((
                    common::Rect {
                        x: 0,
                        y: 0,
                        width: 0,
                        height: 0,
                    },
                    r#"{"status": "Task Stopped"}"#.to_string(),
                ));
            }
        }

        // 6. Wait for the async click to complete
        println!("  [Demo] Async click would complete here");

        // 7. Clone context for independent operations (modifications won't affect original)
        if let Ok(new_ctx) = context.clone_context() {
            let _ = new_ctx.override_pipeline(r#"{"MyCustomOCR": {"roi": [100, 200, 300, 400]}}"#);

            // Run recognition and use the result
            if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
                let reco_id = new_ctx.run_recognition("MyCustomOCR", "{}", &img_buf);

                // If recognition succeeded, get the tasker to retrieve details
                if reco_id.is_ok() {
                    // In a real scenario, you would:
                    // 1. Get recognition detail from tasker
                    // 2. Check if it hit
                    // 3. Use the box coordinates to click
                    println!("  [Demo] Would get reco detail and click on result box");

                    // Example of clicking on recognition result box:
                    // if let Ok(Some(detail)) = tasker.get_recognition_detail(reco_id) {
                    //     if detail.hit {
                    //         let box_rect = detail.box_rect;
                    //         controller.post_click(box_rect.x, box_rect.y).wait();
                    //     }
                    // }
                }
            }
            // new_ctx changes don't affect original context
        }

        // 8. Get current task ID
        let task_id = context.task_id();
        println!("  current task_id: {}", task_id);

        // 9. Get task job for result retrieval
        let task_job = context.get_task_job();
        if let Ok(Some(detail)) = task_job.get(false) {
            println!("  task entry: {}", detail.entry);
        }

        // Return recognition result: bounding box + detail JSON
        Some((
            common::Rect {
                x: 0,
                y: 0,
                width: 100,
                height: 100,
            },
            r#"{"message": "Hello World!"}"#.to_string(),
        ))
    }

pub fn raw(&self) -> *mut MaaContext

Returns the underlying raw MaaContext pointer.

Useful for advanced FFI interop scenarios.

pub fn run_recognition( &self, entry: &str, pipeline_override: &str, image: &MaaImageBuffer, ) -> MaaResult<i64>

Runs a specific recognition task with an input image.

Arguments

• entry - The task entry name.
• pipeline_override - A JSON string for parameter overrides.
• image - The input image buffer.

Returns

Returns the job ID associated with the recognition task.

Examples found in repository

examples/main.rs (line 57)

    fn analyze(
        &self,
        context: &Context,
        _task_id: sys::MaaTaskId,
        node_name: &str,
        custom_recognition_name: &str,
        custom_recognition_param: &str,
        _image: &maa_framework::buffer::MaaImageBuffer,
        _roi: &maa_framework::common::Rect,
    ) -> Option<(maa_framework::common::Rect, String)> {
        println!(
            "[MyRecognition] analyze called: node={}, name={}, param={}",
            node_name, custom_recognition_name, custom_recognition_param
        );

        // --- Context API Demo ---

        // 1. Run sub-pipeline recognition with override
        let pp_override = r#"{"MyCustomOCR": {"recognition": "OCR", "roi": [100, 100, 200, 300]}}"#;
        if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
            let reco_id = context.run_recognition("MyCustomOCR", pp_override, &img_buf);
            println!("  run_recognition result: {:?}", reco_id);
        }

        // 2. Take a new screenshot via tasker's controller
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Note: In real usage, you would use the Tasker's controller reference
            println!("  tasker handle available for controller access");
        }

        // 3. Async click - post now, will wait later
        // (In real code, you'd get controller from context.tasker)
        println!("  [Demo] Would post async click at (10, 20)");

        // 4. Override pipeline for all subsequent operations in this context
        let _ = context.override_pipeline(r#"{"MyCustomOCR": {"roi": [1, 1, 114, 514]}}"#);

        // 5. Check if tasker is stopping - IMPORTANT for responsive cancellation
        // Note: Context provides tasker_handle() which returns a raw pointer.
        // In production code, you should wrap this or use the Tasker instance directly.
        // Here we demonstrate the raw API call for completeness.
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Using sys:: directly requires unsafe - this matches C API usage
            let is_stopping = unsafe { sys::MaaTaskerStopping(tasker_ptr) != 0 };
            if is_stopping {
                println!("  Task is stopping, returning early!");
                return Some((
                    common::Rect {
                        x: 0,
                        y: 0,
                        width: 0,
                        height: 0,
                    },
                    r#"{"status": "Task Stopped"}"#.to_string(),
                ));
            }
        }

        // 6. Wait for the async click to complete
        println!("  [Demo] Async click would complete here");

        // 7. Clone context for independent operations (modifications won't affect original)
        if let Ok(new_ctx) = context.clone_context() {
            let _ = new_ctx.override_pipeline(r#"{"MyCustomOCR": {"roi": [100, 200, 300, 400]}}"#);

            // Run recognition and use the result
            if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
                let reco_id = new_ctx.run_recognition("MyCustomOCR", "{}", &img_buf);

                // If recognition succeeded, get the tasker to retrieve details
                if reco_id.is_ok() {
                    // In a real scenario, you would:
                    // 1. Get recognition detail from tasker
                    // 2. Check if it hit
                    // 3. Use the box coordinates to click
                    println!("  [Demo] Would get reco detail and click on result box");

                    // Example of clicking on recognition result box:
                    // if let Ok(Some(detail)) = tasker.get_recognition_detail(reco_id) {
                    //     if detail.hit {
                    //         let box_rect = detail.box_rect;
                    //         controller.post_click(box_rect.x, box_rect.y).wait();
                    //     }
                    // }
                }
            }
            // new_ctx changes don't affect original context
        }

        // 8. Get current task ID
        let task_id = context.task_id();
        println!("  current task_id: {}", task_id);

        // 9. Get task job for result retrieval
        let task_job = context.get_task_job();
        if let Ok(Some(detail)) = task_job.get(false) {
            println!("  task entry: {}", detail.entry);
        }

        // Return recognition result: bounding box + detail JSON
        Some((
            common::Rect {
                x: 0,
                y: 0,
                width: 100,
                height: 100,
            },
            r#"{"message": "Hello World!"}"#.to_string(),
        ))
    }

pub fn run_recognition_direct( &self, reco_type: &str, reco_param: &str, image: &MaaImageBuffer, ) -> MaaResult<Option<RecognitionDetail>>

Performs a direct recognition operation.

This executes a specific recognition algorithm immediately, bypassing the pipeline structure.

Arguments

• reco_type - The specific recognition algorithm type (e.g., “TemplateMatch”, “OCR”).
• reco_param - A JSON string containing the recognition parameters.
• image - The image buffer to perform recognition on.

Returns

Returns Some(RecognitionDetail) if successful, or None if the operation failed to initiate or yielded no result.

pub fn run_action( &self, entry: &str, pipeline_override: &str, box_rect: &Rect, reco_detail: &str, ) -> MaaResult<i64>

Runs a specific action with context parameters.

Arguments

• entry - The task entry name.
• pipeline_override - A JSON string for parameter overrides.
• box_rect - The target region for the action.
• reco_detail - A string containing details from a previous recognition step.

Returns

Returns the job ID associated with the action.

Examples found in repository

examples/main.rs (lines 181-191)

    fn run(
        &self,
        context: &Context,
        _task_id: sys::MaaTaskId,
        node_name: &str,
        custom_action_name: &str,
        custom_action_param: &str,
        reco_id: sys::MaaRecoId,
        box_rect: &maa_framework::common::Rect,
    ) -> bool {
        println!(
            "[MyAction] run called: node={}, name={}, param={}",
            node_name, custom_action_name, custom_action_param
        );
        println!(
            "  reco_id={}, box=({}, {}, {}, {})",
            reco_id, box_rect.x, box_rect.y, box_rect.width, box_rect.height
        );

        // You can use Context API here too
        let _ = context.run_action(
            "Click",
            "{}",
            &common::Rect {
                x: 114,
                y: 514,
                width: 100,
                height: 100,
            },
            "{}",
        );

        true // Return true for success, false for failure
    }

pub fn run_action_direct( &self, action_type: &str, action_param: &str, box_rect: &Rect, reco_detail: &str, ) -> MaaResult<Option<ActionDetail>>

Performs a direct action operation.

This executes a specific action immediately, bypassing the pipeline structure.

Arguments

• action_type - The type of action to perform (e.g., “Click”, “Swipe”).
• action_param - A JSON string containing the action parameters.
• box_rect - The target region for the action (e.g., derived from recognition results).
• reco_detail - Contextual details from a previous recognition step.

Returns

Returns Some(ActionDetail) on success, or None if the operation failed.

pub fn override_next( &self, node_name: &str, next_list: &[&str], ) -> MaaResult<bool>

Overrides the execution list for a specific node.

Arguments

• node_name - The name of the target node.
• next_list - A slice of strings representing the new next list. Supports special signals like [JumpBack] and [Anchor].

Returns

• Ok(true) if the override was successful.
• Ok(false) if the operation failed.

pub fn get_node_data(&self, node_name: &str) -> MaaResult<Option<String>>

Retrieves data associated with a specific node.

Arguments

• node_name - The name of the node.

Returns

Returns the node data as a String if available, or None otherwise.

pub fn get_node_object( &self, node_name: &str, ) -> MaaResult<Option<PipelineData>>

Retrieves and deserializes the object associated with a node.

This is a convenience wrapper around get_node_data that parses the result into PipelineData.

Arguments

• node_name - The name of the node.

Errors

Returns MaaError::InvalidConfig if the data cannot be parsed.

pub fn task_id(&self) -> MaaId

Returns the ID of the current task.

Examples found in repository

examples/main.rs (line 129)

    fn analyze(
        &self,
        context: &Context,
        _task_id: sys::MaaTaskId,
        node_name: &str,
        custom_recognition_name: &str,
        custom_recognition_param: &str,
        _image: &maa_framework::buffer::MaaImageBuffer,
        _roi: &maa_framework::common::Rect,
    ) -> Option<(maa_framework::common::Rect, String)> {
        println!(
            "[MyRecognition] analyze called: node={}, name={}, param={}",
            node_name, custom_recognition_name, custom_recognition_param
        );

        // --- Context API Demo ---

        // 1. Run sub-pipeline recognition with override
        let pp_override = r#"{"MyCustomOCR": {"recognition": "OCR", "roi": [100, 100, 200, 300]}}"#;
        if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
            let reco_id = context.run_recognition("MyCustomOCR", pp_override, &img_buf);
            println!("  run_recognition result: {:?}", reco_id);
        }

        // 2. Take a new screenshot via tasker's controller
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Note: In real usage, you would use the Tasker's controller reference
            println!("  tasker handle available for controller access");
        }

        // 3. Async click - post now, will wait later
        // (In real code, you'd get controller from context.tasker)
        println!("  [Demo] Would post async click at (10, 20)");

        // 4. Override pipeline for all subsequent operations in this context
        let _ = context.override_pipeline(r#"{"MyCustomOCR": {"roi": [1, 1, 114, 514]}}"#);

        // 5. Check if tasker is stopping - IMPORTANT for responsive cancellation
        // Note: Context provides tasker_handle() which returns a raw pointer.
        // In production code, you should wrap this or use the Tasker instance directly.
        // Here we demonstrate the raw API call for completeness.
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Using sys:: directly requires unsafe - this matches C API usage
            let is_stopping = unsafe { sys::MaaTaskerStopping(tasker_ptr) != 0 };
            if is_stopping {
                println!("  Task is stopping, returning early!");
                return Some((
                    common::Rect {
                        x: 0,
                        y: 0,
                        width: 0,
                        height: 0,
                    },
                    r#"{"status": "Task Stopped"}"#.to_string(),
                ));
            }
        }

        // 6. Wait for the async click to complete
        println!("  [Demo] Async click would complete here");

        // 7. Clone context for independent operations (modifications won't affect original)
        if let Ok(new_ctx) = context.clone_context() {
            let _ = new_ctx.override_pipeline(r#"{"MyCustomOCR": {"roi": [100, 200, 300, 400]}}"#);

            // Run recognition and use the result
            if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
                let reco_id = new_ctx.run_recognition("MyCustomOCR", "{}", &img_buf);

                // If recognition succeeded, get the tasker to retrieve details
                if reco_id.is_ok() {
                    // In a real scenario, you would:
                    // 1. Get recognition detail from tasker
                    // 2. Check if it hit
                    // 3. Use the box coordinates to click
                    println!("  [Demo] Would get reco detail and click on result box");

                    // Example of clicking on recognition result box:
                    // if let Ok(Some(detail)) = tasker.get_recognition_detail(reco_id) {
                    //     if detail.hit {
                    //         let box_rect = detail.box_rect;
                    //         controller.post_click(box_rect.x, box_rect.y).wait();
                    //     }
                    // }
                }
            }
            // new_ctx changes don't affect original context
        }

        // 8. Get current task ID
        let task_id = context.task_id();
        println!("  current task_id: {}", task_id);

        // 9. Get task job for result retrieval
        let task_job = context.get_task_job();
        if let Ok(Some(detail)) = task_job.get(false) {
            println!("  task entry: {}", detail.entry);
        }

        // Return recognition result: bounding box + detail JSON
        Some((
            common::Rect {
                x: 0,
                y: 0,
                width: 100,
                height: 100,
            },
            r#"{"message": "Hello World!"}"#.to_string(),
        ))
    }

pub fn set_anchor(&self, anchor_name: &str, node_name: &str) -> MaaResult<()>

Associates an anchor with a specific node.

Arguments

• anchor_name - The name of the anchor.
• node_name - The name of the target node.

pub fn get_anchor(&self, anchor_name: &str) -> MaaResult<Option<String>>

Retrieves the node name associated with an anchor.

Arguments

• anchor_name - The name of the anchor.

Returns

Returns the node name as a String if the anchor exists.

pub fn get_hit_count(&self, node_name: &str) -> MaaResult<u64>

Retrieves the hit count for a specific node.

Hit count tracks how many times a node has been executed.

Arguments

• node_name - The name of the node to query.

Returns

The number of times the node has been executed, or 0 if not found.

pub fn clear_hit_count(&self, node_name: &str) -> MaaResult<()>

Resets the hit count for a specific node to zero.

Arguments

• node_name - The name of the node to reset.

pub fn clone_context(&self) -> MaaResult<Self>

Creates a clone of the current context.

The new context can be used for independent execution threads, preventing state interference with the original context.

Examples found in repository

examples/main.rs (line 101)

    fn analyze(
        &self,
        context: &Context,
        _task_id: sys::MaaTaskId,
        node_name: &str,
        custom_recognition_name: &str,
        custom_recognition_param: &str,
        _image: &maa_framework::buffer::MaaImageBuffer,
        _roi: &maa_framework::common::Rect,
    ) -> Option<(maa_framework::common::Rect, String)> {
        println!(
            "[MyRecognition] analyze called: node={}, name={}, param={}",
            node_name, custom_recognition_name, custom_recognition_param
        );

        // --- Context API Demo ---

        // 1. Run sub-pipeline recognition with override
        let pp_override = r#"{"MyCustomOCR": {"recognition": "OCR", "roi": [100, 100, 200, 300]}}"#;
        if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
            let reco_id = context.run_recognition("MyCustomOCR", pp_override, &img_buf);
            println!("  run_recognition result: {:?}", reco_id);
        }

        // 2. Take a new screenshot via tasker's controller
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Note: In real usage, you would use the Tasker's controller reference
            println!("  tasker handle available for controller access");
        }

        // 3. Async click - post now, will wait later
        // (In real code, you'd get controller from context.tasker)
        println!("  [Demo] Would post async click at (10, 20)");

        // 4. Override pipeline for all subsequent operations in this context
        let _ = context.override_pipeline(r#"{"MyCustomOCR": {"roi": [1, 1, 114, 514]}}"#);

        // 5. Check if tasker is stopping - IMPORTANT for responsive cancellation
        // Note: Context provides tasker_handle() which returns a raw pointer.
        // In production code, you should wrap this or use the Tasker instance directly.
        // Here we demonstrate the raw API call for completeness.
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Using sys:: directly requires unsafe - this matches C API usage
            let is_stopping = unsafe { sys::MaaTaskerStopping(tasker_ptr) != 0 };
            if is_stopping {
                println!("  Task is stopping, returning early!");
                return Some((
                    common::Rect {
                        x: 0,
                        y: 0,
                        width: 0,
                        height: 0,
                    },
                    r#"{"status": "Task Stopped"}"#.to_string(),
                ));
            }
        }

        // 6. Wait for the async click to complete
        println!("  [Demo] Async click would complete here");

        // 7. Clone context for independent operations (modifications won't affect original)
        if let Ok(new_ctx) = context.clone_context() {
            let _ = new_ctx.override_pipeline(r#"{"MyCustomOCR": {"roi": [100, 200, 300, 400]}}"#);

            // Run recognition and use the result
            if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
                let reco_id = new_ctx.run_recognition("MyCustomOCR", "{}", &img_buf);

                // If recognition succeeded, get the tasker to retrieve details
                if reco_id.is_ok() {
                    // In a real scenario, you would:
                    // 1. Get recognition detail from tasker
                    // 2. Check if it hit
                    // 3. Use the box coordinates to click
                    println!("  [Demo] Would get reco detail and click on result box");

                    // Example of clicking on recognition result box:
                    // if let Ok(Some(detail)) = tasker.get_recognition_detail(reco_id) {
                    //     if detail.hit {
                    //         let box_rect = detail.box_rect;
                    //         controller.post_click(box_rect.x, box_rect.y).wait();
                    //     }
                    // }
                }
            }
            // new_ctx changes don't affect original context
        }

        // 8. Get current task ID
        let task_id = context.task_id();
        println!("  current task_id: {}", task_id);

        // 9. Get task job for result retrieval
        let task_job = context.get_task_job();
        if let Ok(Some(detail)) = task_job.get(false) {
            println!("  task entry: {}", detail.entry);
        }

        // Return recognition result: bounding box + detail JSON
        Some((
            common::Rect {
                x: 0,
                y: 0,
                width: 100,
                height: 100,
            },
            r#"{"message": "Hello World!"}"#.to_string(),
        ))
    }

pub fn tasker_handle(&self) -> *mut MaaTasker

Returns the raw handle to the associated Tasker instance.

Safety

The returned pointer is owned by the framework. The caller must not attempt to destroy or free it.

Examples found in repository

examples/main.rs (line 62)

    fn analyze(
        &self,
        context: &Context,
        _task_id: sys::MaaTaskId,
        node_name: &str,
        custom_recognition_name: &str,
        custom_recognition_param: &str,
        _image: &maa_framework::buffer::MaaImageBuffer,
        _roi: &maa_framework::common::Rect,
    ) -> Option<(maa_framework::common::Rect, String)> {
        println!(
            "[MyRecognition] analyze called: node={}, name={}, param={}",
            node_name, custom_recognition_name, custom_recognition_param
        );

        // --- Context API Demo ---

        // 1. Run sub-pipeline recognition with override
        let pp_override = r#"{"MyCustomOCR": {"recognition": "OCR", "roi": [100, 100, 200, 300]}}"#;
        if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
            let reco_id = context.run_recognition("MyCustomOCR", pp_override, &img_buf);
            println!("  run_recognition result: {:?}", reco_id);
        }

        // 2. Take a new screenshot via tasker's controller
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Note: In real usage, you would use the Tasker's controller reference
            println!("  tasker handle available for controller access");
        }

        // 3. Async click - post now, will wait later
        // (In real code, you'd get controller from context.tasker)
        println!("  [Demo] Would post async click at (10, 20)");

        // 4. Override pipeline for all subsequent operations in this context
        let _ = context.override_pipeline(r#"{"MyCustomOCR": {"roi": [1, 1, 114, 514]}}"#);

        // 5. Check if tasker is stopping - IMPORTANT for responsive cancellation
        // Note: Context provides tasker_handle() which returns a raw pointer.
        // In production code, you should wrap this or use the Tasker instance directly.
        // Here we demonstrate the raw API call for completeness.
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Using sys:: directly requires unsafe - this matches C API usage
            let is_stopping = unsafe { sys::MaaTaskerStopping(tasker_ptr) != 0 };
            if is_stopping {
                println!("  Task is stopping, returning early!");
                return Some((
                    common::Rect {
                        x: 0,
                        y: 0,
                        width: 0,
                        height: 0,
                    },
                    r#"{"status": "Task Stopped"}"#.to_string(),
                ));
            }
        }

        // 6. Wait for the async click to complete
        println!("  [Demo] Async click would complete here");

        // 7. Clone context for independent operations (modifications won't affect original)
        if let Ok(new_ctx) = context.clone_context() {
            let _ = new_ctx.override_pipeline(r#"{"MyCustomOCR": {"roi": [100, 200, 300, 400]}}"#);

            // Run recognition and use the result
            if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
                let reco_id = new_ctx.run_recognition("MyCustomOCR", "{}", &img_buf);

                // If recognition succeeded, get the tasker to retrieve details
                if reco_id.is_ok() {
                    // In a real scenario, you would:
                    // 1. Get recognition detail from tasker
                    // 2. Check if it hit
                    // 3. Use the box coordinates to click
                    println!("  [Demo] Would get reco detail and click on result box");

                    // Example of clicking on recognition result box:
                    // if let Ok(Some(detail)) = tasker.get_recognition_detail(reco_id) {
                    //     if detail.hit {
                    //         let box_rect = detail.box_rect;
                    //         controller.post_click(box_rect.x, box_rect.y).wait();
                    //     }
                    // }
                }
            }
            // new_ctx changes don't affect original context
        }

        // 8. Get current task ID
        let task_id = context.task_id();
        println!("  current task_id: {}", task_id);

        // 9. Get task job for result retrieval
        let task_job = context.get_task_job();
        if let Ok(Some(detail)) = task_job.get(false) {
            println!("  task entry: {}", detail.entry);
        }

        // Return recognition result: bounding box + detail JSON
        Some((
            common::Rect {
                x: 0,
                y: 0,
                width: 100,
                height: 100,
            },
            r#"{"message": "Hello World!"}"#.to_string(),
        ))
    }

pub fn override_image( &self, image_name: &str, image: &MaaImageBuffer, ) -> MaaResult<()>

Overrides a global image resource with a provided buffer.

Arguments

• image_name - The identifier of the image to override.
• image - The new image data buffer.

pub fn get_task_job<'a>(&'a self) -> JobWithResult<'a, TaskDetail>

Retrieves a job handle representing the current task’s execution state.

The returned job is bound to the lifetime of the Context to ensure safety.

Examples found in repository

examples/main.rs (line 133)

    fn analyze(
        &self,
        context: &Context,
        _task_id: sys::MaaTaskId,
        node_name: &str,
        custom_recognition_name: &str,
        custom_recognition_param: &str,
        _image: &maa_framework::buffer::MaaImageBuffer,
        _roi: &maa_framework::common::Rect,
    ) -> Option<(maa_framework::common::Rect, String)> {
        println!(
            "[MyRecognition] analyze called: node={}, name={}, param={}",
            node_name, custom_recognition_name, custom_recognition_param
        );

        // --- Context API Demo ---

        // 1. Run sub-pipeline recognition with override
        let pp_override = r#"{"MyCustomOCR": {"recognition": "OCR", "roi": [100, 100, 200, 300]}}"#;
        if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
            let reco_id = context.run_recognition("MyCustomOCR", pp_override, &img_buf);
            println!("  run_recognition result: {:?}", reco_id);
        }

        // 2. Take a new screenshot via tasker's controller
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Note: In real usage, you would use the Tasker's controller reference
            println!("  tasker handle available for controller access");
        }

        // 3. Async click - post now, will wait later
        // (In real code, you'd get controller from context.tasker)
        println!("  [Demo] Would post async click at (10, 20)");

        // 4. Override pipeline for all subsequent operations in this context
        let _ = context.override_pipeline(r#"{"MyCustomOCR": {"roi": [1, 1, 114, 514]}}"#);

        // 5. Check if tasker is stopping - IMPORTANT for responsive cancellation
        // Note: Context provides tasker_handle() which returns a raw pointer.
        // In production code, you should wrap this or use the Tasker instance directly.
        // Here we demonstrate the raw API call for completeness.
        let tasker_ptr = context.tasker_handle();
        if !tasker_ptr.is_null() {
            // Using sys:: directly requires unsafe - this matches C API usage
            let is_stopping = unsafe { sys::MaaTaskerStopping(tasker_ptr) != 0 };
            if is_stopping {
                println!("  Task is stopping, returning early!");
                return Some((
                    common::Rect {
                        x: 0,
                        y: 0,
                        width: 0,
                        height: 0,
                    },
                    r#"{"status": "Task Stopped"}"#.to_string(),
                ));
            }
        }

        // 6. Wait for the async click to complete
        println!("  [Demo] Async click would complete here");

        // 7. Clone context for independent operations (modifications won't affect original)
        if let Ok(new_ctx) = context.clone_context() {
            let _ = new_ctx.override_pipeline(r#"{"MyCustomOCR": {"roi": [100, 200, 300, 400]}}"#);

            // Run recognition and use the result
            if let Ok(img_buf) = buffer::MaaImageBuffer::new() {
                let reco_id = new_ctx.run_recognition("MyCustomOCR", "{}", &img_buf);

                // If recognition succeeded, get the tasker to retrieve details
                if reco_id.is_ok() {
                    // In a real scenario, you would:
                    // 1. Get recognition detail from tasker
                    // 2. Check if it hit
                    // 3. Use the box coordinates to click
                    println!("  [Demo] Would get reco detail and click on result box");

                    // Example of clicking on recognition result box:
                    // if let Ok(Some(detail)) = tasker.get_recognition_detail(reco_id) {
                    //     if detail.hit {
                    //         let box_rect = detail.box_rect;
                    //         controller.post_click(box_rect.x, box_rect.y).wait();
                    //     }
                    // }
                }
            }
            // new_ctx changes don't affect original context
        }

        // 8. Get current task ID
        let task_id = context.task_id();
        println!("  current task_id: {}", task_id);

        // 9. Get task job for result retrieval
        let task_job = context.get_task_job();
        if let Ok(Some(detail)) = task_job.get(false) {
            println!("  task entry: {}", detail.entry);
        }

        // Return recognition result: bounding box + detail JSON
        Some((
            common::Rect {
                x: 0,
                y: 0,
                width: 100,
                height: 100,
            },
            r#"{"message": "Hello World!"}"#.to_string(),
        ))
    }

pub fn clear_all_hit_counts(&self) -> MaaResult<()>

Resets hit counts for all nodes in the context.

This clears the execution history for all nodes, resetting their hit counts to zero.

Trait Implementations

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Send for Context