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>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);
}