The controller interface. See MaaControllerPostRequest for details on how to post requests to the controller. More...

#include "../MaaDef.h"
#include "../MaaPort.h"

Typedefs
typedef struct MaaCustomControllerCallbacks	MaaCustomControllerCallbacks

Functions
MAA_FRAMEWORK_API MaaController *	MaaAdbControllerCreate (const char adb_path, const char address, MaaAdbScreencapMethod screencap_methods, MaaAdbInputMethod input_methods, const char config, const char agent_path)

MAA_FRAMEWORK_API MaaController *	MaaWin32ControllerCreate (void *hWnd, MaaWin32ScreencapMethod screencap_method, MaaWin32InputMethod mouse_method, MaaWin32InputMethod keyboard_method)

MAA_FRAMEWORK_API MaaController *	MaaCustomControllerCreate (MaaCustomControllerCallbacks controller, void controller_arg)

MAA_FRAMEWORK_API MaaController *	MaaDbgControllerCreate (const char read_path, const char write_path, MaaDbgControllerType type, const char *config)

MAA_FRAMEWORK_API MaaController *	MaaPlayCoverControllerCreate (const char address, const char uuid)
	Create a PlayCover controller for macOS.

MAA_FRAMEWORK_API MaaController *	MaaGamepadControllerCreate (void *hWnd, MaaGamepadType gamepad_type, MaaWin32ScreencapMethod screencap_method)
	Create a virtual gamepad controller for Windows.

MAA_FRAMEWORK_API void	MaaControllerDestroy (MaaController *ctrl)

MAA_FRAMEWORK_API MaaSinkId	MaaControllerAddSink (MaaController ctrl, MaaEventCallback sink, void trans_arg)

MAA_FRAMEWORK_API void	MaaControllerRemoveSink (MaaController *ctrl, MaaSinkId sink_id)

MAA_FRAMEWORK_API void	MaaControllerClearSinks (MaaController *ctrl)

MAA_FRAMEWORK_API MaaBool	MaaControllerSetOption (MaaController *ctrl, MaaCtrlOption key, MaaOptionValue value, MaaOptionValueSize val_size)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostConnection (MaaController *ctrl)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostClick (MaaController *ctrl, int32_t x, int32_t y)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostClickV2 (MaaController *ctrl, int32_t x, int32_t y, int32_t contact, int32_t pressure)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostSwipe (MaaController *ctrl, int32_t x1, int32_t y1, int32_t x2, int32_t y2, int32_t duration)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostSwipeV2 (MaaController *ctrl, int32_t x1, int32_t y1, int32_t x2, int32_t y2, int32_t duration, int32_t contact, int32_t pressure)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostClickKey (MaaController *ctrl, int32_t keycode)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostInputText (MaaController ctrl, const char text)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostStartApp (MaaController ctrl, const char intent)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostStopApp (MaaController ctrl, const char intent)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostTouchDown (MaaController *ctrl, int32_t contact, int32_t x, int32_t y, int32_t pressure)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostTouchMove (MaaController *ctrl, int32_t contact, int32_t x, int32_t y, int32_t pressure)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostTouchUp (MaaController *ctrl, int32_t contact)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostKeyDown (MaaController *ctrl, int32_t keycode)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostKeyUp (MaaController *ctrl, int32_t keycode)

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostScreencap (MaaController *ctrl)
	Post a screenshot request to the controller.

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostScroll (MaaController *ctrl, int32_t dx, int32_t dy)
	Post a scroll action to the controller.

MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostShell (MaaController ctrl, const char cmd, int64_t timeout)
	Post a shell command to the controller.

MAA_FRAMEWORK_API MaaBool	MaaControllerGetShellOutput (const MaaController ctrl, MaaStringBuffer buffer)
	Get the cached shell command output.

MAA_FRAMEWORK_API MaaStatus	MaaControllerStatus (const MaaController *ctrl, MaaCtrlId id)

MAA_FRAMEWORK_API MaaStatus	MaaControllerWait (const MaaController *ctrl, MaaCtrlId id)

MAA_FRAMEWORK_API MaaBool	MaaControllerConnected (const MaaController *ctrl)

MAA_FRAMEWORK_API MaaBool	MaaControllerCachedImage (const MaaController ctrl, MaaImageBuffer buffer)
	Get the cached screenshot image.

MAA_FRAMEWORK_API MaaBool	MaaControllerGetUuid (MaaController ctrl, MaaStringBuffer buffer)

MAA_FRAMEWORK_API MaaBool	MaaControllerGetResolution (const MaaController ctrl, int32_t width, int32_t *height)
	Get the raw (unscaled) device resolution.

MAA_DEPRECATED MAA_FRAMEWORK_API MaaCtrlId	MaaControllerPostPressKey (MaaController *ctrl, int32_t keycode)

Detailed Description

The controller interface. See MaaControllerPostRequest for details on how to post requests to the controller.

Author

Copyright: Copyright (c) 2024

Typedef Documentation

◆ MaaCustomControllerCallbacks

typedef struct MaaCustomControllerCallbacks MaaCustomControllerCallbacks

Function Documentation

◆ MaaAdbControllerCreate()

MAA_FRAMEWORK_API MaaController * MaaAdbControllerCreate	(	const char *	adb_path,
		const char *	address,
		MaaAdbScreencapMethod	screencap_methods,
		MaaAdbInputMethod	input_methods,
		const char *	config,
		const char *	agent_path
	)

◆ MaaWin32ControllerCreate()

MAA_FRAMEWORK_API MaaController * MaaWin32ControllerCreate	(	void *	hWnd,
		MaaWin32ScreencapMethod	screencap_method,
		MaaWin32InputMethod	mouse_method,
		MaaWin32InputMethod	keyboard_method
	)

◆ MaaCustomControllerCreate()

MAA_FRAMEWORK_API MaaController * MaaCustomControllerCreate	(	MaaCustomControllerCallbacks *	controller,
		void *	controller_arg
	)

◆ MaaDbgControllerCreate()

MAA_FRAMEWORK_API MaaController * MaaDbgControllerCreate	(	const char *	read_path,
		const char *	write_path,
		MaaDbgControllerType	type,
		const char *	config
	)

◆ MaaPlayCoverControllerCreate()

MAA_FRAMEWORK_API MaaController * MaaPlayCoverControllerCreate	(	const char *	address,
		const char *	uuid
	)

Create a PlayCover controller for macOS.

Parameters

address	The PlayTools service address in "host:port" format.
uuid	The application bundle identifier (e.g., "com.hypergryph.arknights").

Returns: The controller handle, or nullptr on failure.

Note: This controller is designed for PlayCover on macOS.; Some features are not supported: start_app, input_text, click_key, key_down, key_up, scroll.; Only single touch is supported (contact must be 0).

◆ MaaGamepadControllerCreate()

MAA_FRAMEWORK_API MaaController * MaaGamepadControllerCreate	(	void *	hWnd,
		MaaGamepadType	gamepad_type,
		MaaWin32ScreencapMethod	screencap_method
	)

Create a virtual gamepad controller for Windows.

Parameters

hWnd	Window handle for screencap (optional, can be nullptr if screencap not needed).
gamepad_type	Type of virtual gamepad (MaaGamepadType_Xbox360 or MaaGamepadType_DualShock4).
screencap_method	Win32 screencap method to use. Ignored if hWnd is nullptr.

Returns: The controller handle, or nullptr on failure.

Note

Requires ViGEm Bus Driver to be installed on the system.

For gamepad control, use:

click_key/key_down/key_up: For digital buttons (A, B, X, Y, LB, RB, etc.) See MaaGamepadButton_* constants for available buttons.
touch_down/touch_move/touch_up: For analog inputs (sticks and triggers)
- contact 0 (MaaGamepadTouch_LeftStick): Left stick (x: -32768~32767, y: -32768~32767)
- contact 1 (MaaGamepadTouch_RightStick): Right stick (x: -32768~32767, y: -32768~32767)
- contact 2 (MaaGamepadTouch_LeftTrigger): Left trigger (pressure: 0~255, x/y ignored)
- contact 3 (MaaGamepadTouch_RightTrigger): Right trigger (pressure: 0~255, x/y ignored)

click and swipe are not directly supported for gamepad.

input_text, start_app, stop_app, scroll are not supported.

See also: MaaGamepadButton, MaaGamepadTouch, MaaGamepadType

◆ MaaControllerDestroy()

MAA_FRAMEWORK_API void MaaControllerDestroy ( MaaController * ctrl )

◆ MaaControllerAddSink()

MAA_FRAMEWORK_API MaaSinkId MaaControllerAddSink	(	MaaController *	ctrl,
		MaaEventCallback	sink,
		void *	trans_arg
	)

◆ MaaControllerRemoveSink()

MAA_FRAMEWORK_API void MaaControllerRemoveSink	(	MaaController *	ctrl,
		MaaSinkId	sink_id
	)

◆ MaaControllerClearSinks()

MAA_FRAMEWORK_API void MaaControllerClearSinks ( MaaController * ctrl )

◆ MaaControllerSetOption()

MAA_FRAMEWORK_API MaaBool MaaControllerSetOption	(	MaaController *	ctrl,
		MaaCtrlOption	key,
		MaaOptionValue	value,
		MaaOptionValueSize	val_size
	)

Parameters

[in] value

Parameters

value byte array, int*, char*, bool*

◆ MaaControllerPostConnection()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostConnection ( MaaController * ctrl )

◆ MaaControllerPostClick()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostClick	(	MaaController *	ctrl,
		int32_t	x,
		int32_t	y
	)

◆ MaaControllerPostClickV2()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostClickV2	(	MaaController *	ctrl,
		int32_t	x,
		int32_t	y,
		int32_t	contact,
		int32_t	pressure
	)

◆ MaaControllerPostSwipe()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostSwipe	(	MaaController *	ctrl,
		int32_t	x1,
		int32_t	y1,
		int32_t	x2,
		int32_t	y2,
		int32_t	duration
	)

◆ MaaControllerPostSwipeV2()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostSwipeV2	(	MaaController *	ctrl,
		int32_t	x1,
		int32_t	y1,
		int32_t	x2,
		int32_t	y2,
		int32_t	duration,
		int32_t	contact,
		int32_t	pressure
	)

◆ MaaControllerPostClickKey()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostClickKey	(	MaaController *	ctrl,
		int32_t	keycode
	)

◆ MaaControllerPostInputText()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostInputText	(	MaaController *	ctrl,
		const char *	text
	)

◆ MaaControllerPostStartApp()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostStartApp	(	MaaController *	ctrl,
		const char *	intent
	)

◆ MaaControllerPostStopApp()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostStopApp	(	MaaController *	ctrl,
		const char *	intent
	)

◆ MaaControllerPostTouchDown()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostTouchDown	(	MaaController *	ctrl,
		int32_t	contact,
		int32_t	x,
		int32_t	y,
		int32_t	pressure
	)

◆ MaaControllerPostTouchMove()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostTouchMove	(	MaaController *	ctrl,
		int32_t	contact,
		int32_t	x,
		int32_t	y,
		int32_t	pressure
	)

◆ MaaControllerPostTouchUp()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostTouchUp	(	MaaController *	ctrl,
		int32_t	contact
	)

◆ MaaControllerPostKeyDown()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostKeyDown	(	MaaController *	ctrl,
		int32_t	keycode
	)

◆ MaaControllerPostKeyUp()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostKeyUp	(	MaaController *	ctrl,
		int32_t	keycode
	)

◆ MaaControllerPostScreencap()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostScreencap ( MaaController * ctrl )

Post a screenshot request to the controller.

Parameters

ctrl	The controller handle.

Returns: The control id of the screenshot action.

Note: The screenshot image is scaled according to the screenshot target size settings (long side / short side). Use MaaControllerGetResolution to get the raw (unscaled) device resolution.

See also: MaaControllerCachedImage, MaaControllerSetOption, MaaControllerGetResolution

◆ MaaControllerPostScroll()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostScroll	(	MaaController *	ctrl,
		int32_t	dx,
		int32_t	dy
	)

Post a scroll action to the controller.

Parameters

ctrl	The controller handle.
dx	The horizontal scroll delta. Positive values scroll right, negative values scroll left.
dy	The vertical scroll delta. Positive values scroll up, negative values scroll down.

Returns: The control id of the scroll action.

Note: Not all controllers support scroll. If not supported, the action will fail.; The dx/dy values are sent directly as scroll increments. Using multiples of 120 (WHEEL_DELTA) is recommended for best compatibility.

◆ MaaControllerPostShell()

MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostShell	(	MaaController *	ctrl,
		const char *	cmd,
		int64_t	timeout
	)

Post a shell command to the controller.

Parameters

ctrl	The controller handle.
cmd	The shell command to execute.
timeout	Timeout in milliseconds. Default is 20000 (20 seconds).

Returns: The control id of the shell action.

Note: This is only valid for ADB controllers. If the controller is not an ADB controller, the action will fail.

See also: MaaControllerGetShellOutput

◆ MaaControllerGetShellOutput()

MAA_FRAMEWORK_API MaaBool MaaControllerGetShellOutput	(	const MaaController *	ctrl,
		MaaStringBuffer *	buffer
	)

Get the cached shell command output.

Parameters

ctrl	The controller handle.
buffer	The output buffer to store the command result.

Returns: true if the output is available, false otherwise.

Note: This returns the output from the most recent shell command execution.

◆ MaaControllerStatus()

MAA_FRAMEWORK_API MaaStatus MaaControllerStatus	(	const MaaController *	ctrl,
		MaaCtrlId	id
	)

◆ MaaControllerWait()

MAA_FRAMEWORK_API MaaStatus MaaControllerWait	(	const MaaController *	ctrl,
		MaaCtrlId	id
	)

◆ MaaControllerConnected()

MAA_FRAMEWORK_API MaaBool MaaControllerConnected ( const MaaController * ctrl )

◆ MaaControllerCachedImage()

MAA_FRAMEWORK_API MaaBool MaaControllerCachedImage	(	const MaaController *	ctrl,
		MaaImageBuffer *	buffer
	)

Get the cached screenshot image.

Parameters

ctrl	The controller handle.
buffer	The output buffer to store the screenshot image.

Returns: true if the screenshot is available, false otherwise.

Note: The returned image is scaled according to the screenshot target size settings (long side / short side). The image dimensions may differ from the raw device resolution. Use MaaControllerGetResolution to get the raw (unscaled) device resolution.

See also: MaaControllerPostScreencap, MaaControllerSetOption, MaaControllerGetResolution

◆ MaaControllerGetUuid()

MAA_FRAMEWORK_API MaaBool MaaControllerGetUuid	(	MaaController *	ctrl,
		MaaStringBuffer *	buffer
	)

◆ MaaControllerGetResolution()

MAA_FRAMEWORK_API MaaBool MaaControllerGetResolution	(	const MaaController *	ctrl,
		int32_t *	width,
		int32_t *	height
	)

Get the raw (unscaled) device resolution.

Parameters

	ctrl	The controller handle.
[out]	width	Output parameter for the raw width.
[out]	height	Output parameter for the raw height.

Returns: true if the resolution is available, false otherwise (e.g., not connected or no screenshot taken yet).

Note: This returns the actual device screen resolution before any scaling. The screenshot obtained via MaaControllerCachedImage is scaled according to the screenshot target size settings, so its dimensions may differ from this raw resolution.

See also: MaaControllerCachedImage, MaaControllerPostScreencap

◆ MaaControllerPostPressKey()

MAA_DEPRECATED MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostPressKey	(	MaaController *	ctrl,
		int32_t	keycode
	)

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ MaaCustomControllerCallbacks

Function Documentation

◆ MaaAdbControllerCreate()

◆ MaaWin32ControllerCreate()

◆ MaaCustomControllerCreate()

◆ MaaDbgControllerCreate()

◆ MaaPlayCoverControllerCreate()

◆ MaaGamepadControllerCreate()

◆ MaaControllerDestroy()

◆ MaaControllerAddSink()

◆ MaaControllerRemoveSink()

◆ MaaControllerClearSinks()

◆ MaaControllerSetOption()

◆ MaaControllerPostConnection()

◆ MaaControllerPostClick()

◆ MaaControllerPostClickV2()

◆ MaaControllerPostSwipe()

◆ MaaControllerPostSwipeV2()

◆ MaaControllerPostClickKey()

◆ MaaControllerPostInputText()

◆ MaaControllerPostStartApp()

◆ MaaControllerPostStopApp()

◆ MaaControllerPostTouchDown()

◆ MaaControllerPostTouchMove()

◆ MaaControllerPostTouchUp()

◆ MaaControllerPostKeyDown()

◆ MaaControllerPostKeyUp()

◆ MaaControllerPostScreencap()

◆ MaaControllerPostScroll()

◆ MaaControllerPostShell()

◆ MaaControllerGetShellOutput()

◆ MaaControllerStatus()

◆ MaaControllerWait()

◆ MaaControllerConnected()

◆ MaaControllerCachedImage()

◆ MaaControllerGetUuid()

◆ MaaControllerGetResolution()

◆ MaaControllerPostPressKey()