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

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

public interface IMxAccessServer
{
    /// <summary>Registers a client and returns a server handle.</summary>
    /// <param name="clientName">Name of the client requesting registration.</param>
    /// <returns>Server handle for subsequent operations.</returns>
    int Register(string clientName);

    /// <summary>Unregisters a server handle.</summary>
    /// <param name="serverHandle">Server handle to unregister.</param>
    void Unregister(int serverHandle);

    /// <summary>Adds an item to a server and returns an item handle.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemDefinition">Item definition string.</param>
    /// <returns>Item handle for the added item.</returns>
    int AddItem(
        int serverHandle,
        string itemDefinition);

    /// <summary>Adds an item with context to a server and returns an item handle.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemDefinition">Item definition string.</param>
    /// <param name="itemContext">Item context string.</param>
    /// <returns>Item handle for the added item.</returns>
    int AddItem2(
        int serverHandle,
        string itemDefinition,
        string itemContext);

    /// <summary>Removes an item from a server.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to remove.</param>
    void RemoveItem(
        int serverHandle,
        int itemHandle);

    /// <summary>Subscribes to change notifications for an item.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to subscribe to.</param>
    void Advise(
        int serverHandle,
        int itemHandle);

    /// <summary>Unsubscribes from change notifications for an item.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to unsubscribe from.</param>
    void UnAdvise(
        int serverHandle,
        int itemHandle);

    /// <summary>Subscribes to supervisory change notifications for an item.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to subscribe to.</param>
    void AdviseSupervisory(
        int serverHandle,
        int itemHandle);

    /// <summary>Suspends data acquisition for an advised item (ILMXProxyServer4).</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to suspend.</param>
    /// <returns>
    /// The native MXAccess <c>MxStatus</c> value (boxed) produced by the call.
    /// Callers convert it to a protobuf <c>MxStatusProxy</c> via the worker's
    /// status converter; the underlying type is reflected over, not cast.
    /// </returns>
    object Suspend(
        int serverHandle,
        int itemHandle);

    /// <summary>Reactivates data acquisition for a suspended item (ILMXProxyServer4).</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to activate.</param>
    /// <returns>
    /// The native MXAccess <c>MxStatus</c> value (boxed) produced by the call.
    /// Callers convert it to a protobuf <c>MxStatusProxy</c> via the worker's
    /// status converter; the underlying type is reflected over, not cast.
    /// </returns>
    object Activate(
        int serverHandle,
        int itemHandle);

    /// <summary>Authenticates an MXAccess user and returns its user id (base ILMXProxyServer).</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="verifyUser">MXAccess user name to authenticate.</param>
    /// <param name="verifyUserPassword">
    /// Raw MXAccess credential. Implementations must keep this value out of
    /// logs, metrics, command lines, and diagnostics.
    /// </param>
    /// <returns>The MXAccess user id for the authenticated user.</returns>
    int AuthenticateUser(
        int serverHandle,
        string verifyUser,
        string verifyUserPassword);

    /// <summary>Resolves an ArchestrA user GUID to an MXAccess user id (ILMXProxyServer2).</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="userIdGuid">ArchestrA user GUID to resolve.</param>
    /// <returns>The MXAccess user id for the resolved user.</returns>
    int ArchestrAUserToId(
        int serverHandle,
        string userIdGuid);

    /// <summary>Adds a buffered item to a server and returns an item handle (ILMXProxyServer5).</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemDefinition">Item definition string.</param>
    /// <param name="itemContext">Item context string.</param>
    /// <returns>Item handle for the added buffered item.</returns>
    int AddBufferedItem(
        int serverHandle,
        string itemDefinition,
        string itemContext);

    /// <summary>Sets the buffered-update interval for a server (ILMXProxyServer5).</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="updateIntervalMilliseconds">Buffered update interval in milliseconds.</param>
    void SetBufferedUpdateInterval(
        int serverHandle,
        int updateIntervalMilliseconds);

    /// <summary>Writes a value to an item.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to write to.</param>
    /// <param name="value">COM-marshalable value to write; <see langword="null"/> writes an MXAccess null.</param>
    /// <param name="userId">MXAccess user id (security classification) for the write.</param>
    void Write(
        int serverHandle,
        int itemHandle,
        object? value,
        int userId);

    /// <summary>Writes a value with an explicit source timestamp to an item.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to write to.</param>
    /// <param name="value">COM-marshalable value to write; <see langword="null"/> writes an MXAccess null.</param>
    /// <param name="timestamp">COM-marshalable source timestamp for the write.</param>
    /// <param name="userId">MXAccess user id (security classification) for the write.</param>
    void Write2(
        int serverHandle,
        int itemHandle,
        object? value,
        object? timestamp,
        int userId);

    /// <summary>Performs a secured/verified write to an item.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to write to.</param>
    /// <param name="currentUserId">MXAccess user id of the operator performing the write.</param>
    /// <param name="verifierUserId">MXAccess user id of the verifier authorizing the write.</param>
    /// <param name="value">COM-marshalable value to write; <see langword="null"/> writes an MXAccess null.</param>
    void WriteSecured(
        int serverHandle,
        int itemHandle,
        int currentUserId,
        int verifierUserId,
        object? value);

    /// <summary>Performs a secured/verified write with an explicit source timestamp.</summary>
    /// <param name="serverHandle">Server handle identifying the registration.</param>
    /// <param name="itemHandle">Item handle to write to.</param>
    /// <param name="currentUserId">MXAccess user id of the operator performing the write.</param>
    /// <param name="verifierUserId">MXAccess user id of the verifier authorizing the write.</param>
    /// <param name="value">COM-marshalable value to write; <see langword="null"/> writes an MXAccess null.</param>
    /// <param name="timestamp">COM-marshalable source timestamp for the write.</param>
    void WriteSecured2(
        int serverHandle,
        int itemHandle,
        int currentUserId,
        int verifierUserId,
        object? value,
        object? timestamp);
}