From 786c040a658992a8251988b022d7111d54528b7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9E=AB=E9=9B=A8?= <35213527+moomiji@users.noreply.github.com> Date: Sat, 18 Nov 2023 09:14:07 +0800 Subject: [PATCH] dev --- README.md | 64 +++++++++ .../Abstractions/MaaCommon.cs | 42 ++---- .../Abstractions/MaaOption.cs | 20 ++- .../Interop/Framework/MaaDef.cs | 17 --- .../Interop/Framework/Task/MaaCustomAction.cs | 1 + .../Framework/Task/MaaCustomRecognizer.cs | 1 + .../MaaController.cs | 133 ++++++------------ .../MaaCustomController.cs | 2 +- .../MaaInstance.cs | 42 +++--- src/MaaFramework.Binding.Native/MaaJob.cs | 38 ++--- .../MaaResource.cs | 6 +- .../MaaSyncContext.cs | 2 +- .../MaaThriftController.cs | 2 +- src/MaaFramework.Binding.Native/MaaToolKit.cs | 2 +- src/MaaFramework.Binding.Native/MaaUtility.cs | 2 +- .../Abstractions/IMaaCommon.cs | 12 ++ .../Abstractions/IMaaDefStruct.cs | 8 ++ .../Abstractions/IMaaOption.cs | 22 +++ .../Abstractions/IMaaPost.cs | 14 +- .../Enums/Binding/ConvertOption.cs | 6 - .../Enums/Binding/DisposeOptions.cs | 2 +- .../Enums/Binding/FlagsEnumExtension.cs | 46 ++++++ .../Enums/Binding/LinkOption.cs | 2 +- .../Exceptions/MaaJobStatusException.cs | 20 +-- src/MaaFramework.Binding/IMaaController.cs | 94 +++++++++++++ src/MaaFramework.Binding/IMaaInstance.cs | 11 ++ src/MaaFramework.Binding/IMaaJob.cs | 42 ++++++ src/MaaFramework.Binding/MaaDef.cs | 39 +++++ 28 files changed, 468 insertions(+), 224 deletions(-) rename src/{MaaFramework.Binding => MaaFramework.Binding.Native}/Abstractions/MaaCommon.cs (54%) create mode 100644 src/MaaFramework.Binding/Abstractions/IMaaCommon.cs create mode 100644 src/MaaFramework.Binding/Abstractions/IMaaDefStruct.cs create mode 100644 src/MaaFramework.Binding/Abstractions/IMaaOption.cs delete mode 100644 src/MaaFramework.Binding/Enums/Binding/ConvertOption.cs create mode 100644 src/MaaFramework.Binding/Enums/Binding/FlagsEnumExtension.cs create mode 100644 src/MaaFramework.Binding/IMaaController.cs create mode 100644 src/MaaFramework.Binding/IMaaInstance.cs create mode 100644 src/MaaFramework.Binding/IMaaJob.cs create mode 100644 src/MaaFramework.Binding/MaaDef.cs diff --git a/README.md b/README.md index f60226d..54ac654 100644 --- a/README.md +++ b/README.md @@ -4,3 +4,67 @@ - [MBA](https://github.com/MaaAssistantArknights/MBA) BA 小助手 基于 MAA 全新架构的 BA 小助手。图像技术 + 模拟控制，解放双手，不再点点点！由 MaaFramework 强力驱动！ + +## Wiki + +对应版本 [v1.1.1](https://github.com/MaaAssistantArknights/MaaFramework/blob/v1.1.1) + +Binding wrapper 实现 与 Api 一览 + +### Enums + +| Wrapper | MaaDef | +| AdbControllerTypes | MaaAdbControllerTypeEnum | +| ControllerOption | MaaCtrlOptionEnum | +| DebuggingControllerTypes | MaaDebuggingControllerTypeEnum | +| GlobalOption | MaaGlobalOptionEnum | +| InstanceOption | MaaInstOptionEnum | +| MaaJobStatus | MaaStatusEnum | +| ResourceOption | MaaResOptionEnum | + +CheckStatusOption +DisposeOptions +LinkOption + +### IMaaCommon + +| IMaaCommon.Callback | Occurs when MaaFramework calls back. | + +### MaaJob + +| Wrapper | FFI API | +| IMaaJob.Status | MaaControllerStatus
MaaResourceStatus
MaaTaskStatus | +| IMaaJob.Wait() | MaaControllerWait
MaaResourceWait
MaaWaitTask | +| IMaaJob.SetParam() | MaaSetTaskParam | + +### MaaController + +| Wrapper | FFI API | +| MaaController.MaaController() | MaaAdbControllerCreateV2 | +| MaaCustomController.MaaCustomController() | MaaCustomControllerCreate | +| MaaThriftController.MaaThriftController() | MaaThriftControllerCreate | +| MaaDebuggingController.MaaDebuggingController() | MaaDebuggingControllerCreate | +| IDisposable.Dispose() | MaaControllerDestroy | +| IMaaOption.SetOption() | MaaControllerSetOption | +| IMaaController.LinkStart() | MaaControllerPostConnection | +| IMaaController.Click() | MaaControllerPostClick | +| IMaaController.Swipe() | MaaControllerPostSwipe | +| IMaaController.PressKey() | MaaControllerPostPressKey | +| IMaaController.TouchDown() | MaaControllerPostTouchDown | +| IMaaController.TouchMove() | MaaControllerPostTouchMove | +| IMaaController.TouchUp() | MaaControllerPostTouchUp | +| IMaaController.Screencap() | MaaControllerPostScreencap | +| IMaaPost.SetParam() | Always return false. | +| IMaaPost.GetStatus() | MaaControllerStatus | +| IMaaPost.Wait() | MaaControllerWait | +| IMaaController.LinkStop() | MaaControllerConnected | +| IMaaController.GetImage() | MaaControllerGetImage | +| IMaaController.Uuid | MaaControllerGetUUID | + +### MaaInstance + +| Wrapper | FFI API | +| MaaInstance.MaaInstance() | MaaCreate | + + +### Buffers diff --git a/src/MaaFramework.Binding/Abstractions/MaaCommon.cs b/src/MaaFramework.Binding.Native/Abstractions/MaaCommon.cs similarity index 54% rename from src/MaaFramework.Binding/Abstractions/MaaCommon.cs rename to src/MaaFramework.Binding.Native/Abstractions/MaaCommon.cs index a4e9750..7f9e212 100644 --- a/src/MaaFramework.Binding/Abstractions/MaaCommon.cs +++ b/src/MaaFramework.Binding.Native/Abstractions/MaaCommon.cs @@ -1,20 +1,14 @@ -using MaaFramework.Binding.Enums; -using MaaFramework.Binding.Interop.Framework; +using MaaFramework.Binding.Abstractions; +using MaaFramework.Binding.Native.Interop.Framework; using System.Runtime.InteropServices; -namespace MaaFramework.Binding.Abstractions; +namespace MaaFramework.Binding.Native.Abstractions; /// /// A abstract class providing common members for , and . /// -public abstract class MaaCommon : MaaOption, IMaaPost, IDisposable where T : Enum +public abstract class MaaCommon : MaaOption, IMaaCommon, IDisposable where TEnum : Enum { - /// - ~MaaCommon() - { - Dispose(false); - } - /// public void Dispose() { @@ -25,27 +19,13 @@ public void Dispose() /// protected abstract void Dispose(bool disposing); - /// - public abstract bool SetParam(MaaJob job, string param); - - /// - public abstract MaaJobStatus GetStatus(MaaJob job); - - /// - public abstract MaaJobStatus Wait(MaaJob job); - - /// - /// Maa Callback delegate. - /// - public delegate void MaaCallback(string msg, string detailsJson, MaaCallbackTransparentArg identifier); - /// /// Occurs when MaaFramework calls back. /// - public event MaaCallback? Callback; + public event EventHandler? Callback; /// - /// Raises the Startup event. + /// Raises the Callback event. /// /// /// @@ -55,22 +35,22 @@ public void Dispose() /// protected virtual void OnCallback(MaaStringView msg, MaaStringView detail, MaaCallbackTransparentArg arg) { - Callback?.Invoke( + Callback?.Invoke(this, new MaaCallbackEventArgs( Marshal.PtrToStringUTF8(msg) ?? string.Empty, Marshal.PtrToStringUTF8(detail) ?? "{}", - arg); + arg)); } /// /// A delegate to avoid garbage collection before MaaFramework calls . /// - internal readonly MaaApiCallback MaaApiCallback; + protected readonly MaaApiCallback maaApiCallback; /// - /// Initialize + /// Initialize . /// protected MaaCommon() { - MaaApiCallback = OnCallback; + maaApiCallback = OnCallback; } } diff --git a/src/MaaFramework.Binding.Native/Abstractions/MaaOption.cs b/src/MaaFramework.Binding.Native/Abstractions/MaaOption.cs index db1b1de..0adff4a 100644 --- a/src/MaaFramework.Binding.Native/Abstractions/MaaOption.cs +++ b/src/MaaFramework.Binding.Native/Abstractions/MaaOption.cs @@ -1,30 +1,26 @@ -using static MaaFramework.Binding.Native.Interop.MaaDefConverter; +using MaaFramework.Binding.Abstractions; +using static MaaFramework.Binding.Native.Interop.MaaDefConverter; namespace MaaFramework.Binding.Native.Abstractions; /// /// A abstract class providing common overloading members of SetOption method. /// -public abstract class MaaOption where T : Enum +public abstract class MaaOption : IMaaOption where T : Enum { - /// - /// Sets value to a option. - /// - /// The option. - /// The value. - /// true if the option was setted successfully; otherwise, false. + + /// internal abstract bool SetOption(T option, MaaOptionValue[] value); - /// + /// public bool SetOption(T option, int value) => SetOption(option, value.ToMaaOptionValues()); - /// + /// public bool SetOption(T option, bool value) => SetOption(option, value.ToMaaOptionValues()); - /// - /// + /// public bool SetOption(T option, string value) { ArgumentException.ThrowIfNullOrEmpty(value); diff --git a/src/MaaFramework.Binding.Native/Interop/Framework/MaaDef.cs b/src/MaaFramework.Binding.Native/Interop/Framework/MaaDef.cs index b5c4392..4dc609f 100644 --- a/src/MaaFramework.Binding.Native/Interop/Framework/MaaDef.cs +++ b/src/MaaFramework.Binding.Native/Interop/Framework/MaaDef.cs @@ -52,9 +52,6 @@ global using int32_t = System.Int32; -// Consider using SafeHandle -using System.Runtime.InteropServices; - #pragma warning disable S1133 // Deprecated code should be removed #pragma warning disable S4200 // Native methods should be wrapped #pragma warning disable CA1401 // P/Invoke method should not be visible @@ -80,17 +77,3 @@ public static class MaaDef } public delegate void MaaApiCallback(MaaStringView msg, MaaStringView details_json, MaaCallbackTransparentArg callback_arg); - -[StructLayout(LayoutKind.Sequential)] -public struct MaaRect : IMaaDefStruct -{ - public int32_t X; - public int32_t Y; - public int32_t Width; - public int32_t Height; -} - -public interface IMaaDefStruct -{ - -} diff --git a/src/MaaFramework.Binding.Native/Interop/Framework/Task/MaaCustomAction.cs b/src/MaaFramework.Binding.Native/Interop/Framework/Task/MaaCustomAction.cs index 8eebec7..8541827 100644 --- a/src/MaaFramework.Binding.Native/Interop/Framework/Task/MaaCustomAction.cs +++ b/src/MaaFramework.Binding.Native/Interop/Framework/Task/MaaCustomAction.cs @@ -1,5 +1,6 @@ using System.Runtime.InteropServices.Marshalling; using System.Runtime.InteropServices; +using MaaFramework.Binding.Abstractions; namespace MaaFramework.Binding.Native.Interop.Framework; diff --git a/src/MaaFramework.Binding.Native/Interop/Framework/Task/MaaCustomRecognizer.cs b/src/MaaFramework.Binding.Native/Interop/Framework/Task/MaaCustomRecognizer.cs index 26abea9..d92f9a1 100644 --- a/src/MaaFramework.Binding.Native/Interop/Framework/Task/MaaCustomRecognizer.cs +++ b/src/MaaFramework.Binding.Native/Interop/Framework/Task/MaaCustomRecognizer.cs @@ -1,5 +1,6 @@ using System.Runtime.InteropServices.Marshalling; using System.Runtime.InteropServices; +using MaaFramework.Binding.Abstractions; namespace MaaFramework.Binding.Native.Interop.Framework; diff --git a/src/MaaFramework.Binding.Native/MaaController.cs b/src/MaaFramework.Binding.Native/MaaController.cs index 496ef98..acc5a4b 100644 --- a/src/MaaFramework.Binding.Native/MaaController.cs +++ b/src/MaaFramework.Binding.Native/MaaController.cs @@ -1,16 +1,16 @@ -using MaaFramework.Binding.Abstractions; -using MaaFramework.Binding.Buffers; +using MaaFramework.Binding.Buffers; using MaaFramework.Binding.Enums; using MaaFramework.Binding.Exceptions; +using MaaFramework.Binding.Native.Abstractions; using MaaFramework.Binding.Native.Interop; using static MaaFramework.Binding.Native.Interop.Framework.MaaController; namespace MaaFramework.Binding; /// -/// A class providing a reference implementation for . +/// A wrapper class providing a reference implementation for . /// -public class MaaController : MaaCommon +public class MaaController : MaaCommon, IMaaController { internal MaaControllerHandle _handle; private bool disposed; @@ -57,17 +57,24 @@ public MaaController(string adbPath, string address, AdbControllerTypes type, st /// /// Wrapper of . /// + /// /// public MaaController(string adbPath, string address, AdbControllerTypes type, string adbConfig, string agentPath, MaaCallbackTransparentArg maaCallbackTransparentArg, CheckStatusOption check, LinkOption link) { - _handle = MaaAdbControllerCreateV2(adbPath, address, (int)type, adbConfig, agentPath, MaaApiCallback, maaCallbackTransparentArg); + ArgumentException.ThrowIfNullOrEmpty(adbPath); + ArgumentException.ThrowIfNullOrEmpty(address); + type.Check(); + ArgumentException.ThrowIfNullOrEmpty(adbConfig); + ArgumentException.ThrowIfNullOrEmpty(agentPath); + + _handle = MaaAdbControllerCreateV2(adbPath, address, (int)type, adbConfig, agentPath, maaApiCallback, maaCallbackTransparentArg); if (link == LinkOption.Start) { var status = LinkStart().Wait(); if (check == CheckStatusOption.ThrowIfNotSuccess) { - status.ThrowIfMaaControllerNotSuccess(); + status.ThrowIfNot(MaaJobStatus.Success, MaaJobStatusException.MaaControllerMessage); } } } @@ -97,174 +104,122 @@ protected override void Dispose(bool disposing) internal override bool SetOption(ControllerOption option, MaaOptionValue[] value) => MaaControllerSetOption(_handle, (MaaCtrlOption)option, ref value[0], (MaaOptionValueSize)value.Length).ToBoolean(); - /// - /// Connects the address specified by the constructor. - /// - /// A connection job. + /// /// /// Wrapper of . /// - public MaaJob LinkStart() + public IMaaJob LinkStart() { var id = MaaControllerPostConnection(_handle); - return new(id, this); + return new MaaJob(id, this); } - /// - /// Clicks a point. - /// - /// The horizontal coordinate of the point. - /// The vertical coordinate of the point. - /// A click job. + /// /// /// Wrapper of . /// - public MaaJob Click(int x, int y) + public IMaaJob Click(int x, int y) { var id = MaaControllerPostClick(_handle, x, y); - return new(id, this); + return new MaaJob(id, this); } - /// - /// Swipes from a starting point to a ending point with duration. - /// - /// The horizontal coordinate of the starting point. - /// The vertical coordinate of the starting point. - /// The horizontal coordinate of the ending point. - /// The horizontal coordinate of the ending point. - /// The duration. - /// A swipe job. + /// /// /// Wrapper of . /// - public MaaJob Swipe(int x1, int y1, int x2, int y2, int duration) + public IMaaJob Swipe(int x1, int y1, int x2, int y2, int duration) { var id = MaaControllerPostSwipe(_handle, x1, y1, x2, y2, duration); - return new(id, this); + return new MaaJob(id, this); } - /// - /// Presses a key. - /// - /// The code of the key. - /// A press key job. + /// /// /// Wrapper of . /// - public MaaJob PressKey(int keyCode) + public IMaaJob PressKey(int keyCode) { var id = MaaControllerPostPressKey(_handle, keyCode); - return new(id, this); + return new MaaJob(id, this); } - /// - /// Usage: TouchDown -> TouchMove -> TouchUp. - /// - /// The contact id. - /// The horizontal coordinate of the starting point. - /// The vertical coordinate of the starting point. - /// The pressure. - /// A touch down job. + /// /// /// Wrapper of . /// - public MaaJob TouchDown(int contact, int x, int y, int pressure) + public IMaaJob TouchDown(int contact, int x, int y, int pressure) { var id = MaaControllerPostTouchDown(_handle, contact, x, y, pressure); - return new(id, this); + return new MaaJob(id, this); } - /// - /// Usage: TouchDown -> TouchMove -> TouchUp. - /// - /// The contact id. - /// The horizontal coordinate of the ending point. - /// The vertical coordinate of the ending point. - /// The pressure. - /// A touch move job. + /// /// /// Wrapper of . /// - public MaaJob TouchMove(int contact, int x, int y, int pressure) + public IMaaJob TouchMove(int contact, int x, int y, int pressure) { var id = MaaControllerPostTouchMove(_handle, contact, x, y, pressure); - return new(id, this); + return new MaaJob(id, this); } - /// - /// Usage: TouchDown -> TouchMove -> TouchUp. - /// - /// The contact id. - /// A touch up job. + /// /// /// Wrapper of . /// - public MaaJob TouchUp(int contact) + public IMaaJob TouchUp(int contact) { var id = MaaControllerPostTouchUp(_handle, contact); - return new(id, this); + return new MaaJob(id, this); } - /// - /// Takes a screenshot. - /// - /// A screen capture job. + /// /// /// Wrapper of . /// - public MaaJob Screencap() + public IMaaJob Screencap() { var id = MaaControllerPostScreencap(_handle); - return new(id, this); + return new MaaJob(id, this); } /// /// /// Always return false. /// - public override bool SetParam(MaaJob job, string param) + public bool SetParam(IMaaJob job, string param) => false; /// /// /// Wrapper of . /// - public override MaaJobStatus GetStatus(MaaJob job) + public MaaJobStatus GetStatus(IMaaJob job) => (MaaJobStatus)MaaControllerStatus(_handle, job); /// /// /// Wrapper of . /// - public override MaaJobStatus Wait(MaaJob job) + public MaaJobStatus Wait(IMaaJob job) => (MaaJobStatus)MaaControllerWait(_handle, job); - /// - /// Ends the connection of the address specified by the constructor. - /// - /// true if the connection was ended successfully; otherwise, false. + /// /// /// Wrapper of . /// public bool LinkStop() => MaaControllerConnected(_handle).ToBoolean(); - /// - /// Gets a image. - /// - /// true if the image was got successfully; otherwise, false. + /// /// /// Wrapper of . /// - public bool GetImage(MaaImageBuffer maaImage) + public bool GetImage(IMaaImageBuffer maaImage) => MaaControllerGetImage(_handle, maaImage._handle).ToBoolean(); - /// - /// Gets the uuid string of the . - /// - /// - /// A string if the hash was successfully got; otherwise, null. - /// + /// /// /// Wrapper of . /// diff --git a/src/MaaFramework.Binding.Native/MaaCustomController.cs b/src/MaaFramework.Binding.Native/MaaCustomController.cs index 4416714..0656312 100644 --- a/src/MaaFramework.Binding.Native/MaaCustomController.cs +++ b/src/MaaFramework.Binding.Native/MaaCustomController.cs @@ -4,7 +4,7 @@ namespace MaaFramework.Binding; /// -/// A class providing a reference implementation for . +/// A wrapper class providing providing a reference implementation for . /// public class MaaCustomController : MaaController { diff --git a/src/MaaFramework.Binding.Native/MaaInstance.cs b/src/MaaFramework.Binding.Native/MaaInstance.cs index 86e528b..e7c47cf 100644 --- a/src/MaaFramework.Binding.Native/MaaInstance.cs +++ b/src/MaaFramework.Binding.Native/MaaInstance.cs @@ -1,6 +1,7 @@ using MaaFramework.Binding.Abstractions; using MaaFramework.Binding.Enums; using MaaFramework.Binding.Exceptions; +using MaaFramework.Binding.Native.Abstractions; using MaaFramework.Binding.Native.Interop; using MaaFramework.Binding.Native.Interop.Framework; using System.Diagnostics.CodeAnalysis; @@ -9,14 +10,14 @@ namespace MaaFramework.Binding; /// -/// A class providing a reference implementation for . +/// A wrapper class providing a reference implementation for . /// public class MaaInstance : MaaCommon { internal MaaInstanceHandle _handle; private bool disposed; - private MaaResource _resource = new(); - private MaaController _controller = new(); + private MaaResource _resource = default!; + private MaaController _controller = default!; /* 为 RPC 准备的 [SetsRequiredMembers] @@ -45,20 +46,27 @@ public MaaInstance() /// public MaaInstance(MaaCallbackTransparentArg maaCallbackTransparentArg) { - _handle = MaaCreate(MaaApiCallback, maaCallbackTransparentArg); + _handle = MaaCreate(maaApiCallback, maaCallbackTransparentArg); } /// The resource. /// The controller. + /// The dispose options. /// [SetsRequiredMembers] - public MaaInstance(MaaResource resource, MaaController controller) + public MaaInstance(MaaResource resource, MaaController controller, DisposeOptions disposeOptions) : this(MaaCallbackTransparentArg.Zero) { Resource = resource; Controller = controller; + DisposeOptions = disposeOptions; } + /// + /// Whether to dispose the and the when was invoked. + /// + public required DisposeOptions DisposeOptions { get; set; } + /// /// Disposes the instance. /// @@ -72,7 +80,9 @@ protected override void Dispose(bool disposing) { if (disposing) { - Controller.Dispose(); + DisposeOptions. + if (DisposeOptions.Contains(DisposeOptions.Resource)) + Controller.Dispose(); Resource.Dispose(); } @@ -100,14 +110,14 @@ public required MaaResource Resource { get { - MaaBindException.ThrowIfFalse( + MaaBindException.ThrowIf( MaaGetResource(_handle) != _resource!._handle, MaaBindException.ResourceModifiedMessage); return _resource; } init { - MaaBindException.ThrowIfFalse( + MaaBindException.ThrowIf( MaaBindResource(_handle, value._handle).ToBoolean(), MaaBindException.ResourceMessage); _resource = value; @@ -125,14 +135,14 @@ public required MaaController Controller { get { - MaaBindException.ThrowIfFalse( + MaaBindException.ThrowIf( MaaGetController(_handle) != _controller!._handle, MaaBindException.ControllerModifiedMessage); return _controller; } init { - MaaBindException.ThrowIfFalse( + MaaBindException.ThrowIf( MaaBindController(_handle, value._handle).ToBoolean(), MaaBindException.ControllerMessage); _controller = value; @@ -260,22 +270,22 @@ public MaaJob AppendTask(string taskEntryName, string taskParam = MaaDef.EmptyMa /// /// Wrapper of . /// - public override bool SetParam(MaaJob job, string param) - => MaaSetTaskParam(_handle, job, param).ToBoolean(); + public bool SetParam(MaaJob job, string param) + => MaaSetTaskParam(_handle, job.Id, param).ToBoolean(); /// /// /// Wrapper of . /// - public override MaaJobStatus GetStatus(MaaJob job) - => (MaaJobStatus)MaaTaskStatus(_handle, job); + public MaaJobStatus GetStatus(MaaJob job) + => (MaaJobStatus)MaaTaskStatus(_handle, job.Id); /// /// /// Wrapper of . /// - public override MaaJobStatus Wait(MaaJob job) - => (MaaJobStatus)MaaWaitTask(_handle, job); + public MaaJobStatus Wait(MaaJob job) + => (MaaJobStatus)MaaWaitTask(_handle, job.Id); /// /// Gets whether the all maa tasks finished. diff --git a/src/MaaFramework.Binding.Native/MaaJob.cs b/src/MaaFramework.Binding.Native/MaaJob.cs index 9d5360a..823b2da 100644 --- a/src/MaaFramework.Binding.Native/MaaJob.cs +++ b/src/MaaFramework.Binding.Native/MaaJob.cs @@ -4,48 +4,32 @@ namespace MaaFramework.Binding; /// -/// A class providing a reference implementation for return value of Maa Post method. +/// A wrapper class providing a reference implementation for return value of Maa Post method. /// -public class MaaJob +public class MaaJob : IMaaJob { - /// - /// - /// - /// - public static implicit operator MaaId(MaaJob job) => job._id; - - private readonly MaaId _id; private readonly IMaaPost _maa; /// - /// + /// Creats a instance. /// /// /// public MaaJob(MaaId id, IMaaPost maa) { - _id = id; + Id = id; _maa = maa; } - /// - /// Gets the status of the . - /// - /// - /// Calls . - /// + /// + public MaaId Id { get; } + + /// public MaaJobStatus Status => _maa.GetStatus(this); - /// - /// Calls . - /// - /// + /// public MaaJobStatus Wait() => _maa.Wait(this); - /// - /// Calls . - /// - /// - /// - public bool SetParam(string param) => _maa.SetParam(this, param); + /// + public bool SetParam(string parameters) => _maa.SetParam(this, parameters); } diff --git a/src/MaaFramework.Binding.Native/MaaResource.cs b/src/MaaFramework.Binding.Native/MaaResource.cs index e30c67c..603f850 100644 --- a/src/MaaFramework.Binding.Native/MaaResource.cs +++ b/src/MaaFramework.Binding.Native/MaaResource.cs @@ -1,14 +1,14 @@ -using MaaFramework.Binding.Abstractions; -using MaaFramework.Binding.Buffers; +using MaaFramework.Binding.Buffers; using MaaFramework.Binding.Enums; using MaaFramework.Binding.Exceptions; +using MaaFramework.Binding.Native.Abstractions; using MaaFramework.Binding.Native.Interop; using static MaaFramework.Binding.Native.Interop.Framework.MaaResource; namespace MaaFramework.Binding; /// -/// A class providing a reference implementation for . +/// A wrapper class providing a reference implementation for . /// public class MaaResource : MaaCommon { diff --git a/src/MaaFramework.Binding.Native/MaaSyncContext.cs b/src/MaaFramework.Binding.Native/MaaSyncContext.cs index d9b3b55..1ff919b 100644 --- a/src/MaaFramework.Binding.Native/MaaSyncContext.cs +++ b/src/MaaFramework.Binding.Native/MaaSyncContext.cs @@ -6,7 +6,7 @@ namespace MaaFramework.Binding; /// -/// A class providing a reference implementation for . +/// A wrapper class providing a reference implementation for . /// public class MaaSyncContext { diff --git a/src/MaaFramework.Binding.Native/MaaThriftController.cs b/src/MaaFramework.Binding.Native/MaaThriftController.cs index 499a244..aebd5b3 100644 --- a/src/MaaFramework.Binding.Native/MaaThriftController.cs +++ b/src/MaaFramework.Binding.Native/MaaThriftController.cs @@ -3,7 +3,7 @@ namespace MaaFramework.Binding; /// -/// A class providing a reference implementation for . +/// A wrapper class providing a reference implementation for . /// public class MaaThriftController : MaaController { diff --git a/src/MaaFramework.Binding.Native/MaaToolKit.cs b/src/MaaFramework.Binding.Native/MaaToolKit.cs index 6c224b8..788eb8c 100644 --- a/src/MaaFramework.Binding.Native/MaaToolKit.cs +++ b/src/MaaFramework.Binding.Native/MaaToolKit.cs @@ -6,7 +6,7 @@ namespace MaaFramework.Binding; /// -/// A static class providing a reference implementation for . +/// A static wrapper class providing a reference implementation for . /// public static class MaaToolKit { diff --git a/src/MaaFramework.Binding.Native/MaaUtility.cs b/src/MaaFramework.Binding.Native/MaaUtility.cs index 4c8d703..5c0b89c 100644 --- a/src/MaaFramework.Binding.Native/MaaUtility.cs +++ b/src/MaaFramework.Binding.Native/MaaUtility.cs @@ -5,7 +5,7 @@ namespace MaaFramework.Binding; /// -/// A static class providing a reference implementation for . +/// A static wrapper class providing a reference implementation for . /// public static class MaaUtility { diff --git a/src/MaaFramework.Binding/Abstractions/IMaaCommon.cs b/src/MaaFramework.Binding/Abstractions/IMaaCommon.cs new file mode 100644 index 0000000..3c6eee4 --- /dev/null +++ b/src/MaaFramework.Binding/Abstractions/IMaaCommon.cs @@ -0,0 +1,12 @@ +namespace MaaFramework.Binding.Abstractions; + +/// +/// An interface defining members that do not interoperate with . +/// +public interface IMaaCommon +{ + /// + /// Occurs when MaaFramework calls back. + /// + event EventHandler? Callback; +} diff --git a/src/MaaFramework.Binding/Abstractions/IMaaDefStruct.cs b/src/MaaFramework.Binding/Abstractions/IMaaDefStruct.cs new file mode 100644 index 0000000..895e75f --- /dev/null +++ b/src/MaaFramework.Binding/Abstractions/IMaaDefStruct.cs @@ -0,0 +1,8 @@ +namespace MaaFramework.Binding.Abstractions; + +/// +/// An interface representing a MaaDef structure. +/// +public interface IMaaDefStruct +{ +} diff --git a/src/MaaFramework.Binding/Abstractions/IMaaOption.cs b/src/MaaFramework.Binding/Abstractions/IMaaOption.cs new file mode 100644 index 0000000..57ca400 --- /dev/null +++ b/src/MaaFramework.Binding/Abstractions/IMaaOption.cs @@ -0,0 +1,22 @@ +namespace MaaFramework.Binding.Abstractions; + +/// +/// An interface defining methods that set options for . +/// +public interface IMaaOption where T : Enum +{ + /// + /// Sets value to a option. + /// + /// The option. + /// The value. + /// true if the option was setted successfully; otherwise, false. + bool SetOption(T option, int value); + + /// + bool SetOption(T option, bool value); + + /// + /// + bool SetOption(T option, string value); +} diff --git a/src/MaaFramework.Binding/Abstractions/IMaaPost.cs b/src/MaaFramework.Binding/Abstractions/IMaaPost.cs index 7a36ee2..bee24e5 100644 --- a/src/MaaFramework.Binding/Abstractions/IMaaPost.cs +++ b/src/MaaFramework.Binding/Abstractions/IMaaPost.cs @@ -3,29 +3,29 @@ namespace MaaFramework.Binding.Abstractions; /// -/// A interface of Maa post method. +/// An interface defining methods that use the returned by the post methods. /// public interface IMaaPost { /// - /// Sets of a . + /// Sets of a . /// /// The MaaJob. /// The param, which could be parsed to a JSON. /// true if the were setted successfully in the ; otherwise, false. - bool SetParam(MaaJob job, string param); + bool SetParam(IMaaJob job, string param); /// - /// Gets the current status of a . + /// Gets the current status of a . /// /// The MaaJob. /// The status of . - MaaJobStatus GetStatus(MaaJob job); + MaaJobStatus GetStatus(IMaaJob job); /// - /// Waits a . + /// Waits a . /// /// The MaaJob. /// The status at the end of the . - MaaJobStatus Wait(MaaJob job); + MaaJobStatus Wait(IMaaJob job); } diff --git a/src/MaaFramework.Binding/Enums/Binding/ConvertOption.cs b/src/MaaFramework.Binding/Enums/Binding/ConvertOption.cs deleted file mode 100644 index 50a5d40..0000000 --- a/src/MaaFramework.Binding/Enums/Binding/ConvertOption.cs +++ /dev/null @@ -1,6 +0,0 @@ -namespace MaaFramework.Binding.Enums; - -internal enum ConvertOption -{ - Convert, -} diff --git a/src/MaaFramework.Binding/Enums/Binding/DisposeOptions.cs b/src/MaaFramework.Binding/Enums/Binding/DisposeOptions.cs index 506de20..158dbfb 100644 --- a/src/MaaFramework.Binding/Enums/Binding/DisposeOptions.cs +++ b/src/MaaFramework.Binding/Enums/Binding/DisposeOptions.cs @@ -1,7 +1,7 @@ namespace MaaFramework.Binding.Enums; /// -/// dispose options. +/// dispose options. /// /// [Flags] diff --git a/src/MaaFramework.Binding/Enums/Binding/FlagsEnumExtension.cs b/src/MaaFramework.Binding/Enums/Binding/FlagsEnumExtension.cs new file mode 100644 index 0000000..e3697b3 --- /dev/null +++ b/src/MaaFramework.Binding/Enums/Binding/FlagsEnumExtension.cs @@ -0,0 +1,46 @@ +using MaaFramework.Binding.Exceptions; + +namespace MaaFramework.Binding.Enums; + +/// +/// A static class adding extensional methods to FlagsEnum. +/// +public static class FlagsEnumExtension +{ + /// + /// Whether a flags enum contains another flags enum. + /// + /// The flags enum. + /// The another flags enum. + /// true if the flags enum contains the another flags enum; otherwise, false. + public static bool Contains(this DisposeOptions flagsEnum, DisposeOptions containedEnum) + => (flagsEnum & containedEnum) == containedEnum; + + /// + public static bool Contains(this AdbControllerTypes flagsEnum, AdbControllerTypes containedEnum) + => (flagsEnum & containedEnum) == containedEnum; + + /// + public static bool Contains(this DebuggingControllerTypes flagsEnum, DebuggingControllerTypes containedEnum) + => (flagsEnum & containedEnum) == containedEnum; + + /// + /// Whether a flags enum contains all necessary enumeration value. + /// + /// The flags enum. + /// Throw a MaaException if not all inclusive. + public static void Check(this AdbControllerTypes flagsEnum) + { + if ((flagsEnum & AdbControllerTypes.TouchMask) == AdbControllerTypes.Invalid) + throw new ArgumentException($"This types ({flagsEnum}) missing Touch type will cause {nameof(IMaaController.LinkStart)} failure."); + if ((flagsEnum & AdbControllerTypes.KeyMask) == AdbControllerTypes.Invalid) + throw new MaaException($"This types ({flagsEnum}) missing Key type will cause {nameof(IMaaController.LinkStart)} failure."); + if ((flagsEnum & AdbControllerTypes.ScreenCapMask) == AdbControllerTypes.Invalid) + throw new MaaException($"This types ({flagsEnum}) missing ScreenCap type will cause {nameof(IMaaController.LinkStart)} failure."); + } + + public static void Check(this DebuggingControllerTypes flagsEnum) + { + throw new NotImplementedException(); + } +} diff --git a/src/MaaFramework.Binding/Enums/Binding/LinkOption.cs b/src/MaaFramework.Binding/Enums/Binding/LinkOption.cs index 40c5650..3ffac7f 100644 --- a/src/MaaFramework.Binding/Enums/Binding/LinkOption.cs +++ b/src/MaaFramework.Binding/Enums/Binding/LinkOption.cs @@ -1,7 +1,7 @@ namespace MaaFramework.Binding.Enums; /// -/// link option. +/// link option. /// public enum LinkOption { diff --git a/src/MaaFramework.Binding/Exceptions/MaaJobStatusException.cs b/src/MaaFramework.Binding/Exceptions/MaaJobStatusException.cs index 459c878..1d62fce 100644 --- a/src/MaaFramework.Binding/Exceptions/MaaJobStatusException.cs +++ b/src/MaaFramework.Binding/Exceptions/MaaJobStatusException.cs @@ -3,22 +3,22 @@ namespace MaaFramework.Binding.Exceptions; /// -/// The exception is thrown when the of a is incorrect. +/// The exception is thrown when the of a is incorrect. /// public class MaaJobStatusException : MaaException { /// /// Maa controller message. /// - public const string MaaControllerMessage = $"{nameof(MaaController)} failed to connect to the device."; + public const string MaaControllerMessage = $"{nameof(IMaaController)} failed to connect to the device."; /// /// Maa resource message. /// - public const string MaaResourceMessage = $"{nameof(MaaResource)} failed to load resources."; + public const string MaaResourceMessage = $"{nameof(IMaaResource)} failed to load resources."; /// - /// The exception is thrown when a fails to bind a or a . + /// The exception is thrown when a is unexpected. /// public MaaJobStatusException(string message = "MaaJobStatus was unexpected.") : base(message) { @@ -35,7 +35,7 @@ public MaaJobStatusException(MaaJobStatus status, string message = "") /// /// /// - public MaaJobStatusException(MaaJob job, string message = "") + public MaaJobStatusException(IMaaJob job, string message = "") : this(string.IsNullOrEmpty(message) ? $"MaaJobStatus cannot be {job.Status}." : $"{message} MaaJobStatus cannot be {job.Status}.") { } @@ -51,10 +51,11 @@ public static class MaaJobStatusThrow /// /// The current status. /// The incorrect status. + /// The message. /// - public static void ThrowIf(this MaaJobStatus current, MaaJobStatus incorrect) + public static void ThrowIf(this MaaJobStatus current, MaaJobStatus incorrect, string message = "") { - if (current == incorrect) throw new MaaJobStatusException(current); + if (current == incorrect) throw new MaaJobStatusException(current, message); } /// @@ -62,9 +63,10 @@ public static void ThrowIf(this MaaJobStatus current, MaaJobStatus incorrect) /// /// The current status. /// The correct status. + /// The message. /// - public static void ThrowIfNot(this MaaJobStatus current, MaaJobStatus correct) + public static void ThrowIfNot(this MaaJobStatus current, MaaJobStatus correct, string message = "") { - if (current != correct) throw new MaaJobStatusException(current); + if (current != correct) throw new MaaJobStatusException(current, message); } } diff --git a/src/MaaFramework.Binding/IMaaController.cs b/src/MaaFramework.Binding/IMaaController.cs new file mode 100644 index 0000000..21ac4b7 --- /dev/null +++ b/src/MaaFramework.Binding/IMaaController.cs @@ -0,0 +1,94 @@ +using MaaFramework.Binding.Abstractions; + +namespace MaaFramework.Binding; + +/// +/// An interface defining wrapped members for MaaController. +/// +public interface IMaaController : IMaaPost +{ + /// + /// Connects the address specified by the constructor. + /// + /// A connection job. + IMaaJob LinkStart(); + + /// + /// Clicks a point. + /// + /// The horizontal coordinate of the point. + /// The vertical coordinate of the point. + /// A click job. + IMaaJob Click(int x, int y); + + /// + /// Swipes from a starting point to a ending point with duration. + /// + /// The horizontal coordinate of the starting point. + /// The vertical coordinate of the starting point. + /// The horizontal coordinate of the ending point. + /// The horizontal coordinate of the ending point. + /// The duration. + /// A swipe job. + IMaaJob Swipe(int x1, int y1, int x2, int y2, int duration); + + /// + /// Presses a key. + /// + /// The code of the key. + /// A press key job. + IMaaJob PressKey(int keyCode); + + /// + /// Usage: TouchDown -> TouchMove -> TouchUp. + /// + /// The contact id. + /// The horizontal coordinate of the starting point. + /// The vertical coordinate of the starting point. + /// The pressure. + /// A touch down job. + IMaaJob TouchDown(int contact, int x, int y, int pressure); + + /// + /// Usage: TouchDown -> TouchMove -> TouchUp. + /// + /// The contact id. + /// The horizontal coordinate of the ending point. + /// The vertical coordinate of the ending point. + /// The pressure. + /// A touch move job. + IMaaJob TouchMove(int contact, int x, int y, int pressure); + + /// + /// Usage: TouchDown -> TouchMove -> TouchUp. + /// + /// The contact id. + /// A touch up job. + IMaaJob TouchUp(int contact); + + /// + /// Takes a screenshot. + /// + /// A screen capture job. + IMaaJob Screencap(); + + /// + /// Ends the connection of the address specified by the constructor. + /// + /// true if the connection was ended successfully; otherwise, false. + bool LinkStop(); + + /// + /// Gets a image. + /// + /// true if the image was got successfully; otherwise, false. + bool GetImage(IMaaImageBuffer maaImage); + + /// + /// Gets the uuid string of the . + /// + /// + /// A string if the hash was successfully got; otherwise, null. + /// + string? Uuid { get; } +} diff --git a/src/MaaFramework.Binding/IMaaInstance.cs b/src/MaaFramework.Binding/IMaaInstance.cs new file mode 100644 index 0000000..2559f2e --- /dev/null +++ b/src/MaaFramework.Binding/IMaaInstance.cs @@ -0,0 +1,11 @@ +using MaaFramework.Binding.Abstractions; + +namespace MaaFramework.Binding; + +/// +/// An interface defining wrapped members for MaaInstance. +/// +public interface IMaaInstance : IMaaPost +{ + +} diff --git a/src/MaaFramework.Binding/IMaaJob.cs b/src/MaaFramework.Binding/IMaaJob.cs new file mode 100644 index 0000000..1fb2886 --- /dev/null +++ b/src/MaaFramework.Binding/IMaaJob.cs @@ -0,0 +1,42 @@ +using MaaFramework.Binding.Abstractions; +using MaaFramework.Binding.Enums; + +namespace MaaFramework.Binding; + +/// +/// An interface representing a MaaJob that wrapping a MaaId and methods to invoke MaaId. +/// +public interface IMaaJob +{ + /// + /// Gets a MaaId. + /// + MaaId Id { get; } + + /// + /// Gets the status of a . + /// + /// + /// Calls . + /// + MaaJobStatus Status { get; } + + /// + /// Waits for a to complete. + /// + /// The job status. + /// + /// Calls . + /// + MaaJobStatus Wait(); + + /// + /// Sets the parameters of a . + /// + /// The parameters. + /// true if the parameters was setted successfully; otherwise, false. + /// + /// Calls . + /// + bool SetParam(string parameters); +} diff --git a/src/MaaFramework.Binding/MaaDef.cs b/src/MaaFramework.Binding/MaaDef.cs new file mode 100644 index 0000000..68b9026 --- /dev/null +++ b/src/MaaFramework.Binding/MaaDef.cs @@ -0,0 +1,39 @@ +// Some necessary maa definitions for abstractions in MaaFramework.Binding. +global using MaaId = System.Int64; + +namespace MaaFramework.Binding; + +/// +/// A class provides data for the event. +/// +public class MaaCallbackEventArgs : EventArgs +{ + /// + /// Maa callback message. + /// + public string Message { get; } + + + /// + /// Maa callback details json. + /// + public string Details { get; } + + /// + /// MaaCallbackTransparentArg. + /// + public nint Arg { get; } + + /// + /// Creates a instance. + /// + /// The callback message. + /// The callback details json. + /// The MaaCallbackTransparentArg. + public MaaCallbackEventArgs(string message, string details, nint arg) + { + Message = message; + Details = details; + Arg = arg; + } +}