Media Files (TSMediaFile)

Use TopStepComKit.sharedInstance.mediaFile to list, download, and delete typed device media files. Audio recordings are the currently defined media type.

Data model

TSMediaFileModel

Property	Type	Description
identifier	NSString *	Provider-owned opaque identifier; pass it back unchanged
fileName	NSString *	Complete device file name, including its extension
type	TSMediaFileType	Media type
fileSize	NSNumber *	Size in bytes, or nil when the device does not report it

Enumerations

Value	Number	Description
TSMediaFileTypeUnknown	0	Unknown type
TSMediaFileTypeAudioRecording	1	Audio recording

TSMediaFileOperation is a capability mask. List, Download, Delete, DeleteAll, and ObserveChanges identify the supported operations; None means no operation is supported.

Query capabilities and files

id<TSMediaFileInterface> mediaFile = [TopStepComKit sharedInstance].mediaFile;
TSMediaFileOperation operations =
    [mediaFile supportedOperationsForType:TSMediaFileTypeAudioRecording];

if (operations & TSMediaFileOperationList) {
    [mediaFile fetchMediaFilesOfType:TSMediaFileTypeAudioRecording
                          completion:^(NSArray<TSMediaFileModel *> *files,
                                       NSError *error) {
        if (error) {
            TSLog(@"Failed to fetch recordings: %@", error.localizedDescription);
            return;
        }
        TSLog(@"The device has %lu recordings", (unsigned long)files.count);
    }];
}

- (TSMediaFileOperation)supportedOperationsForType:(TSMediaFileType)type;
- (void)fetchMediaFilesOfType:(TSMediaFileType)type
                   completion:(nullable TSMediaFileListBlock)completion;

Success with no files returns an empty array. Failure returns a nil list and an error. The completion runs exactly once on the main thread.

Download a file

- (void)downloadMediaFile:(TSMediaFileModel *)mediaFile
          localFolderPath:(NSString *)localFolderPath
                 progress:(nullable TSMediaFileDownloadProgressBlock)progress
               completion:(nullable TSMediaFileDownloadCompletionBlock)completion;

[mediaFile downloadMediaFile:selectedFile
             localFolderPath:recordingsFolder
                    progress:^(double progress) {
    TSLog(@"Download: %.1f%%", progress);
} completion:^(NSString *localFilePath, NSError *error) {
    if (error) {
        TSLog(@"Download failed: %@", error.localizedDescription);
        return;
    }
    TSLog(@"Saved to: %@", localFilePath);
}];

progress is a percentage from 0.0 through 100.0, not a fraction from 0.0 through 1.0. The SDK creates a missing destination directory and returns the final local path on success.

Delete files

- (void)deleteMediaFile:(TSMediaFileModel *)mediaFile
             completion:(nullable TSCompletionBlock)completion;

- (void)deleteAllMediaFilesOfType:(TSMediaFileType)type
                       completion:(nullable TSCompletionBlock)completion;

Check the corresponding Delete or DeleteAll capability first. Do not keep using models from a stale list after deletion.

Observe list invalidation

- (void)registerMediaFileListDidChangedBlock:
    (nullable TSMediaFileListDidChangedBlock)changeBlock;

The callback means that the cached list for the reported type is invalid. Fetch it again instead of inferring local changes. Pass nil to unregister.

Important notes

1. Download and delete models returned by the list API; never manufacture provider identifiers.
2. Check the operation mask for each media type because devices need not support every operation.
3. Unregister list observation during teardown and ignore download UI updates after the screen is gone.