媒体文件（TSMediaFile）

通过 TopStepComKit.sharedInstance.mediaFile 按类型查询、下载和删除设备媒体文件。当前公开的媒体类型为录音文件。

数据模型

TSMediaFileModel

属性	类型	说明
`identifier`	`NSString *`	Provider 维护的不透明文件标识，只能原样传回接口
`fileName`	`NSString *`	包含扩展名的完整设备文件名
`type`	`TSMediaFileType`	媒体文件类型
`fileSize`	`NSNumber *`	文件字节数；设备未提供时为 `nil`

枚举

枚举	值	说明
`TSMediaFileTypeUnknown`	0	未知类型
`TSMediaFileTypeAudioRecording`	1	录音文件

TSMediaFileOperation 是能力位掩码：List、Download、Delete、DeleteAll、ObserveChanges 分别表示列表、下载、单个删除、全部删除和列表失效监听；None 表示不支持任何操作。

查询能力与列表

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(@"获取录音列表失败: %@", error.localizedDescription);
            return;
        }
        TSLog(@"设备共有 %lu 个录音文件", (unsigned long)files.count);
    }];
}

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

成功且没有文件时返回空数组；失败时列表为 nil 并返回错误。回调在主线程调用一次。

下载文件

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

[mediaFile downloadMediaFile:selectedFile
             localFolderPath:recordingsFolder
                    progress:^(double progress) {
    TSLog(@"下载进度: %.1f%%", progress);
} completion:^(NSString *localFilePath, NSError *error) {
    if (error) {
        TSLog(@"下载失败: %@", error.localizedDescription);
        return;
    }
    TSLog(@"文件已保存到: %@", localFilePath);
}];

progress 是 0.0～100.0 的百分比，不是 0.0～1.0。目标目录不存在时 SDK 会创建；成功回调返回最终本地文件路径。

删除文件

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

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

先检查对应的 Delete 或 DeleteAll 能力位。删除成功后不要继续使用旧列表中的模型。

监听列表失效

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

收到回调表示指定类型的缓存列表已失效，应重新调用 fetchMediaFilesOfType:completion:，而不是在本地猜测增删项。传 nil 注销监听。

注意事项

下载和删除必须使用列表接口返回的原始 TSMediaFileModel，不要自行构造 identifier。
每次操作前按媒体类型检查能力位，不要假设所有设备均支持全部操作。
页面销毁时注销列表监听，并忽略已经离开页面的下载 UI 更新。

数据模型​

TSMediaFileModel​

枚举​

查询能力与列表​

下载文件​

删除文件​

监听列表失效​

注意事项​