Plugin Receiver APIs

Receiver APIs for Plugins

ReceiverManager is the source of truth. Prefer it over caching receiver configuration objects for long periods because receivers can be edited, reordered, deleted, or reloaded while the application is running.

Observe selection

private void SelectedReceiverChanged(object? sender, ReceiverSelectionChangedEventArgs e)
{
    Receiver? receiver = e.SelectedReceiver;
    _context!.Logger.LogDebug("Selected receiver changed to {Receiver}.", receiver?.Configuration.Name ?? "none");
}

public Task EnableAsync(CancellationToken cancellationToken = default)
{
    _context!.ReceiverManager.SelectedReceiverChanged += SelectedReceiverChanged;
    return Task.CompletedTask;
}

public Task DisableAsync(CancellationToken cancellationToken = default)
{
    _context!.ReceiverManager.SelectedReceiverChanged -= SelectedReceiverChanged;
    return Task.CompletedTask;
}

Useful members:

• Receivers: current ordered receiver collection.
• SelectedReceiver: current selection or null.
• GetReceiver(Guid): lookup by application receiver ID.
• SelectReceiver(Guid?): select or clear selection.
• AddReceiverAsync, UpdateReceiverAsync, RemoveReceiverAsync: validated persistent mutations.
• MoveReceiverAsync: persistent ordering.
• ReloadAsync: reload the configured receiver JSON file.

Receiver identity

Do not confuse these values:

• Receiver.Id is the application's stable Guid used by manager and command APIs.
• Receiver.Configuration.ReceiverId is the numeric device/protocol identifier.
• Receiver.Configuration.IpAddress is the configured IPv4 address.

Refresh and status

Receiver? receiver = context.ReceiverManager.SelectedReceiver;

if (receiver is not null)
    await context.ReceiverCommandManager.RefreshReceiverAsync(receiver.Id, cancellationToken);

Subscribe to ReceiverConnectionStatusChanged and ReceiverActivityStatusChanged when UI must respond immediately. Unsubscribe during disablement.

RefreshReceiverEpgAsync requires an online receiver. RefreshAllReceiversAsync refreshes the configured collection. DiscoverReceiverAtIpAsync probes an IPv4 address and returns discovery details without adding it.

Send a command

CMD_SEND_BUTTON_KEY command = CMD_SEND_BUTTON_KEY.Default;
command.AddPayload(new CMD_PAYLOAD { Key = "BACK" });

CommandResult<CMD_GET_CURRENT_EPG_RESPONSE> result = await context.ReceiverCommandManager.SendCommandAsync<CMD_GET_CURRENT_EPG_RESPONSE>(
    receiver.Id,
    command,
    timeout: TimeSpan.FromSeconds(5),
    cancellationToken: cancellationToken);

if (!result.IsSuccess)
    context.Logger.LogWarning("Receiver command failed: {Error}", result.ErrorMessage);

Use the response type required by the command. Always check IsSuccess and handle a null Response.

Throttling and activity

Normal commands use the host's safety throttle and update receiver activity automatically.

ReceiverCommandExecutionOptions.Default

Only bypass throttling for protocol sequences that truly require rapid consecutive messages:

ReceiverCommandExecutionOptions.BypassThrottling
ReceiverCommandExecutionOptions.BypassThrottlingWithoutActivityUpdates

Do not use bypass options merely to make a UI feel faster. They can overwhelm a receiver or conflict with other application commands.

Mutating receiver state

Use manager methods rather than directly changing Receiver.Configuration. The manager enforces unique names, IDs, and IP addresses and persists changes. Use SetReceiverActivityStatus only when the plugin owns a longer operation whose activity cannot be inferred from SendCommandAsync.