Установка времени устройства

Установите на внутренних часах подключённого устройства дату и время, заданные приложением.

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

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

• Устройство подключено и находится в стабильном состоянии.
• Устройство поддерживает протокол 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(_:).
• Поддержка установки заданного времени зависит от модели устройства и версии прошивки.