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

デバイス時刻の設定

接続中のデバイスの内蔵時計を、アプリから指定した日時に設定します。

前提条件​

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

  • デバイスが接続済みで、安定した状態にあること
  • デバイスが DeviceInfoAPI プロトコルに対応していること
  • 対象の Date が、アプリから送信する意図した日時を表していること

API リファレンス​

フレームワーク​

AIBuds.xcframework

インポート​

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

Swift
import AIBuds

プロトコル​

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

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

インスタンスメソッド​

デバイスのシステム時刻を指定日時に設定します。

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

パラメータ​

パラメータ型説明
dateDate / NSDateデバイスに設定する日時。
completionAIBudsStatusCodeCompletionHandler?処理完了時に呼び出される任意の完了ハンドラー。

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

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

戻り値​

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

使用例​

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

エラー処理​

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

  1. 指定日時が反映されたと判断する前に success を確認します。
  2. success が false の場合は、error から失敗の詳細を取得します。
  3. statusCode がある場合は、診断やデバイス固有の処理に備えて保持します。
  4. 対象デバイスについて文書化されていないエラーやステータスコードを前提にしないでください。

ベストプラクティス​

  1. 指定日時を検証する: アプリが意図した日時を送信していることを確認します。

  2. プロトコル対応を確認する: メソッドを呼び出す前に、デバイスが DeviceInfoAPI に対応していることを確認します。

  3. 接続完了後に呼び出す: デバイスが接続済みで操作可能になってから時刻を設定します。

  4. すべての完了値を処理する: success、statusCode、error を確認します。

  5. メインキューで UI を更新する: 完了ハンドラーからの UIKit 更新はメインキューへ切り替えます。

注意事項​

  • 公開 API は Date を受け取りますが、UTC 変換の仕様は定めていません。対象デバイスで規定されていないタイムゾーンの前提を追加しないでください。
  • デバイスを現在時刻に合わせるだけの場合は syncDeviceTime(_:) を使用します。
  • 指定日時の設定への対応は、デバイスモデルやファームウェアによって異なる場合があります。