Skip to content
Back

ITaskExecutionContext

Interface in Oadm.Sdk.Plugins · Oadm.Sdk.dll

What the server gives one task while it runs on one device.

public interface ITaskExecutionContext

Guide: Task plugins

Properties

Section titled “Properties”

Files

Section titled “Files”
IUploadedFiles Files { get; }

Files uploaded by the dialog (firmware, ACAP packages), referenced by id in the payload.

Logger

Section titled “Logger”
ILogger Logger { get; }

The server log. For what the user should read, use ITaskExecutionContext.Log.

Owner

Section titled “Owner”
ICorePlugin? Owner { get; }

Set when the task was contributed by a core plugin.

TaskId

Section titled “TaskId”
Guid TaskId { get; }

The id of this task (one device).

Vapix

Section titled “Vapix”
IVapixClient Vapix { get; }

Pre-authenticated for the current device.

Methods

Section titled “Methods”

BeginStep

Section titled “BeginStep”
ITaskStep BeginStep(string name)

Default implementation

Starts the named step (activating the planned step of that name) and returns it; see ITaskStep for the end rules. Every device request and every wait is its own step. Use using var step = ctx.BeginStep("...") or the helper TaskStepExtensions.StepAsync. A running step is completed when the next one begins.

CreateClientForAsync

Section titled “CreateClientForAsync”
Task<IVapixClient> CreateClientForAsync(string address, CancellationToken ct)

Default implementation

A VAPIX client for the current device at another address (e.g. the static address the plugin just set), with the stored credentials, the device’s scheme and its pinned certificate. The caller owns the client: dispose it when it implements IDisposable. Read requests only until the identity is verified.

Log

Section titled “Log”
void Log(TaskLogLevel level, string message)

Entry in this task’s log, per device, shown in the task details and persisted. Never log secrets.

MarkCredentialsInvalid

Section titled “MarkCredentialsInvalid”
void MarkCredentialsInvalid()

Default implementation

The device no longer accepts the credentials OADM stored (factory default, password reset): the server deletes them and refreshes the device, which then shows PasswordNotSet or CredentialsRequired. Logged in the task log (without secrets).

PlanSteps

Section titled “PlanSteps”
void PlanSteps(params string[] names)

Default implementation

Announces the steps the task will (probably) run, in order, so the user sees them as Pending from the start. Optional: ITaskExecutionContext.BeginStep also adds steps that were not planned. Planned steps that never run end as Skipped. Name steps in the imperative, short and specific (“Upload firmware”).

ReportProgress

Section titled “ReportProgress”
void ReportProgress(int percent, string? message = null)

Overall progress of the task with an optional status message. Optional when the plugin uses steps: without explicit calls the progress is derived from the steps (each step weighs the same; the running one counts with its own ITaskStep.ReportProgress). Once called, this value wins.

ReportWarning

Section titled “ReportWarning”
void ReportWarning(string message)

The device finishes as “Done with warnings” (unless it fails); the message is logged.

UpdateCredentialsAsync

Section titled “UpdateCredentialsAsync”
Task UpdateCredentialsAsync(string userName, string password, CancellationToken ct)

Default implementation

Stores new credentials for the current device (encrypted, never logged), e.g. after the plugin changed the password of the account OADM uses. Afterwards ITaskExecutionContext.Vapix returns a client with the new credentials; re-read it instead of keeping the old instance.

UpdateDeviceAddressAsync

Section titled “UpdateDeviceAddressAsync”
Task<bool> UpdateDeviceAddressAsync(string newAddress, CancellationToken ct)

Default implementation

Moves OADM’s device record to newAddress so the device stays managed after it was re-addressed. The server first checks that the device answering there has the same serial number (throws DeviceIdentityException otherwise, the record is unchanged), keeps credentials and certificate pin, publishes the change and queues a full refresh; afterwards ITaskExecutionContext.Vapix uses the new address. Returns false when nothing was changed because OADM reaches the device by host name (added by its DNS name or a typed name) or the record already has that address.

UpdateDeviceTlsAsync

Section titled “UpdateDeviceTlsAsync”
Task UpdateDeviceTlsAsync(string scheme, string? expectedFingerprintSha256, CancellationToken ct)

Default implementation

Updates how OADM connects to the current device after the plugin changed its web server: with scheme “https” the device must present the certificate with the SHA-256 fingerprint expectedFingerprintSha256 (hex, separators ignored; null = accept and pin the presented one), with “http” OADM connects over plain HTTP (Digest only). The server connects with the new scheme, verifies the serial number like ITaskExecutionContext.UpdateDeviceAddressAsync, then stores scheme, certificate pin and certificate details (so the device never shows CertificateChanged), publishes the change and queues a full refresh; afterwards ITaskExecutionContext.Vapix uses the new connection. Throws DeviceIdentityException when the device does not answer with the new scheme, has another serial number or presents another certificate; the record is then unchanged.

Used by

Section titled “Used by”