platform sdk archive transfer

About archive transfer

In Security Center, archive transfer is the mechanism that moves recorded video between archivers. The Platform SDK exposes the workflow through Engine.ArchiveTransferManager, a manager that creates and operates transfer groups for backups, retrievals, restores, and trickling transfers.

ArchiveTransferManager requires a Platform SDK Engine that is logged on to a Directory, and the Security Center license must include the Media SDK option. Access the manager through the engine:

ArchiveTransferManager manager = engine.ArchiveTransferManager;

Creating a backup transfer group

A backup transfer group copies recorded video from one archiver to a backup archiver on a schedule. Use CreateBackupBuilder and the fluent setters, then call Build to produce a TransferGroup:

TransferGroup backup = engine.ArchiveTransferManager
    .CreateBackupBuilder()
    .SetName("Nightly backup")
    .SetDescription("Backup of perimeter cameras")
    .SetSources(perimeterCameraGuids)
    .SetSimultaneousDownload(5)
    .SetRecurringDaily(
        atTimeOfDay: DateTime.Today.AddHours(22))
    .Build();

SetName must be called before Build; Build throws InvalidOperationException if no name was set. Source GUIDs passed to SetSources must resolve to entities of type Camera, ArchiverRole, or Area. Empty Guids or other entity types raise ArgumentException or InvalidOperationException.

The returned TransferGroup exposes TransferGroupType, SimultaneousDownload, and methods to inspect sources: GetSources, GetCameras, GetCamerasAndArchivers, GetCamerasByArchiver, and GetAreas.

Creating a retrieve transfer group

A retrieve transfer group pulls archives back to a primary archiver, typically from edge storage on a camera. The pattern matches backup, but the builder comes from CreateRetrieveBuilder:

TransferGroup retrieve = engine.ArchiveTransferManager
    .CreateRetrieveBuilder()
    .SetName("Edge retrieve")
    .SetSources(cameraGuid)
    .SetTimeRangeBetween(
        TimeSpan.FromHours(13),
        TimeSpan.FromHours(15))
    .SetManual()
    .Build();

The retrieve builder has two setters that the backup builder does not:

• CoveringEverythingSinceLastTransfer covers everything since the most recent successful transfer.
• CoveringEverythingSinceLastTransferUpTo(int days) caps that look-back at the specified number of days.

Choosing what to transfer

By default, a transfer group transfers everything since the last successful transfer. To narrow the transfer to specific content categories, both builders share these setters:

• SetAlarms(bool)
• SetBookmarks(bool)
• SetInputTriggers(bool)
• SetMotionEvents(bool)
• SetProtectedVideos(bool)
• SetVideoAnalyticsEvents(bool)
• SetAllArchiveswhenTheCameraWasOffline(bool)

Calling any of these (with true or false) switches the transfer to selective mode. Calling them with false afterwards does not restore the "everything since last transfer" mode. To return to that mode explicitly, call SetEverythingSinceLastTransfer.

SetOffloadBefore and SetOffloadAfter also switch the transfer to selective mode. If you want to keep transferring everything since the last successful transfer, call SetEverythingSinceLastTransfer after these setters.

Setting the time range

On the builders, use one of the supported time-range setters:

• SetTimeRangeBetween(TimeSpan startTimeOfDay, TimeSpan endTimeOfDay) for a time-of-day window.
• SetFromLastMinute(int), SetFromLastHour(int), SetFromLastDays(int) for a relative window ending when the transfer runs.

Recurrence

By default, the builders start with a manual, non-recurring schedule. The transfer group runs only when your application calls StartTransfer. To make it recurring, call one of the recurrence setters below, or EnableRecurring(true). To return the group to manual mode, call SetManual; EnableRecurring(false) is equivalent and switches the transfer to manual mode.

To configure recurrence, choose one of:

• SetRecurringDaily(DateTime atTimeOfDay, TimeSpan? duration = null)
• SetReccuringWeekly(DateTime atTimeOfDay, params DayOfWeek[] days), with an overload that accepts a TimeSpan duration between atTimeOfDay and days
• SetReccuringHourly(int hours), where hours is between 1 and 24
• SetReccuringMinutely(int minutes), where minutes is between 1 and 60

Note

The atTimeOfDay parameter for the daily and weekly setters must have Kind == DateTimeKind.Local. Passing a UTC or unspecified DateTime raises ArgumentException. DateTime.Today.AddHours(...) produces a value of the correct kind.

Starting and stopping a transfer group

StartTransfer and StopTransfer operate on existing transfer groups by GUID:

manager.StartTransfer(backup.Guid);
// later
manager.StopTransfer(backup.Guid);

Both methods have an IEnumerable<Guid> overload that operates on multiple transfer groups in one call.

Monitoring transfer progress

Engine.TransferGroupManager reports live transfer progress for the transfer groups you register. Add the transfer groups to the monitored set, then subscribe to TransferStateChanged:

engine.TransferGroupManager
    .AddTransferGroupsToMonitor(new[] { backup.Guid });
engine.TransferGroupManager.TransferStateChanged +=
    OnTransferStateChanged;

The event arguments carry the transfer groups whose state changed. Each TransferState identifies the transfer group (Id, FriendlyName) and exposes Items, the per-camera progress, and Sources, the per-source progress including the next scheduled start:

private void OnTransferStateChanged(
    object sender, TransferStateChangedEventArgs e)
{
    foreach (TransferState state in e.ModifiedTransferStates)
    {
        foreach (TransferStateItem item in state.Items)
        {
            Console.WriteLine(
                $"{item.CameraName}: {item.Status}, " +
                $"{item.Progression:F0}%, " +
                $"{item.TransferedDataSize} bytes");
        }
    }
}

A TransferStateItem also reports LastStart and LastEnd, the current file, the transfer bitrate, and, when a transfer fails, ErrorCode and ErrorDetails. MonitoredTaskIds lists the registered transfer groups, and RemoveTransferGroupsToMonitor stops the monitoring. To read the current state on demand instead of subscribing, call GetTransferStates with the transfer group GUIDs.

One-off transfers

For one-time transfers that should not be persisted as a recurring group, the manager exposes three services. Each has its own members and its own pre-conditions for StartTransfer.

Manual backup

CreateManualBackupTransferService returns ManualBackupTransferService. The service supports the same content filters as the backup builder (SetAlarms, SetBookmarks, and so on), plus SetSimultaneousDownload, SetOffloadBefore, SetOffloadAfter, and SetTimeRange(DateTime fromUTC, DateTime toUTC). Both DateTime arguments must have Kind == DateTimeKind.Utc. Configure sources with SetSources, then call StartTransfer. The call throws InvalidOperationException if no sources have been set.

Manual restore

CreateManualRestoreService returns ManualRestoreTransferService. Configure the destination archiver with SetDestination(Guid), the archiver agent that handles the restore with SetArchiverAgent(Guid), and the archives to restore with SetArchivesToRestore(RestoreData[]). Each RestoreData carries a FilePath, StartTime, and EndTime. Optionally protect the restored archives with SetArchiveProtectionFor(int days), SetArchiveProtectionIndefinitely, or SetArchiveProtectionUntil(DateTime utcTime), then call StartTransfer. StartTransfer throws InvalidOperationException if either the destination or the restore data is missing.

Manual trickling

CreateManualTricklingTransferHandler returns ManualTricklingTransferService, used to move archives from archiver to archiver. It supports the same content filters as the manual backup service plus the full set of builder time-range methods: SetTimeRange, SetTimeRangeBetween, SetFromLastMinute, SetFromLastHour, and SetFromLastDays. Configure sources with SetSources and the destination archiver with SetDestination(Guid), and then call StartTransfer. StartTransfer requires that the destination resolves to a running entity and that the destination is not also listed in the sources when a source entry is a Role.

Querying transfer status and history

ArchiveTransferManager does not surface report queries. To inspect the live state of a transfer group, create an ArchiveTransferQuery with ReportType.ArchiveTransferReport. To inspect past transfer attempts, create a TransferHistoryQuery with ReportType.TransferHistoryReport. Use TransferHistoryDetailsQuery with ReportType.TransferHistoryDetailsReport for per-file detail. For more information, see Platform SDK report manager query reference.

See also

• About video: The video hub.
• About cameras: The camera entity, recording configuration, manual record control, video protection, and stream usage.
• Archiver and auxiliary archiver roles: Archiver configuration, statistics, and certificate management.
• Platform SDK report manager: Running queries against the Directory and processing results.
• Platform SDK report manager query reference: The full catalog of query types, filters, and result schemas.