기기 시간 동기화

연결된 기기의 내부 시계를 현재 시간과 동기화합니다. 특정 날짜를 직접 전달하지 않고 기기 시간을 맞출 때 사용하세요.

사전 요구 사항

기기 시간을 동기화하기 전에 다음을 확인하세요.

• 기기가 연결되어 안정적인 상태입니다.
• 기기가 DeviceInfoAPI 프로토콜을 지원합니다.

API 참고

프레임워크

AIBuds.xcframework

가져오기

SDK를 사용할 파일에서 메인 프레임워크를 가져옵니다.

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

프로토콜

syncDeviceTime 메서드는 DeviceInfoAPI에 정의되어 있으며 이 프로토콜은 기본 기기 API 프로토콜을 상속합니다.

Swift

Swift

/// The protocol for device information related API.
protocol DeviceInfoAPI: DeviceAPI {
    /// Synchronizes the device time with the current time.
    /// - Parameters:
    ///   - 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 syncDeviceTime(_ completion: AIBudsStatusCodeCompletionHandler?)
}

Objective-C

Objective-C

/// The protocol for device information related API.
@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>
/// Synchronizes the device time with the current time.
/// - Parameters:
///   - 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)syncDeviceTimeWithCompletion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;
@end

인스턴스 메서드

기기 시간을 현재 시간과 동기화합니다.

Swift

Swift

/// Synchronizes the device time with the current time.
/// - Parameters:
///   - 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 syncDeviceTime(_ completion: AIBudsStatusCodeCompletionHandler?)

Objective-C

Objective-C

/// Synchronizes the device time with the current time.
/// - Parameters:
///   - 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)syncDeviceTimeWithCompletion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;

매개변수

매개변수	타입	설명
completion	AIBudsStatusCodeCompletionHandler?	작업이 끝날 때 호출되는 선택적 completion handler입니다.

콜백 매개변수:

이름	타입	설명
success	Bool / BOOL	작업이 성공하면 true, 실패하면 false입니다.
statusCode	NSNumber?	기기가 반환한 상태 코드입니다. 작업에 실패하면 nil입니다.
error	NSError?	작업 실패 상세 정보이며 성공하면 nil입니다.

반환 값

이 메서드는 값을 직접 반환하지 않습니다. 결과는 completion handler로 전달됩니다.

사용 예제

Swift

Swift

import AIBuds

final class DeviceManager {

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

    /// Synchronizes the connected device with the current time
    func synchronizeDeviceTime() {
        guard let device = device as? DeviceInfoAPI else {
            print("Device does not support time synchronization")
            return
        }

        device.syncDeviceTime { success, statusCode, error in
            if !success {
                print(
                    "Time synchronization failed: "
                        + (error?.localizedDescription ?? "Unknown error")
                )
                return
            }

            print(
                "Time synchronized 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)synchronizeDeviceTime {
    id<AIBudsDeviceInfoAPI> device = (id<AIBudsDeviceInfoAPI>)self.device;

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

    [device syncDeviceTimeWithCompletion:^(
                BOOL success, NSNumber *_Nullable statusCode, NSError *_Nullable error) {
        if (!success) {
            NSLog(@"Time synchronization failed: %@",
                  error.localizedDescription ?: @"Unknown error");
            return;
        }

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

@end

오류 처리

completion handler는 동기화 결과를 보고합니다.

1. 작업 완료로 처리하기 전에 success를 확인하세요.
2. success가 false이면 error에서 실패 상세 정보를 확인하세요.
3. statusCode가 있으면 진단 또는 기기별 처리를 위해 보관하세요.
4. 대상 기기에 정의되지 않은 오류나 상태 코드를 임의로 가정하지 마세요.

권장 사항

1. 프로토콜 확인: 메서드 호출 전에 기기가 DeviceInfoAPI를 지원하는지 확인하세요.

2. 연결 후 호출: 기기가 연결되어 사용할 수 있는 상태에서만 동기화하세요.

3. 모든 completion 값 처리: success, statusCode 및 error를 모두 확인하고 error 하나에만 의존하지 마세요.

4. 메인 큐에서 UI 변경: completion에서 수행하는 UIKit 변경은 메인 큐로 전달하세요.

참고

• syncDeviceTime은 대상 Date를 받지 않습니다. 특정 시간을 전달하려면 setDeviceTime(to:completion:)을 사용하세요.
• 공개 API는 현재 시간과의 동기화를 정의하지만 UTC 변환 규칙은 정의하지 않습니다.
• 시간 동기화 지원 여부는 기기 모델과 펌웨어에 따라 다를 수 있습니다.