メインコンテンツまでスキップ

デバイス時刻の同期

接続中のデバイスの内蔵時計を現在時刻に合わせます。特定の日時を指定せず、デバイスの時計を現在時刻に同期する場合に使用します。

前提条件​

デバイス時刻を同期する前に、次の条件を確認してください。

  • デバイスが接続済みで、安定した状態にあること
  • デバイスが DeviceInfoAPI プロトコルに対応していること

API リファレンス​

フレームワーク​

AIBuds.xcframework

インポート​

SDK を使用するファイルで、メインフレームワークをインポートします。

Swift
import AIBuds

プロトコル​

syncDeviceTime メソッドは DeviceInfoAPI で定義されています。このプロトコルは基底デバイス API プロトコルを継承します。

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

インスタンスメソッド​

デバイス時刻を現在時刻に同期します。

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

パラメータ​

パラメータ型説明
completionAIBudsStatusCodeCompletionHandler?処理完了時に呼び出される任意の完了ハンドラー。

コールバックのパラメータ:

名前型説明
successBool / BOOL処理が成功した場合は true、それ以外は false。
statusCodeNSNumber?デバイスが返すステータスコード。SDK の仕様では、処理失敗時は nil です。
errorNSError?処理失敗時のエラー詳細。成功時は nil。

戻り値​

このメソッドは値を直接返しません。結果は完了ハンドラーに渡されます。

使用例​

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

エラー処理​

同期結果は完了ハンドラーに渡されます。

  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 変換の仕様は定めていません。
  • 時刻同期への対応は、デバイスモデルやファームウェアによって異なる場合があります。