기기 찾기

Request connected device 시작 its firmware-defined locate-device indication. 이 API locates represented device; it 하지 않습니다 scan 위한 nearby Bluetooth devices.

사전 요구 사항

전에 calling 이 API, ensure:

• 기기 입니다 connected 및 ready
• 기기 supports DeviceFindAPI protocol

API Reference

Framework

AIBuds.xcframework

Import

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

프로토콜

findDevice method 입니다 defined 에서 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

인스턴스 메서드

Requests connected device 시작 its locate-device indication.

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?	선택적 handler called 때 command processing completes.

콜백 Parameters:

이름	타입	설명
success	Bool / BOOL	true 때 기기 accepted command; 그렇지 않으면 false.
error	NSError?	command 또는 communication 오류, 또는 nil on 성공.

반환값

이 method 하지 않습니다 반환 value directly. Its completion 보고서 command processing, 아닌 whether user has physically located 기기.

사용 예제

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

Observe 기기-Found Event

때 지원되는 by 기기, deviceDidReportFound 입니다 distinct, device-originated terminal event:

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 전에 showing command was accepted, 및 사용 error 위한 command 또는 communication failures. 하지 마세요 present successful command processing as “device found”; wait 위한 separate found event 때 기기 supports it.

권장 사항

1. 확인 Protocol Conformance: 검증 DeviceFindAPI support 전에 calling method.
2. 사용 Precise UI State: Distinguish “command accepted” 에서 “device found.”
3. Provide 중지 Action: Make stopFindDevice(_:) 사용 가능한 후에 starting indication.
4. Observe Found Event: Implement 기기 또는 SDK delegate 콜백 때 지원되는.
5. Update UI on 메인 큐: Dispatch UIKit updates 에서 completions 및 delegate 콜백 메인 큐.

참고

• 이 API controls already-connected device 및 하지 않습니다 discover 또는 scan 위한 devices.
• 공개 API defines locate indication but 하지 않습니다 prescribe how device presents it.
• Sound, vibration, duration, 및 volume behavior 할 수 있습니다 be device-specific.
• Find-iPhone 입니다 opposite direction; see Report iPhone Found.