设置设备时间

将连接设备的内部时钟设置为应用提供的指定日期和时间。

前置条件

设置设备时间前，请确保：

• 设备已连接并处于稳定状态。
• 设备支持 DeviceInfoAPI 协议。
• 目标 Date 表示应用准备发送的时间。

API 参考

框架

AIBuds.xcframework

导入

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

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

协议

setDeviceTime 方法定义在 DeviceInfoAPI 中，该协议继承自基础设备 API 协议。

Swift

Swift

/// The protocol for device information related API.
protocol DeviceInfoAPI: DeviceAPI {
    /// Sets the device's system time.
    /// - Parameters:
    ///   - date: The target time to set on the device.
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - statusCode: The status code returned by the device. `nil` if the operation failed.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func setDeviceTime(
        to date: Date,
        completion: AIBudsStatusCodeCompletionHandler?
    )
}

Objective-C

Objective-C

/// The protocol for device information related API.
@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>
/// Sets the device's system time.
/// - Parameters:
///   - date: The target time to set on the device.
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - statusCode: The status code returned by the device. `nil` if the operation failed.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the
///     operation was successful.
- (void)setDeviceTime:(NSDate *_Nonnull)date
           completion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;
@end

实例方法

将设备系统时间设置为提供的日期。

Swift

Swift

/// Sets the device's system time.
/// - Parameters:
///   - date: The target time to set on the device.
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - statusCode: The status code returned by the device. `nil` if the operation failed.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func setDeviceTime(
    to date: Date,
    completion: AIBudsStatusCodeCompletionHandler?
)

Objective-C

Objective-C

/// Sets the device's system time.
/// - Parameters:
///   - date: The target time to set on the device.
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - statusCode: The status code returned by the device. `nil` if the operation failed.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the
///     operation was successful.
- (void)setDeviceTime:(NSDate *_Nonnull)date
           completion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;

参数

参数	类型	描述
date	Date / NSDate	要设置到设备的目标时间。
completion	AIBudsStatusCodeCompletionHandler?	操作结束时调用的可选完成回调。

回调参数：

名称	类型	描述
success	Bool / BOOL	操作成功时为 true，否则为 false。
statusCode	NSNumber?	设备返回的状态码。SDK 文档规定，操作失败时该值为 nil。
error	NSError?	操作失败时的错误详情；成功时为 nil。

返回值

该方法不直接返回值，结果通过完成回调提供。

使用示例

Swift

Swift

import AIBuds

final class DeviceManager {

    /// The connected device
    weak var device: DeviceConvertible?

    /// Sets the connected device to the supplied date
    func setDeviceTime(to date: Date) {
        guard let device = device as? DeviceInfoAPI else {
            print("Device does not support setting the time")
            return
        }

        device.setDeviceTime(to: date) { success, statusCode, error in
            if !success {
                print(
                    "Failed to set device time: " + (error?.localizedDescription ?? "Unknown error")
                )
                return
            }

            print(
                "Device time set successfully. Status code: " + (statusCode?.stringValue ?? "N/A")
            )
        }
    }
}

Objective-C

Objective-C

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

@interface DeviceManager ()

/// The connected device
@property(weak, nonatomic) id<AIBudsDeviceConvertible> device;

@end

@implementation DeviceManager

- (void)setDeviceTime:(NSDate *)date {
    id<AIBudsDeviceInfoAPI> device = (id<AIBudsDeviceInfoAPI>)self.device;

    if (![device conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
        NSLog(@"Device does not support setting the time");
        return;
    }

    [device
        setDeviceTime:date
           completion:^(BOOL success, NSNumber *_Nullable statusCode, NSError *_Nullable error) {
               if (!success) {
                   NSLog(@"Failed to set device time: %@",
                         error.localizedDescription ?: @"Unknown error");
                   return;
               }

               NSLog(@"Device time set successfully. Status code: %@", statusCode ?: @"N/A");
           }];
}

@end

错误处理

完成回调报告操作结果：

1. 将目标时间视为已应用前，先检查 success。
2. 当 success 为 false 时，通过 error 获取失败详情。
3. statusCode 可用时保留该值，用于诊断或设备特定处理。
4. 除非目标设备文档明确说明，否则不要假设特定错误码或状态码。

最佳实践

1. 验证目标日期：确认应用发送的是预期日期和时间。

2. 检查协议支持：调用方法前确认设备支持 DeviceInfoAPI。

3. 连接后调用：仅在设备已连接且就绪后设置时间。

4. 处理全部回调值：同时判断 success、statusCode 和 error。

5. 在主队列更新 UI：将完成回调触发的 UIKit 更新派发到主队列。

注意事项

• 公开 API 接受 Date，但未定义 UTC 转换约定。不要加入目标设备未明确规定的时区假设。
• 设备只需与当前时间同步时，请使用 syncDeviceTime(_:)。
• 设置目标时间的支持情况可能因设备型号和固件而异。