기기 시간 설정

앱에서 지정한 날짜와 시간으로 연결된 기기의 내부 시계를 설정합니다.

사전 요구 사항

기기 시간을 설정하기 전에 다음을 확인하세요.

기기가 연결되어 안정적인 상태입니다.
기기가 DeviceInfoAPI 프로토콜을 지원합니다.
대상 Date가 앱에서 전송하려는 시간을 나타냅니다.

API 참고

프레임워크

AIBuds.xcframework

가져오기

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

Swift
Objective-C

import AIBuds

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

프로토콜

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

Swift
Objective-C

/// 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?
    )
}

/// 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
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.
func setDeviceTime(
    to date: Date,
    completion: AIBudsStatusCodeCompletionHandler?
)

/// 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?`	작업이 끝날 때 호출되는 선택적 completion handler입니다.

콜백 매개변수:

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

반환 값

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

사용 예제

Swift
Objective-C

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")
            )
        }
    }
}

#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

오류 처리

completion handler는 작업 결과를 보고합니다.

대상 시간이 적용된 것으로 처리하기 전에 success를 확인하세요.
success가 false이면 error에서 실패 상세 정보를 확인하세요.
statusCode가 있으면 진단 또는 기기별 처리를 위해 보관하세요.
대상 기기에 정의되지 않은 오류나 상태 코드를 임의로 가정하지 마세요.

권장 사항

대상 날짜 검증: 앱에서 의도한 날짜와 시간을 전송하는지 확인하세요.
프로토콜 확인: 메서드 호출 전에 기기가 DeviceInfoAPI를 지원하는지 확인하세요.
연결 후 호출: 기기가 연결되어 사용할 수 있는 상태에서만 시간을 설정하세요.
모든 completion 값 처리: success, statusCode 및 error를 모두 확인하세요.
메인 큐에서 UI 변경: completion에서 수행하는 UIKit 변경은 메인 큐로 전달하세요.

참고

공개 API는 Date를 받지만 UTC 변환 규칙은 정의하지 않습니다. 대상 기기에 정의되지 않은 시간대 처리를 임의로 추가하지 마세요.
기기 시간을 현재 시간과 맞추기만 하면 syncDeviceTime(_:)을 사용하세요.
특정 시간 설정 지원 여부는 기기 모델과 펌웨어에 따라 다를 수 있습니다.

사전 요구 사항​

API 참고​

프레임워크​

가져오기​

프로토콜​

인스턴스 메서드​

매개변수​

반환 값​

사용 예제​

오류 처리​

권장 사항​

참고​