查找设备

请求已连接设备启动由固件定义的查找提示。该 API 用于查找当前设备，不扫描附近的蓝牙设备。

前置条件

调用此 API 前，请确保：

• 设备已连接且就绪。
• 设备支持 DeviceFindAPI 协议。

API 参考

框架

AIBuds.xcframework

导入

Swift

Swift

import AIBuds

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

协议

findDevice 方法定义在 DeviceFindAPI 中。

Swift

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

Objective-C

Objective-C

/// 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. A
/// successful completion means command acceptance, not physical location.
@protocol AIBudsDeviceFindAPI <AIBudsDeviceAPI>
/// Requests that the connected device start its locate-device indication.
///
/// The completion reports command processing. A supported device reports
/// the terminal found event separately through the device or SDK delegate.
/// - 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.
- (void)findDeviceWithCompletion:(AIBudsCompletionHandler _Nullable)completion;
@end

实例方法

请求已连接设备启动查找提示。

Swift

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

Objective-C

Objective-C

/// Requests that the connected device start its locate-device indication.
///
/// The completion reports command processing. A supported device reports the
/// terminal found event separately through the device or SDK delegate.
/// - 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.
- (void)findDeviceWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

参数

参数	类型	描述
completion	AIBudsCompletionHandler?	命令处理完成时调用的可选回调。

回调参数：

名称	类型	描述
success	Bool / BOOL	设备接受命令时为 true，否则为 false。
error	NSError?	命令或通信错误；成功时为 nil。

返回值

该方法不直接返回值。完成回调报告命令处理结果，不表示用户已实际找到设备。

使用示例

Swift

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

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

id<AIBudsDeviceFindAPI> device = (id<AIBudsDeviceFindAPI>)self.device;
if (![device conformsToProtocol:@protocol(AIBudsDeviceFindAPI)]) {
    NSLog(@"Device does not support finding");
    return;
}

[device findDeviceWithCompletion:^(BOOL success, NSError *_Nullable error) {
    if (!success) {
        NSLog(@"Failed to start finding: %@", error.localizedDescription ?: @"Unknown error");
        return;
    }

    NSLog(@"Locate-device command accepted");
}];

监听设备已找到事件

设备支持时，deviceDidReportFound 是由设备发起的独立结束事件：

Swift

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

Objective-C

Objective-C

/// Called when the device reports that it has been found.
///
/// This is distinct from the find command completion, which only reports
/// command processing.
- (void)deviceDidReportFound:(id<AIBudsDeviceConvertible>)device {
    dispatch_async(dispatch_get_main_queue(), ^{
        [self showDeviceFoundState];
    });
}

错误处理

先检查 success 再显示命令已接受；命令或通信失败时读取 error。不要将命令处理成功显示为“设备已找到”；设备支持时，应等待独立的已找到事件。

最佳实践

1. 检查协议支持：调用方法前确认设备支持 DeviceFindAPI。
2. 使用准确的 UI 状态：区分“命令已接受”和“设备已找到”。
3. 提供停止操作：启动提示后提供 stopFindDevice(_:) 操作。
4. 监听已找到事件：设备支持时，实现设备或 SDK 代理回调。
5. 在主队列更新 UI：将完成回调和代理回调中的 UIKit 更新派发到主队列。

注意事项

• 该 API 控制已连接设备，不执行设备发现或扫描。
• 公开 API 定义了查找提示，但未规定设备如何呈现。
• 声音、振动、持续时间和音量行为可能因设备而异。
• 查找 iPhone 是相反方向的流程；请参阅报告已找到 iPhone。