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

デバイスを探す

接続中のデバイスに、ファームウェアで定義された探索通知の開始を要求します。この API は対象デバイスを探すためのもので、周辺の Bluetooth デバイスをスキャンするものではありません。

前提条件​

この API を呼び出す前に、次の条件を確認してください。

  • デバイスが接続済みで、操作可能な状態であること
  • デバイスが DeviceFindAPI プロトコルに対応していること

API リファレンス​

フレームワーク​

AIBuds.xcframework

インポート​

Swift
import AIBuds

プロトコル​

findDevice メソッドは DeviceFindAPI で定義されています。

Swift
/// Controls the locate-device indication on a connected device.
///
/// This API operates on the device represented by the conforming object. It
/// does not perform Bluetooth discovery or scan for nearby devices. The
/// indication used to locate the device, such as sound, vibration, or another
/// firmware-defined behavior, depends on the device implementation.
///
/// A successful completion from `findDevice(_:)` means the start command was
/// accepted; it does not mean the device has been physically located. Observe
/// `DeviceDelegate.deviceDidReportFound(_:)` or
/// `SDKDelegate.deviceDidReportFound(_:)` when the device supports reporting
/// that it has been found.
public protocol DeviceFindAPI: DeviceAPI {
    /// Requests that the connected device start its locate-device indication.
    ///
    /// The completion reports whether the command was accepted and executed by
    /// the device. It does not report whether the user has located the device.
    /// Use `DeviceDelegate.deviceDidReportFound(_:)` or the corresponding
    /// `SDKDelegate` callback for a device-originated found event.
    /// - Parameters:
    ///   - completion: Called when command processing completes.
    ///     - success: `true` when the device accepted the command; otherwise,
    ///       `false`.
    ///     - error: The command or communication error, or `nil` on success.
    func findDevice(_ completion: AIBudsCompletionHandler?)
}

インスタンスメソッド​

接続中のデバイスに探索通知の開始を要求します。

Swift
/// Requests that the connected device start its locate-device indication.
///
/// The completion reports whether the command was accepted and executed by
/// the device. It does not report whether the user has located the device.
/// Use `DeviceDelegate.deviceDidReportFound(_:)` or the corresponding
/// `SDKDelegate` callback for a device-originated found event.
/// - Parameters:
///   - completion: Called when command processing completes.
///     - success: `true` when the device accepted the command; otherwise,
///       `false`.
///     - error: The command or communication error, or `nil` on success.
func findDevice(_ completion: AIBudsCompletionHandler?)

パラメータ​

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

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

名前型説明
successBool / BOOLデバイスがコマンドを受理した場合は true、それ以外は false。
errorNSError?コマンドまたは通信のエラー。成功時は nil。

戻り値​

このメソッドは値を直接返しません。完了ハンドラーが示すのはコマンド処理の結果であり、ユーザーが実際にデバイスを見つけたかどうかではありません。

使用例​

Swift
import AIBuds

final class DeviceManager {
    weak var device: DeviceConvertible?

    func startFindingDevice() {
        guard let device = device as? DeviceFindAPI else {
            print("Device does not support finding")
            return
        }

        device.findDevice { success, error in
            guard success else {
                print("Failed to start finding: \(error?.localizedDescription ?? "Unknown error")")
                return
            }

            print("Locate-device command accepted")
        }
    }
}

デバイス発見イベントを監視する​

デバイスが対応している場合、deviceDidReportFound はデバイス側から通知される独立した完了イベントです。

Swift
/// Called when the device reports that it has been found.
///
/// This is distinct from `findDevice(_:)` completion, which only reports
/// command processing.
func deviceDidReportFound(_ device: DeviceConvertible) {
    DispatchQueue.main.async {
        self.showDeviceFoundState()
    }
}

エラー処理​

コマンドが受理されたと表示する前に success を確認し、コマンドまたは通信の失敗は error で処理します。コマンド処理の成功を「デバイス発見」と表示せず、対応デバイスでは別途通知される発見イベントを待ってください。

ベストプラクティス​

  1. プロトコル対応を確認する: メソッドを呼び出す前に DeviceFindAPI への対応を確認します。
  2. UI の状態を正確に分ける: 「コマンド受理」と「デバイス発見」を区別します。
  3. 停止操作を用意する: 探索通知の開始後は stopFindDevice(_:) を実行できるようにします。
  4. 発見イベントを監視する: 対応デバイスでは、デバイスまたは SDK のデリゲートコールバックを実装します。
  5. メインキューで UI を更新する: 完了ハンドラーやデリゲートコールバックからの UIKit 更新はメインキューへ切り替えます。

注意事項​

  • この API は接続済みデバイスを操作するもので、デバイスの検出やスキャンは行いません。
  • 公開 API は探索通知を定義していますが、デバイスが通知をどのように表現するかは規定していません。
  • 音、振動、継続時間、音量などの動作はデバイスごとに異なる場合があります。
  • iPhone を探す機能は逆方向の処理です。iPhone 発見の通知を参照してください。