/* ========================================================================
* Copyright (c) 2005-2025 The OPC Foundation, Inc. All rights reserved.
*
* OPC Foundation MIT License 1.00
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use,
* copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following
* conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
*
* The complete license agreement can be found here:
* http://opcfoundation.org/License/MIT/1.00/
* ======================================================================*/
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Opc.Ua.Client;
namespace Opc.Ua.Gds.Client
{
///
/// Public surface of . Exposes
/// the asynchronous operations that the GDS client offers against a
/// connected Global Discovery Server.
///
public interface IGlobalDiscoveryServerClient : IAsyncDisposable
{
/// The application configuration in use.
ApplicationConfiguration Configuration { get; }
/// The message context derived from the configuration.
IServiceMessageContext MessageContext { get; }
/// The administrator credentials used to elevate calls.
IUserIdentity? AdminCredentials { get; set; }
/// The endpoint URL of the connected server, when available.
string? EndpointUrl { get; }
/// true when an active session exists.
bool IsConnected { get; }
/// The active session, when connected.
ISession? Session { get; }
/// The endpoint to connect to. Write-once before connect.
ConfiguredEndpoint? Endpoint { get; set; }
/// Locales preferred by the client.
ArrayOf PreferredLocales { get; set; }
/// Raised on every keep-alive callback.
event KeepAliveEventHandler? KeepAlive;
/// Raised when monitored item notifications change server status.
event MonitoredItemNotificationEventHandler? ServerStatusChanged;
/// Clears the cached .
void ResetCredentials();
/// Connects using the previously assigned endpoint.
ValueTask ConnectAsync(CancellationToken ct = default);
/// Connects to the supplied endpoint URL.
ValueTask ConnectAsync(string endpointUrl, CancellationToken ct = default);
/// Connects to the supplied configured endpoint.
ValueTask ConnectAsync(ConfiguredEndpoint? endpoint, CancellationToken ct = default);
/// Disconnects the active session.
ValueTask DisconnectAsync(CancellationToken ct = default);
/// Returns the URLs of the servers known to the LDS, excluding GDS instances.
ValueTask> GetDefaultServerUrlsAsync(
LocalDiscoveryServerClient? lds,
CancellationToken ct = default);
/// Returns the URLs of GDS instances known to the LDS.
ValueTask> GetDefaultGdsUrlsAsync(
LocalDiscoveryServerClient? lds,
CancellationToken ct = default);
/// Finds the application records with the supplied URI.
/// Calls the FindApplications method on the GDS DirectoryType (OPC 10000-12 §7.5.4).
ValueTask> FindApplicationAsync(
string? applicationUri,
CancellationToken ct = default);
/// Queries the GDS for servers matching the supplied criteria.
/// Calls the QueryServers method on the GDS DirectoryType (OPC 10000-12 §7.5.6).
ValueTask> QueryServersAsync(
uint maxRecordsToReturn,
string? applicationName,
string? applicationUri,
string? productUri,
ArrayOf serverCapabilities,
CancellationToken ct = default);
/// Queries the GDS for servers matching the supplied criteria.
/// Calls the QueryServers method on the GDS DirectoryType (OPC 10000-12 §7.5.6).
ValueTask<(ArrayOf servers, DateTimeUtc lastCounterResetTime)> QueryServersAsync(
uint startingRecordId,
uint maxRecordsToReturn,
string? applicationName,
string? applicationUri,
string? productUri,
ArrayOf serverCapabilities,
CancellationToken ct = default);
/// Queries the GDS for application registrations.
/// Calls the QueryApplications method on the GDS DirectoryType (OPC 10000-12 §7.5.7).
ValueTask<(
ArrayOf applications,
DateTimeUtc lastCounterResetTime,
uint nextRecordId)> QueryApplicationsAsync(
uint startingRecordId,
uint maxRecordsToReturn,
string? applicationName,
string? applicationUri,
uint applicationType,
string? productUri,
ArrayOf serverCapabilities,
CancellationToken ct = default);
/// Gets the registered application with the specified id.
/// Calls the GetApplication method on the GDS DirectoryType (OPC 10000-12 §7.5.5).
ValueTask GetApplicationAsync(
NodeId applicationId,
CancellationToken ct = default);
/// Registers the supplied application with the GDS.
/// Calls the RegisterApplication method on the GDS DirectoryType (OPC 10000-12 §7.5.2).
ValueTask RegisterApplicationAsync(
ApplicationRecordDataType application,
CancellationToken ct = default);
/// Updates an existing application registration.
/// Calls the UpdateApplication method on the GDS DirectoryType (OPC 10000-12 §7.5.3).
ValueTask UpdateApplicationAsync(
ApplicationRecordDataType application,
CancellationToken ct = default);
/// Unregisters the application with the supplied id.
/// Calls the UnregisterApplication method on the GDS DirectoryType (OPC 10000-12 §7.5.8).
ValueTask UnregisterApplicationAsync(
NodeId applicationId,
CancellationToken ct = default);
/// Lists the certificates issued for the supplied application.
/// Calls the GetCertificates method on the GDS CertificateDirectoryType (OPC 10000-12 §7.6.10).
ValueTask<(ArrayOf certificateTypeIds, ArrayOf certificates)> GetCertificatesAsync(
NodeId applicationId,
NodeId certificateGroupId,
CancellationToken ct = default);
/// Checks the revocation status of the supplied certificate.
/// Calls the CheckRevocationStatus method on the GDS CertificateDirectoryType (OPC 10000-12 §7.6.11).
ValueTask<(StatusCode certificateStatus, DateTimeUtc validityTime)> CheckRevocationStatusAsync(
ByteString certificate,
CancellationToken ct = default);
/// Revokes the supplied certificate for an application.
/// Calls the RevokeCertificate method on the GDS CertificateDirectoryType (OPC 10000-12 §7.6.9).
ValueTask RevokeCertificateAsync(
NodeId applicationId,
ByteString certificate,
CancellationToken ct = default);
/// Starts a new key-pair certificate request.
/// Calls the StartNewKeyPairRequest method on the GDS CertificateDirectoryType (OPC 10000-12 §7.6.4).
ValueTask StartNewKeyPairRequestAsync(
NodeId applicationId,
NodeId certificateGroupId,
NodeId certificateTypeId,
string subjectName,
ArrayOf domainNames,
string privateKeyFormat,
char[] privateKeyPassword,
CancellationToken ct = default);
/// Starts a signing certificate request.
/// Calls the StartSigningRequest method on the GDS CertificateDirectoryType (OPC 10000-12 §7.6.5).
ValueTask StartSigningRequestAsync(
NodeId applicationId,
NodeId certificateGroupId,
NodeId certificateTypeId,
ByteString certificateRequest,
CancellationToken ct = default);
/// Finishes the supplied certificate request.
/// Calls the FinishRequest method on the GDS CertificateDirectoryType (OPC 10000-12 §7.6.6).
ValueTask<(ByteString publicKey, ByteString privateKey, ArrayOf issuerCertificates)> FinishRequestAsync(
NodeId applicationId,
NodeId requestId,
CancellationToken ct = default);
/// Lists the certificate groups for the supplied application.
/// Calls the GetCertificateGroups method on the GDS CertificateDirectoryType (OPC 10000-12 §7.6.7).
ValueTask> GetCertificateGroupsAsync(
NodeId applicationId,
CancellationToken ct = default);
/// Returns the trust list node for the supplied certificate group.
/// Calls the GetTrustList method on the GDS CertificateDirectoryType (OPC 10000-12 §7.6.8).
ValueTask GetTrustListAsync(
NodeId applicationId,
NodeId certificateGroupId,
CancellationToken ct = default);
/// Returns the certificate status for the supplied group / type.
/// Calls the GetCertificateStatus method on the GDS CertificateDirectoryType (OPC 10000-12 §7.6.12).
ValueTask GetCertificateStatusAsync(
NodeId applicationId,
NodeId certificateGroupId,
NodeId certificateTypeId,
CancellationToken ct = default);
/// Reads the trust list referenced by the supplied id.
/// Reads the trust list via the file transfer methods of TrustListType (OPC 10000-12 §7.8).
ValueTask ReadTrustListAsync(
NodeId trustListId,
CancellationToken ct = default);
/// Reads the trust list referenced by the supplied id.
/// Reads the trust list via the file transfer methods of TrustListType (OPC 10000-12 §7.8).
ValueTask ReadTrustListAsync(
NodeId trustListId,
long maxTrustListSize,
CancellationToken ct = default);
}
}