Синхронизация времени устройства

Синхронизируйте внутренние часы подключённого устройства с текущим временем. Этот способ подходит, когда не требуется передавать конкретную дату.

Предварительные условия

Перед синхронизацией времени устройства убедитесь, что:

• Устройство подключено и находится в стабильном состоянии.
• Устройство поддерживает протокол 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?	Необязательный обработчик, вызываемый после завершения операции.

Параметры обратного вызова:

Имя	Тип	Описание
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?

    /// 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

Обработка ошибок

Обработчик завершения сообщает результат синхронизации:

1. Считайте операцию завершённой только после проверки success.
2. Если success равно false, сведения о причине доступны в error.
3. Если доступен statusCode, сохраняйте его для диагностики или обработки особенностей устройства.
4. Не полагайтесь на конкретный код ошибки или состояния, если он не задокументирован для данного устройства.

Рекомендации

1. Проверяйте соответствие протоколу: перед вызовом метода убедитесь, что устройство поддерживает DeviceInfoAPI.

2. Вызывайте после подключения: синхронизируйте время только после подключения и готовности устройства.

3. Обрабатывайте все значения: проверяйте success, statusCode и error, а не только error.

4. Обновляйте UI в главной очереди: выполняйте вызванные завершением обновления UIKit в главной очереди.

Примечания

• syncDeviceTime не принимает целевое значение Date; если дату требуется передать явно, используйте setDeviceTime(to:completion:).
• Публичный API описывает синхронизацию с текущим временем, но не определяет правила преобразования UTC.
• Поддержка синхронизации времени зависит от модели устройства и версии прошивки.