查询存储信息

向已连接设备请求最新存储信息，然后读取更新后的 storageInfo 属性。

前置条件

查询存储信息前，请确保：

• 设备已连接并处于稳定状态。
• 设备支持 DeviceInfoAPI 协议。

API 参考

框架

AIBuds.xcframework

导入

在需要使用 SDK 的文件中导入主框架：

Swift

Swift

import AIBuds

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

协议

请求方法和结果属性定义在 DeviceInfoAPI 中。

Swift

Swift

protocol DeviceInfoAPI: DeviceAPI {
    /// Device storage information.
    var storageInfo: StorageInfoModel? { get }

    /// Request to query the device storage information.
    /// - Parameters:
    ///   - completion: A closure that is called when the operation completes.
    ///   - success: `true` if the operation was successful; otherwise `false`.
    ///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func requestQueryStorageInfo(
        _ completion: AIBudsCompletionHandler?
    )
}

Objective-C

Objective-C

@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>
/// Device storage information.
@property(nonatomic, readonly, strong) AIBudsStorageInfoModel *_Nullable storageInfo;

/// Request to query the device storage information.
/// - Parameters:
///   - completion: A closure that is called when the operation completes.
///   - success: `true` if the operation was successful; otherwise `false`.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation
///   was successful.
- (void)requestQueryStorageInfoWithCompletion:(AIBudsCompletionHandler _Nullable)completion;
@end

实例方法

请求最新的设备存储信息。

Swift

Swift

/// Request to query the device storage information.
/// - Parameters:
///   - completion: A closure that is called when the operation completes.
///   - success: `true` if the operation was successful; otherwise `false`.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func requestQueryStorageInfo(
    _ completion: AIBudsCompletionHandler?
)

Objective-C

Objective-C

/// Request to query the device storage information.
/// - Parameters:
///   - completion: A closure that is called when the operation completes.
///   - success: `true` if the operation was successful; otherwise `false`.
///   - error: An `NSError` object that describes the error that occurred, or `nil` if the operation
///   was successful.
- (void)requestQueryStorageInfoWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

参数

参数	类型	描述
completion	AIBudsCompletionHandler?	请求结束时调用的可选完成回调。

回调参数：

名称	类型	描述
success	Bool / BOOL	请求成功时为 true，否则为 false。
error	NSError?	请求失败时的错误详情；成功时为 nil。

结果属性：

属性	类型	描述
usedSpaceInMB	NSNumber	以 MB 为单位的已用存储空间。
freeSpaceInMB	NSNumber	以 MB 为单位的剩余可用存储空间。

返回值

该方法不会在完成回调中返回存储数据。请求成功后，请读取更新后的 storageInfo 属性。

使用示例

Swift

Swift

import AIBuds

final class DeviceManager {
    weak var device: DeviceConvertible?

    func queryStorageInformation() {
        guard let device = device as? DeviceInfoAPI else {
            print("Device does not support storage queries")
            return
        }

        device.requestQueryStorageInfo { success, error in
            guard success else {
                print("Storage query failed: \(error?.localizedDescription ?? "Unknown error")")
                return
            }

            guard let storage = device.storageInfo else {
                print("The device did not provide storage information")
                return
            }

            print("Used storage: \(storage.usedSpaceInMB) MB")
            print("Free storage: \(storage.freeSpaceInMB) MB")
        }
    }
}

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

@interface DeviceManager ()
@property(weak, nonatomic) id<AIBudsDeviceConvertible> device;
@end

@implementation DeviceManager

- (void)queryStorageInformation {
    id<AIBudsDeviceInfoAPI> device = (id<AIBudsDeviceInfoAPI>)self.device;
    if (![device conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
        NSLog(@"Device does not support storage queries");
        return;
    }

    [device requestQueryStorageInfoWithCompletion:^(BOOL success, NSError *_Nullable error) {
        if (!success) {
            NSLog(@"Storage query failed: %@", error.localizedDescription ?: @"Unknown error");
            return;
        }

        AIBudsStorageInfoModel *storage = device.storageInfo;
        if (!storage) {
            NSLog(@"The device did not provide storage information");
            return;
        }

        NSLog(@"Used storage: %@ MB", storage.usedSpaceInMB);
        NSLog(@"Free storage: %@ MB", storage.freeSpaceInMB);
    }];
}

@end

错误处理

1. 读取刷新后的属性前，先检查 success。
2. 请求失败时，通过 error 获取失败详情。
3. 即使回调成功，也要处理返回 nil 的 storageInfo。
4. 除非目标设备文档明确说明，否则不要假设固定错误码。

最佳实践

1. 成功后读取：仅在查询成功完成后访问 storageInfo。
2. 保持 SDK 单位：两个值均以 MB 为单位，不要按字节解释。
3. 检查协议支持：确认设备支持 DeviceInfoAPI。
4. 在主队列更新 UI：将完成回调触发的 UIKit 更新派发到主队列。

注意事项

• 完成回调仅报告请求状态，不包含 StorageInfoModel 结果。
• StorageInfoModel 仅提供以 MB 为单位的已用和可用空间。
• SDK 未在该模型中提供单独的总容量属性。
• 录制、导入或删除媒体时，存储信息可能发生变化。