डिवाइस विवरण पाएँ

AIBuds डिवाइस पर अभी उपलब्ध जानकारी पढ़ें। Device details, device object की properties के रूप में मिलते हैं; कोई एक getDeviceDetails request या DeviceDetails result model नहीं है।

Identity, firmware, connection और advertisement जानकारी के लिए DeviceConvertible उपयोग करें। डिवाइस DeviceInfoAPI के अनुरूप भी हो तो battery status, बताई गई capabilities, hardware configuration, language setting, call status, storage information और media counts पढ़ सकते हैं।

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

डिवाइस विवरण पढ़ने से पहले:

• Scan, stored-device या connection workflow से DeviceConvertible instance पाएँ।
• नवीनतम device-reported values चाहिए हों तो डिवाइस के connected और ready होने की प्रतीक्षा करें।
• SDK या डिवाइस से value मिलने तक optional properties को unavailable मानें।

:::info मौजूदा snapshot इन properties को पढ़ने पर Bluetooth command नहीं भेजा जाता। Values SDK का मौजूदा snapshot हैं और discovery data, persisted device data या active connection के दौरान मिली जानकारी से आ सकते हैं। :::

API संदर्भ

फ्रेमवर्क

AIBuds.xcframework

Import

SDK उपयोग करने वाली files में main framework import करें:

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

प्रोटोकॉल

Device details दो protocols से मिलते हैं। DeviceConvertible base device snapshot देता है। जुड़ा डिवाइस support करे तो DeviceInfoAPI अतिरिक्त device-information properties देता है।

Swift

Swift

/// Defines the persistent identity and capabilities of an AIBuds device.
protocol DeviceConvertible: NSObjectProtocol, NSSecureCoding

/// The protocol for device information related API.
protocol DeviceInfoAPI: DeviceAPI

Objective-C

Objective-C

/// Defines the persistent identity and capabilities of an AIBuds device.
@protocol AIBudsDeviceConvertible <NSSecureCoding, NSObject>

/// The protocol for device information related API.
@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>

प्रॉपर्टीज़

Base device प्रॉपर्टीज़

ये properties DeviceConvertible के माध्यम से उपलब्ध हैं।

श्रेणी	Properties	विवरण
Identity	name, uuid, bluetoothName, macAddress, product	SDK को अभी ज्ञात device name और identifiers।
Hardware	deviceModel, deviceSerialNum, formatedProjNumber	समर्थित डिवाइस द्वारा दी गई optional values।
Firmware	firmwareVersion, formatedFirmwareVersion, coProcessorFirmwareVersion	formatedFirmwareVersion Demo में उपयोग होने वाली display-oriented main firmware string है।
Connection	connectionState, deviceState, isConnectedAndReady, isBusy, lastConnectTime	Live device state पर निर्भर होने से पहले isConnectedAndReady जाँचें।
Binding	bindUserId, userBindTime, isAlreadyUnbind, shouldAutoReconnectWhenAppLaunch	SDK द्वारा रखी गई binding और reconnection state।
Advertisement	advertisementDataString, advertisementRawData, manufacturerData, manufacturerHexDataString, timestampOfAdvertisementData	सबसे हाल में मिले advertisement data से निकली values।
Presentation	thumbnail, screenName, customContent	Host app UI में उपयोग की जा सकने वाली optional values।

डिवाइस जानकारी की properties

DeviceInfoAPI conformance की पुष्टि के बाद ये अतिरिक्त snapshot values उपलब्ध होती हैं।

Property	प्रकार	विवरण
batteryStatusInfo	BatteryStatusModel?	डिवाइस के battery components की real-time जानकारी।
deviceCapabilities	DeviceCapabilities?	डिवाइस द्वारा बताई गई normalized capability flags; valid जानकारी मिलने तक nil।
hardwareConfiguration	DeviceHardwareConfiguration	डिवाइस द्वारा बताई गई physical input hardware और on-device guidance requirements।
languageSetting	DeviceLanguage	डिवाइस की मौजूदा भाषा।
supportedLanguages	[NSNumber]	डिवाइस द्वारा supported raw DeviceLanguage values।
callStatus	CallStatus	मौजूदा call status।
storageInfo	StorageInfoModel?	उपयोग हुई और खाली storage, MB में।
mediaCountInfo	MediaCountInfoModel?	Photo, video और audio file counts।
isSupportAdjustRecordDuration	Bool	Maximum recording duration configure की जा सकती है या नहीं।
aiSolutionCapabilities	AIBudsAISolutionCapabilities	डिवाइस द्वारा बताई गई AI capabilities।
coprocessorModel	CoprocessorModel	डिवाइस का co-processor model।
imageEnhancementPostProcessingAlgorithm	ImageEnhancementPostProcessingAlgorithm	डिवाइस द्वारा बताया गया मौजूदा image-enhancement post-processing algorithm; default .general।
recommendedMaxVideoRecordingDurationOptions	[NSNumber]	सुझाए गए maximum video-recording duration विकल्प, मिनट में; default [1, 3, 9, 12]।
recommendedMaxAudioRecordingDurationOptions	[NSNumber]	सुझाए गए maximum audio-recording duration विकल्प, मिनट में; default [30, 60, 120]।
minimumBatteryLevelForMediaOperations	Int	Photo, video, audio और file transfer के लिए minimum battery percentage; default 30। OTA के नियम अलग हैं।

सामान्य status values

batteryStatusInfo में product द्वारा supported कोई भी component हो सकता है:

BatteryComponent	अर्थ
.glass	चश्मे का मुख्य भाग
.leftEarbud / .rightEarbud	बायाँ या दायाँ earbud
.chargingCase	चार्जिंग केस
.mainSpeaker / .sideSpeaker	Main या side speaker
.headphones	कान को ढकने वाले हेडफ़ोन
.unknown	Component unavailable या पहचाना नहीं गया

TWS, spatial audio, multipoint, ANC, on-device voice assistant, bass engine, live streaming, Ximalaya और factory-test chirp उपलब्ध कराने का निर्णय deviceCapabilities fields से लें। इन सुविधाओं का अनुमान केवल product से न लगाएँ। nil का अर्थ है कि valid capability जानकारी अभी नहीं मिली है; इसका अर्थ सभी सुविधाओं का unsupported होना नहीं है।

hardwareConfiguration बताता है कि product को कैसे चलाया जा सकता है:

Property	अर्थ
hasTouchInput	Touch input surface मौजूद है।
hasPhysicalButtonInput	Physical button input मौजूद है।
requiresOnDeviceVoiceAssistantGuidance	Host app को on-device voice assistant उपयोग करने की guidance देनी चाहिए।

callStatus, CallStatus उपयोग करता है:

Value	अर्थ
.notInCall	कोई call active नहीं है।
.ringing	Incoming call की ring बज रही है।
.inCall	Call active है।
.threeWayRinging	समर्थित होने पर three-way call की ring बज रही है।
.aiChat	डिवाइस मौजूदा call-channel activity को AI conversation बताता है।
.unknown	Call state unavailable या पहचानी नहीं गई।

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

डिवाइस विवरण पढ़ें

ये examples SDK Demo के DeviceInfoDetailsController जैसा तरीका अपनाते हैं: पहले base device properties पढ़ें, फिर उपलब्ध होने पर DeviceInfoAPI properties जोड़ें।

Swift

Swift

import AIBuds

typealias DeviceDetail = (label: String, value: String)

func formattedDate(_ date: Date?, unavailable: String) -> String {
    guard let date else { return unavailable }

    let formatter = DateFormatter()
    formatter.dateStyle = .medium
    formatter.timeStyle = .medium
    return formatter.string(from: date)
}

func deviceDetails(for device: DeviceConvertible) -> [DeviceDetail] {
    let unavailable = "N/A"
    var details: [DeviceDetail] = [
        ("Device Name", device.name),
        ("UUID", device.uuid.uuidString),
        ("Bluetooth Name", device.bluetoothName ?? unavailable),
        ("MAC Address", device.macAddress ?? unavailable),
        ("Product", String(describing: device.product)),
        ("Device Model", device.deviceModel ?? unavailable),
        ("Serial Number", device.deviceSerialNum ?? unavailable),
        ("Firmware Version", device.formatedFirmwareVersion ?? unavailable),
        ("Co-processor Firmware", device.coProcessorFirmwareVersion ?? unavailable),
        ("Project Number", device.formatedProjNumber ?? unavailable),
        ("Last Connection", formattedDate(device.lastConnectTime, unavailable: unavailable)),
        ("Auto Reconnect", device.shouldAutoReconnectWhenAppLaunch ? "Yes" : "No"),
        ("Advertisement Data", device.advertisementDataString ?? unavailable),
        ("Manufacturer Data", device.manufacturerHexDataString ?? unavailable),
        (
            "Advertisement Timestamp",
            formattedDate(device.timestampOfAdvertisementData, unavailable: unavailable)
        ),
        ("Screen Name", device.screenName ?? unavailable),
        ("Custom Content", device.customContent ?? unavailable),
    ]

    guard let info = device as? DeviceInfoAPI else {
        return details
    }

    let supportedLanguages = info.supportedLanguages
        .compactMap { DeviceLanguage(rawValue: $0.intValue) }
        .map { String(describing: $0) }
        .joined(separator: ", ")

    details.append(contentsOf: [
        ("Battery Status", info.batteryStatusInfo?.description ?? unavailable),
        ("Device Capabilities", info.deviceCapabilities?.description ?? unavailable),
        ("Hardware Configuration", info.hardwareConfiguration.description),
        ("Language", String(describing: info.languageSetting)),
        ("Supported Languages", supportedLanguages.isEmpty ? unavailable : supportedLanguages),
        ("Call Status", String(describing: info.callStatus)),
        ("Storage", info.storageInfo?.description ?? unavailable),
        ("Media Count", info.mediaCountInfo?.description ?? unavailable),
        ("Adjustable Recording Duration", info.isSupportAdjustRecordDuration ? "Yes" : "No"),
        ("AI Capabilities", String(describing: info.aiSolutionCapabilities)),
        ("Co-processor Model", String(describing: info.coprocessorModel)),
        (
            "Image Enhancement",
            String(describing: info.imageEnhancementPostProcessingAlgorithm)
        ),
        ("Recommended Video Duration Options", info.recommendedMaxVideoRecordingDurationOptions.description),
        ("Recommended Audio Duration Options", info.recommendedMaxAudioRecordingDurationOptions.description),
        ("Minimum Media Battery", "\(info.minimumBatteryLevelForMediaOperations)%"),
    ])

    return details
}

Objective-C

Objective-C

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

- (NSArray<NSDictionary<NSString *, NSString *> *> *)deviceDetailsForDevice:
    (id<AIBudsDeviceConvertible>)device {
    NSString *unavailable = @"N/A";
    NSMutableArray<NSDictionary<NSString *, NSString *> *> *details = [NSMutableArray array];

    void (^addDetail)(NSString *, id _Nullable) = ^(NSString *label, id _Nullable value) {
        [details addObject:@{
            @"label" : label,
            @"value" : value ? [value description] : unavailable,
        }];
    };

    addDetail(@"Device Name", device.name);
    addDetail(@"UUID", device.uuid.UUIDString);
    addDetail(@"Bluetooth Name", device.bluetoothName);
    addDetail(@"MAC Address", device.macAddress);
    addDetail(@"Product", @(device.product));
    addDetail(@"Device Model", device.deviceModel);
    addDetail(@"Serial Number", device.deviceSerialNum);
    addDetail(@"Firmware Version", device.formatedFirmwareVersion);
    addDetail(@"Co-processor Firmware", device.coProcessorFirmwareVersion);
    addDetail(@"Project Number", device.formatedProjNumber);
    addDetail(@"Last Connection", device.lastConnectTime);
    addDetail(@"Auto Reconnect", device.shouldAutoReconnectWhenAppLaunch ? @"Yes" : @"No");
    addDetail(@"Advertisement Data", device.advertisementDataString);
    addDetail(@"Manufacturer Data", device.manufacturerHexDataString);
    addDetail(@"Advertisement Timestamp", device.timestampOfAdvertisementData);
    addDetail(@"Screen Name", device.screenName);
    addDetail(@"Custom Content", device.customContent);

    id<AIBudsDeviceInfoAPI> info = (id<AIBudsDeviceInfoAPI>)device;
    if ([info conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
        addDetail(@"Battery Status", info.batteryStatusInfo);
        addDetail(@"Device Capabilities", info.deviceCapabilities);
        addDetail(@"Hardware Configuration", info.hardwareConfiguration);
        addDetail(@"Language", @(info.languageSetting));
        addDetail(@"Supported Languages", info.supportedLanguages);
        addDetail(@"Call Status", @(info.callStatus));
        addDetail(@"Storage", info.storageInfo);
        addDetail(@"Media Count", info.mediaCountInfo);
        addDetail(@"Adjustable Recording Duration",
                  info.isSupportAdjustRecordDuration ? @"Yes" : @"No");
        addDetail(@"AI Capabilities", @(info.aiSolutionCapabilities));
        addDetail(@"Co-processor Model", @(info.coprocessorModel));
        addDetail(@"Image Enhancement", @(info.imageEnhancementPostProcessingAlgorithm));
        addDetail(@"Recommended Video Duration Options", info.recommendedMaxVideoRecordingDurationOptions);
        addDetail(@"Recommended Audio Duration Options", info.recommendedMaxAudioRecordingDurationOptions);
        addDetail(@"Minimum Media Battery",
                  [NSString stringWithFormat:@"%ld%%",
                                             (long)info.minimumBatteryLevelForMediaOperations]);
    }

    return details;
}

Returned rows को ऐप के view model और localization से render करें। Demo table view उपयोग करता है और enum values को localized display strings में बदलता है।

Storage या media जानकारी refresh करें

storageInfo और mediaCountInfo snapshot properties हैं। Screen को नवीनतम value चाहिए तो पहले update request करें और operation सफल होने के बाद संबंधित property पढ़ें।

Swift

Swift

guard let info = device as? DeviceInfoAPI else { return }

info.requestQueryStorageInfo { success, error in
    guard success else {
        print(error?.localizedDescription ?? "Storage query failed")
        return
    }

    print(info.storageInfo?.description ?? "Storage information is unavailable")
}

Objective-C

Objective-C

id<AIBudsDeviceInfoAPI> info = (id<AIBudsDeviceInfoAPI>)self.device;
if ([info conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
    [info requestQueryStorageInfoWithCompletion:^(BOOL success, NSError *_Nullable error) {
        if (!success) {
            NSLog(@"Storage query failed: %@", error.localizedDescription);
            return;
        }

        NSLog(@"%@", info.storageInfo);
    }];
}

Swift में requestQueryMediaCountInfo(_:) या Objective-C में requestQueryMediaCountInfoWithCompletion: उपयोग करके mediaCountInfo refresh करें।

Error handling

Property access स्वयं asynchronous error नहीं देता। Explicit refresh operations failures को completion handlers से बताते हैं। Unavailable जानकारी को इस तरह संभालें:

1. Live values चाहिए हों तो device.isConnectedAndReady जाँचें।
2. DeviceInfoAPI properties पढ़ने से पहले protocol conformance की पुष्टि करें।
3. यह माने बिना optional properties संभालें कि हर model हर value देगा; nil वाले deviceCapabilities को unsupported नहीं बल्कि unknown मानें।
4. Advertisement fields को सबसे हाल में मिला advertisement snapshot मानें।
5. Storage या media-count query जैसे explicit refresh operations में success और error संभालें।

बेहतर तरीके

1. Protocol conformance जाँचें: Extended properties पढ़ने से पहले DeviceInfoAPI support की पुष्टि करें।

2. Reported values से features तय करें: Product name या hard-coded limits के बजाय deviceCapabilities की normalized flags, recommended recording durations और minimumBatteryLevelForMediaOperations उपयोग करें।

3. Values को snapshot मानें: यह न मानें कि हर property एक ही समय refresh हुई है।

4. Optional values संभालें: काल्पनिक fallback data बनाने के बजाय unavailable state दिखाएँ।

5. ज़रूरत पर ही refresh करें: Screen को current values चाहिए हों तभी storage और media-count query methods उपयोग करें।

6. Display values localize करें: Products, languages, call status और अन्य enums को user-facing localized text में बदलें।

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

• Device capabilities और उपलब्ध fields product तथा firmware के अनुसार बदलते हैं। DeviceProduct.headphones over-ear headphones product को और BatteryComponent.headphones उसकी battery entry को दर्शाता है।
• supportedLanguages में NSNumber values होती हैं, जो DeviceLanguage.rawValue से map होती हैं।
• StorageInfoModel, usedSpaceInMB और freeSpaceInMB देता है।
• MediaCountInfoModel, photoCount, videoCount और audioCount देता है।
• UI को अलग-अलग values चाहिए हों तो description parse करने के बजाय model properties उपयोग करें।