डिवाइस ढूँढें

जुड़े डिवाइस से firmware-defined locate indication शुरू करने का अनुरोध करें। यह API उसी जुड़े डिवाइस को ढूँढता है; आस-पास के Bluetooth डिवाइस scan नहीं करता।

पहले की आवश्यकताएँ

यह API call करने से पहले सुनिश्चित करें:

• डिवाइस connected और ready है
• डिवाइस DeviceFindAPI protocol का समर्थन करता है

API संदर्भ

फ्रेमवर्क

AIBuds.xcframework

Import

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

प्रोटोकॉल

findDevice method, 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

Instance method

जुड़े डिवाइस से locate 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?	Command processing पूरा होने पर call होने वाला optional handler।

Callback पैरामीटर:

नाम	प्रकार	विवरण
success	Bool / BOOL	डिवाइस ने command स्वीकार किया हो तो true, अन्यथा false।
error	NSError?	Command या communication error; सफल होने पर nil।

Return value

यह method सीधे कोई value return नहीं करता। Completion command processing बताता है, यह नहीं कि उपयोगकर्ता को डिवाइस वास्तव में मिल गया।

उपयोग के उदाहरण

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

डिवाइस मिलने का event observe करें

डिवाइस द्वारा समर्थित होने पर deviceDidReportFound डिवाइस से आने वाला अलग 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];
    });
}

Error handling

Command accepted दिखाने से पहले success जाँचें और command या communication failure के लिए error उपयोग करें। सफल command processing को “डिवाइस मिल गया” न दिखाएँ; समर्थित डिवाइस पर अलग found event की प्रतीक्षा करें।

बेहतर तरीके

1. Protocol conformance जाँचें: Method call करने से पहले DeviceFindAPI support की पुष्टि करें।
2. सटीक UI state रखें: “Command स्वीकार हुआ” और “डिवाइस मिल गया” को अलग दिखाएँ।
3. रोकने का action दें: Indication शुरू होने के बाद stopFindDevice(_:) उपलब्ध रखें।
4. Found event observe करें: समर्थित होने पर device या SDK delegate callback लागू करें।
5. UI को main queue पर अपडेट करें: Completions और delegate callbacks से UIKit updates main queue पर भेजें।

ध्यान देने योग्य बातें

• यह API पहले से जुड़े डिवाइस को नियंत्रित करता है; डिवाइस discover या scan नहीं करता।
• Public API locate indication परिभाषित करता है, लेकिन डिवाइस उसे कैसे दिखाएगा यह तय नहीं करता।
• ध्वनि, vibration, अवधि और volume का व्यवहार डिवाइस के अनुसार अलग हो सकता है।
• Find-iPhone विपरीत दिशा वाला workflow है; iPhone मिलने की सूचना दें देखें।