停止查找设备

请求已连接设备停止由固件定义的查找提示。

前置条件

调用此 API 前，请确保：

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

API 参考

框架

AIBuds.xcframework

导入

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

协议

stopFindDevice 方法定义在 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.
public protocol DeviceFindAPI: DeviceAPI {
    /// Requests that the connected device stop its locate-device indication.
    /// - Parameters:
    ///   - completion: Called when command processing completes.
    ///     - success: `true` when the device accepted the stop command;
    ///       otherwise, `false`.
    ///     - error: The command or communication error, or `nil` on success.
    func stopFindDevice(_ completion: AIBudsCompletionHandler?)
}

Objective-C

Objective-C

/// Controls the locate-device indication on a connected device.
@protocol AIBudsDeviceFindAPI <AIBudsDeviceAPI>
/// Requests that the connected device stop its locate-device indication.
/// - Parameters:
///   - completion: Called when command processing completes.
///     - success: `true` when the device accepted the stop command;
///       otherwise, `false`.
///     - error: The command or communication error, or `nil` on success.
- (void)stopFindDeviceWithCompletion:(AIBudsCompletionHandler _Nullable)completion;
@end

实例方法

请求已连接设备停止查找提示。

Swift

Swift

/// Requests that the connected device stop its locate-device indication.
/// - Parameters:
///   - completion: Called when command processing completes.
///     - success: `true` when the device accepted the stop command; otherwise,
///       `false`.
///     - error: The command or communication error, or `nil` on success.
func stopFindDevice(_ completion: AIBudsCompletionHandler?)

Objective-C

Objective-C

/// Requests that the connected device stop its locate-device indication.
/// - Parameters:
///   - completion: Called when command processing completes.
///     - success: `true` when the device accepted the stop command; otherwise,
///       `false`.
///     - error: The command or communication error, or `nil` on success.
- (void)stopFindDeviceWithCompletion:(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 stopFindingDevice() {
        guard let device = device as? DeviceFindAPI else {
            print("Device does not support finding")
            return
        }

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

            print("Stop 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 stopFindDeviceWithCompletion:^(BOOL success, NSError *_Nullable error) {
    if (!success) {
        NSLog(@"Failed to stop finding: %@", error.localizedDescription ?: @"Unknown error");
        return;
    }

    NSLog(@"Stop command accepted");
}];

错误处理

先检查 success 再显示停止命令已接受；命令或通信失败时读取 error。不要假设目标设备文档未明确说明的固定错误码。

最佳实践

1. 检查协议支持：调用方法前确认设备支持 DeviceFindAPI。
2. 在本地维护 UI 状态：该协议未提供用于报告查找是否活动的属性。
3. 在主队列更新 UI：将完成回调中的 UIKit 更新派发到主队列。

注意事项

• 公开 API 未定义查找未活动时调用停止的结果。
• 设备特定的查找提示不属于该 API 契约。
• 此操作只停止设备侧提示，不会停止 iPhone 侧的“查找 iPhone”提醒；该提醒由宿主 App 负责。