mxaccessgw/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/AaManagedAlarmAckConsumer.cs

using System;
using System.IO;
using System.Reflection;
using WNWRAPCONSUMERLib;

namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;

/// <summary>
///     Acknowledge path over AVEVA's modern managed alarm client,
///     <c>aaAlarmManagedClient.AlarmClient</c> (the C++/CLI assembly the AVEVA
///     Alarm Control itself uses: <c>AlarmClient → CwwAlarmConsumer →
///     alarmlst.dll → alarmmgr.exe</c>). Preferred over a hand-rolled native
///     WNAL consumer because <c>AlarmAckByGUID</c> performs the
///     register → match-by-GUID → submit sequence internally — the record
///     layout and selection semantics that are provider-defined (and therefore
///     NOT safely recoverable by static RE of alarmlst.dll) stay inside AVEVA's
///     own code. See <see cref="WnalNativeAckConsumer"/> for why the native
///     acquisition path is deliberately unfinished.
///
///     The <c>AlarmClient</c> members are <c>famorasm</c> (protected-internal)
///     and mxaccessgw is not an <c>InternalsVisibleTo</c> friend, so everything
///     here is invoked by reflection. In full-trust .NET Framework 4.8 that is
///     permitted. Method shapes are confirmed from the assembly metadata:
///       .ctor()                                                   (internal)
///       int InitializeConsumer(string appName)
///       int RegisterConsumer(int hWnd, string product, string app, string version, bool)
///       int Subscribe(string expr, short fromPri, short toPri,
///                     localQueryType, localSortFlags,
///                     localAlarmFilterState mask, localAlarmFilterState spec)
///       int AlarmAckByGUID(System.Guid guid, string comment, string oper,
///                          string node, string domain, string fullName)
///       int DeregisterConsumer()  /  int UninitializeConsumer()  /  Dispose()
///
///     THREADING: the underlying consumer is apartment-affine (same as the
///     wnwrap COM path). Construct and call this only on the worker STA
///     (marshal via <c>StaRuntime.InvokeAsync</c>).
///
///     x86 ONLY — aaAlarmManagedClient.dll is a 32-bit mixed-mode PE.
///
///     OPEN (confirm at runtime, flagged inline): the trailing <c>bool</c> of
///     <c>RegisterConsumer</c> (passed <c>false</c> here); whether
///     <c>Subscribe</c> is actually required before an ack by GUID; and the
///     native status returned on a real secured ack.
/// </summary>
public sealed class AaManagedAlarmAckConsumer : IManagedAlarmAckClient
{
    /// <summary>Default install location of the managed alarm client (eac.dll folder).</summary>
    public const string DefaultAssemblyPath =
        @"C:\Program Files (x86)\ArchestrA\Framework\Bin\Invensys_Systems__Inc__eac.dll\aaAlarmManagedClient.dll";

    /// <summary>
    ///     Env var that opts the worker into the managed ack path. Unset/anything
    ///     other than "1" keeps the existing wnwrap ack behavior.
    /// </summary>
    public const string EnableEnvVar = "MXGATEWAY_USE_MANAGED_ALARM_ACK";

    private const string AckApplicationName = "ZB.MOM.WW.MxGateway.ack";

    /// <summary>
    ///     Production factory for the <see cref="AlarmCommandHandler"/> seam:
    ///     returns a managed ack client only when <see cref="EnableEnvVar"/> == "1",
    ///     otherwise <see langword="null"/> (ack stays on the wnwrap path). Never
    ///     throws — a construction failure (missing DLL, etc.) degrades to the
    ///     wnwrap path rather than breaking the alarm subscription.
    /// </summary>
    public static IManagedAlarmAckClient? EnvGatedFactory()
    {
        if (!string.Equals(Environment.GetEnvironmentVariable(EnableEnvVar), "1", StringComparison.Ordinal))
            return null;
        try
        {
            return new AaManagedAlarmAckConsumer(AckApplicationName);
        }
        catch
        {
            // Opt-in enhancement only: if the managed client can't load, fall
            // back to the wnwrap ack path rather than failing alarm reads.
            return null;
        }
    }

    private const string TypeName = "aaAlarmManagedClient.AlarmClient";
    private const BindingFlags Inst = BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic;

    private readonly object syncRoot = new();
    private readonly object client;
    private readonly MethodInfo initializeConsumer;
    private readonly MethodInfo registerConsumer;
    private readonly MethodInfo subscribe;
    private readonly MethodInfo alarmAckByGuid;
    private readonly MethodInfo? deregisterConsumer;
    private readonly MethodInfo? uninitializeConsumer;

    private bool subscribed;
    private bool disposed;

    /// <param name="applicationName">Consumer application name (e.g. "MxGateway.ack").</param>
    /// <param name="assemblyPath">Override for <see cref="DefaultAssemblyPath"/>.</param>
    public AaManagedAlarmAckConsumer(string applicationName, string? assemblyPath = null)
    {
        if (string.IsNullOrWhiteSpace(applicationName))
            throw new ArgumentException("Application name is required.", nameof(applicationName));

        string path = assemblyPath ?? DefaultAssemblyPath;
        if (!File.Exists(path))
            throw new FileNotFoundException($"aaAlarmManagedClient.dll not found at '{path}'.", path);

        Assembly asm = Assembly.LoadFrom(path);
        Type type = asm.GetType(TypeName, throwOnError: true)
            ?? throw new InvalidOperationException($"Type '{TypeName}' not found in {path}.");

        initializeConsumer = Resolve(type, "InitializeConsumer");
        registerConsumer = Resolve(type, "RegisterConsumer");
        subscribe = Resolve(type, "Subscribe");
        alarmAckByGuid = Resolve(type, "AlarmAckByGUID");
        deregisterConsumer = type.GetMethod("DeregisterConsumer", Inst, null, Type.EmptyTypes, null);
        uninitializeConsumer = type.GetMethod("UninitializeConsumer", Inst, null, Type.EmptyTypes, null);

        client = Activator.CreateInstance(type, nonPublic: true)
            ?? throw new InvalidOperationException($"Could not construct '{TypeName}'.");

        ApplicationName = applicationName;
    }

    /// <summary>The consumer application name this instance registered under.</summary>
    public string ApplicationName { get; }

    private static MethodInfo Resolve(Type type, string name) =>
        type.GetMethod(name, Inst)
        ?? throw new MissingMethodException(TypeName, name);

    /// <summary>
    ///     Run the Initialize → Register → Subscribe lifecycle once, mirroring the
    ///     proven wnwrap argument values. <paramref name="subscription"/> is the
    ///     alarm query root, e.g. <c>\\NODE\Galaxy!Area</c>. Throws if any native
    ///     status is non-zero.
    /// </summary>
    public void Subscribe(string subscription)
    {
        if (subscription is null) throw new ArgumentNullException(nameof(subscription));
        lock (syncRoot)
        {
            if (disposed) throw new ObjectDisposedException(nameof(AaManagedAlarmAckConsumer));
            if (subscribed) throw new InvalidOperationException("Subscribe was already called.");

            int init = (int)initializeConsumer.Invoke(client, new object[] { ApplicationName })!;
            if (init != 0) throw new InvalidOperationException($"InitializeConsumer returned {init}.");

            // RegisterConsumer(hWnd, product, app, version, bool). hWnd=0 => pull model.
            // The trailing bool is unconfirmed; false = client/non-modal is the safe default.
            int reg = (int)registerConsumer.Invoke(client, new object[]
            {
                0, "ZB.MOM.WW.MxGateway", ApplicationName, "1.0", false,
            })!;
            if (reg != 0) throw new InvalidOperationException($"RegisterConsumer returned {reg}.");

            int sub = (int)subscribe.Invoke(client, BuildSubscribeArgs(subscription))!;
            if (sub != 0) throw new InvalidOperationException($"Subscribe('{subscription}') returned {sub}.");

            subscribed = true;
        }
    }

    /// <summary>
    ///     Acknowledge a single alarm by GUID with full operator identity. Returns
    ///     AVEVA's native status (0 = success). A zero return means accepted, not
    ///     necessarily applied — verify the alarm's acked state / Historian row
    ///     (see docs/AlarmProbeFindings.md).
    /// </summary>
    public int AcknowledgeByGuid(
        Guid alarmGuid,
        string comment,
        string operatorName,
        string operatorNode,
        string operatorDomain,
        string operatorFullName)
    {
        lock (syncRoot)
        {
            if (disposed) throw new ObjectDisposedException(nameof(AaManagedAlarmAckConsumer));
            if (!subscribed) throw new InvalidOperationException("Subscribe must be called before acknowledging.");

            return (int)alarmAckByGuid.Invoke(client, new object[]
            {
                alarmGuid,
                comment ?? string.Empty,
                operatorName ?? string.Empty,
                operatorNode ?? string.Empty,
                operatorDomain ?? string.Empty,
                operatorFullName ?? string.Empty,
            })!;
        }
    }

    /// <summary>
    ///     Build the 7 Subscribe args, boxing the proven wnwrap enum integers into
    ///     aaAlarmManagedClient's own enum parameter types (localQueryType /
    ///     localSortFlags / localAlarmFilterState) via <see cref="Enum.ToObject(Type,object)"/>.
    /// </summary>
    private object[] BuildSubscribeArgs(string subscription)
    {
        ParameterInfo[] p = subscribe.GetParameters();
        if (p.Length != 7)
            throw new InvalidOperationException($"Unexpected AlarmClient.Subscribe arity {p.Length}; expected 7.");

        return new object[]
        {
            subscription,
            (short)1,                                                        // wFromPri
            (short)999,                                                      // wToPri
            Enum.ToObject(p[3].ParameterType, (int)eQueryType.qtSummary),
            Enum.ToObject(p[4].ParameterType, (int)eSortFlags.sfReturnNewestFirst),
            Enum.ToObject(p[5].ParameterType, (int)eAlarmFilterState.asAlarmActiveNow),
            Enum.ToObject(p[6].ParameterType, (int)eAlarmFilterState.asAlarmActiveNow),
        };
    }

    /// <inheritdoc />
    public void Dispose()
    {
        lock (syncRoot)
        {
            if (disposed) return;
            disposed = true;

            try { if (subscribed) deregisterConsumer?.Invoke(client, Array.Empty<object>()); } catch { /* best effort */ }
            try { uninitializeConsumer?.Invoke(client, Array.Empty<object>()); } catch { /* best effort */ }
            (client as IDisposable)?.Dispose();
        }
    }
}