Class SecomClient

Namespace

EncDotNet.S100.Collections.Secom

Assembly

EncDotNet.S100.Collections.dll

A read-only client for one SECOM (IEC 63173-2) service: Capability, GetSummary and Get (issue #804), presenting its Identity, if any, when the service asks for a client certificate (#883).

public sealed class SecomClient

Inheritance

object

SecomClient

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The ServiceUri is the service's registered endpoint (for example https://s124.ccg-gcc.gc.ca/api/secom); interface paths such as v2/object/summary resolve against it. Unless a version is pinned, the client tries edition 2 (/v2) first and falls back to edition 1 (/v1) when the service does not answer there, then keeps using the version that answered.

A SECOM 2.0 service with no GET summary but the enveloped POST forms (POST …/v2/object/search/summary and …/v2/object/search, as KHRA and KRISO have) is listed and read through them, signed by Signer, once a GET summary answers 404 (#838). Access requests and encrypted data are not supported yet; see docs/design/dataset-collections.md §7.5.

Constructors

SecomClient(HttpClient, Uri, SecomApiVersion?)

Creates a client for the service at serviceUri.

public SecomClient(HttpClient httpClient, Uri serviceUri, SecomApiVersion? version = null)

Parameters

httpClient HttpClient

The client used for requests.

serviceUri Uri

The service's endpoint URI (http or https).

version SecomApiVersion?

Pins the interface version; null to detect it.

Fields

ServiceMessageKey

The key under which a failure's Data holds the service's own explanation.

public const string ServiceMessageKey = "SecomServiceMessage"

Field Value

string

Properties

ApiVersion

The interface version in use: pinned, or detected by the first request that succeeded; null before then.

public SecomApiVersion? ApiVersion { get; }

Property Value

SecomApiVersion?

Identity

The MCP identity every request is tagged with (#883): a handler from CreateHandler() presents it when the service asks for a client certificate. null presents none.

public SecomClientIdentity? Identity { get; init; }

Property Value

SecomClientIdentity

SentSigned

True once a SECOM 2.0 request signed by Signer has been sent.

public bool SentSigned { get; }

Property Value

bool

ServiceUri

The service's endpoint URI, ending in /.

public Uri ServiceUri { get; }

Property Value

Uri

Signer

The signer for SECOM 2.0 POST requests (#838): this client's MCP identity, when one is set; null or returning null when there is none.

public Func<SecomEnvelopeSigner?>? Signer { get; init; }

Property Value

Func<SecomEnvelopeSigner>

UsesPostInterfaces

True when this client lists and reads through the SECOM 2.0 POST forms: set to start with them (a service known to need them), or found when a GET summary answered 404 and the POST form exists.

public bool UsesPostInterfaces { get; init; }

Property Value

bool

Methods

CreatePostGetRequest(Uri, SecomEnvelopeSigner, DateTimeOffset)

The request that Gets an object through the SECOM 2.0 POST form (POST …/v2/object/search), for hosts that fetch it themselves (the downloader). getObjectUri is the object's GET URI (GetObjectUri(string, SecomApiVersion)), which names the service and the data reference.

public static HttpRequestMessage CreatePostGetRequest(Uri getObjectUri, SecomEnvelopeSigner signer, DateTimeOffset now)

Parameters

getObjectUri Uri

signer SecomEnvelopeSigner

now DateTimeOffset

Returns

HttpRequestMessage

Exceptions

ArgumentException

The URI names no data reference.

GetAsync(string, CancellationToken)

Calls Get for one data object.

public Task<SecomDataObject?> GetAsync(string dataReference, CancellationToken cancellationToken = default)

Parameters

dataReference string

cancellationToken CancellationToken

Returns

Task<SecomDataObject>

The object, or null when the service returned none.

Exceptions

HttpRequestException

The service did not answer on any interface version.

InvalidDataException

The response is not a SECOM get response.

GetCapabilityAsync(CancellationToken)

Calls Capability.

public Task<SecomCapability> GetCapabilityAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<SecomCapability>

Exceptions

HttpRequestException

The service did not answer on any interface version.

InvalidDataException

The response is not a SECOM capability response.

GetObjectUri(string, SecomApiVersion)

The URI that Gets the object dataReference on version.

public Uri GetObjectUri(string dataReference, SecomApiVersion version)

Parameters

dataReference string

version SecomApiVersion

Returns

Uri

GetSummariesAsync(SecomQuery, int, CancellationToken)

Calls GetSummary page by page until every entry is read, at most maxItems entries are read, or a page adds nothing new (some services ignore paging). Entries are returned once per data reference.

public Task<SecomSummaryList> GetSummariesAsync(SecomQuery query, int maxItems = 10000, CancellationToken cancellationToken = default)

Parameters

query SecomQuery

maxItems int

cancellationToken CancellationToken

Returns

Task<SecomSummaryList>

Exceptions

HttpRequestException

The service did not answer on any interface version.

InvalidDataException

A response is not a SECOM summary response.

GetSummaryPageAsync(SecomQuery, int, CancellationToken)

Calls GetSummary for one page (pages count from 1).

public Task<SecomSummaryPage> GetSummaryPageAsync(SecomQuery query, int page = 1, CancellationToken cancellationToken = default)

Parameters

query SecomQuery

page int

cancellationToken CancellationToken

Returns

Task<SecomSummaryPage>

Remarks

Some services answer a filtered request that matches nothing with 404. So for a filtered query the interface version is detected first, with an unfiltered request; once it is known, a 404 means an empty page.

Exceptions

HttpRequestException

The service did not answer on any interface version.

InvalidDataException

The response is not a SECOM summary response.

NormalizeServiceUri(Uri)

Returns the service URI in canonical form: query and fragment dropped, a trailing /, and any trailing /v1 or /v2 (or an interface path after it) removed, so users may paste an interface URL.

public static Uri NormalizeServiceUri(Uri serviceUri)

Parameters

serviceUri Uri

Returns

Uri

ReadDataObject(Stream)

Reads the first data object of a Get response body, for hosts that fetched it themselves (for example the downloader).

public static SecomDataObject ReadDataObject(Stream body)

Parameters

body Stream

Returns

SecomDataObject

Exceptions

InvalidDataException

The body is not a SECOM get response with data.