기기 상세 정보 조회

읽기 information currently 사용 가능한 on AIBuds device. Device details 입니다 exposed as properties on 기기 object; there 입니다 no single getDeviceDetails request 또는 DeviceDetails result model.

식별 정보, 펌웨어, 연결 및 광고 정보에는 DeviceConvertible을 사용합니다. 기기가 DeviceInfoAPI도 준수하면 배터리 상태, 보고된 기능, 하드웨어 구성, 언어 설정, 통화 상태, 저장 공간 정보 및 미디어 수를 읽을 수 있습니다.

사전 요구 사항

전에 reading device details:

• Obtain DeviceConvertible instance 에서 your scan, stored-device, 또는 연결 flow.
• Wait until 기기 입니다 connected 및 ready 때 you need latest device-reported values.
• Treat 선택적 properties as 사용할 수 없는 until SDK 또는 device has supplied them.

:::info 현재 snapshot Reading these properties 하지 않습니다 전송 Bluetooth command. values represent SDK's 현재 snapshot 및 may come 에서 discovery data, persisted device data, 또는 information received during active 연결. :::

API Reference

Framework

AIBuds.xcframework

Import

에서 files where you want 사용 SDK, import main framework:

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

프로토콜

Device details 입니다 exposed by two protocols. DeviceConvertible 제공합니다 base device snapshot. DeviceInfoAPI 제공합니다 additional device-information properties 때 connected device supports protocol.

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>

속성

기본 기기 속성

These properties 입니다 사용 가능한 통해 DeviceConvertible.

분류	속성	참고
Identity	name, uuid, bluetoothName, macAddress, product	기기 name 및 identifiers currently known SDK.
Hardware	deviceModel, deviceSerialNum, formatedProjNumber	선택적 values reported by 지원되는 devices.
Firmware	firmwareVersion, formatedFirmwareVersion, coProcessorFirmwareVersion	formatedFirmwareVersion 입니다 display-oriented main firmware string used by Demo.
연결	connectionState, deviceState, isConnectedAndReady, isBusy, lastConnectTime	사용 isConnectedAndReady 전에 relying on live device state.
Binding	bindUserId, userBindTime, isAlreadyUnbind, shouldAutoReconnectWhenAppLaunch	Binding 및 reconnection state maintained by SDK.
Advertisement	advertisementDataString, advertisementRawData, manufacturerData, manufacturerHexDataString, timestampOfAdvertisementData	Values derived 에서 most recently received advertisement data.
Presentation	thumbnail, screenName, customContent	선택적 values 할 수 있습니다 be used by host application UI.

기기 정보 속성

후에 confirming conformance DeviceInfoAPI, following additional snapshot values 입니다 사용 가능한.

속성	타입	설명
batteryStatusInfo	BatteryStatusModel?	Real-time information 위한 기기's battery components.
deviceCapabilities	DeviceCapabilities?	기기가 보고한 정규화된 기능 플래그이며, 유효한 기능 정보를 받기 전에는 nil입니다.
hardwareConfiguration	DeviceHardwareConfiguration	기기가 보고한 물리적 입력 하드웨어 및 기기 내 안내 요구 사항입니다.
languageSetting	DeviceLanguage	현재 device language.
supportedLanguages	[NSNumber]	Raw DeviceLanguage values 지원되는 by 기기.
callStatus	CallStatus	현재 call status.
storageInfo	StorageInfoModel?	Used 및 free 저장 공간 values, 에서 MB.
mediaCountInfo	MediaCountInfoModel?	Photo, video, 및 audio file counts.
isSupportAdjustRecordDuration	Bool	Whether maximum 녹음 duration 할 수 있습니다 be configured.
aiSolutionCapabilities	AIBudsAISolutionCapabilities	AI 지원 기능 reported 위한 기기.
coprocessorModel	CoprocessorModel	기기's co-processor model.
imageEnhancementPostProcessingAlgorithm	ImageEnhancementPostProcessingAlgorithm	기기가 현재 보고한 이미지 향상 후처리 알고리즘이며 기본값은 .general입니다.
recommendedMaxVideoRecordingDurationOptions	[NSNumber]	기기가 권장하는 최대 동영상 녹화 시간 옵션(분)이며 기본값은 [1, 3, 9, 12]입니다.
recommendedMaxAudioRecordingDurationOptions	[NSNumber]	기기가 권장하는 최대 오디오 녹음 시간 옵션(분)이며 기본값은 [30, 60, 120]입니다.
minimumBatteryLevelForMediaOperations	Int	사진, 동영상, 오디오 및 파일 전송에 필요한 최소 배터리 비율이며 기본값은 30입니다. OTA에는 별도 규칙이 적용됩니다.

공통 상태 값

batteryStatusInfo may contain any component 지원되는 by product:

BatteryComponent	의미
.glass	안경 본체
.leftEarbud / .rightEarbud	Left 또는 right earbud
.chargingCase	충전 케이스
.mainSpeaker / .sideSpeaker	Main 또는 side speaker
.headphones	오버이어 헤드폰
.unknown	Component 입니다 사용할 수 없는 또는 unrecognized

deviceCapabilities 필드로 TWS, 공간 오디오, 멀티포인트, ANC, 기기 내 음성 비서, 베이스 엔진, 라이브 스트리밍, Ximalaya 및 공장 테스트용 처프음을 제공할지 결정하세요. product만으로 기능을 추론하지 마세요. nil은 아직 유효한 기능 정보를 받지 못했다는 뜻이며 모든 기능이 지원되지 않는다는 뜻은 아닙니다.

hardwareConfiguration은 제품을 조작하는 방법을 설명합니다.

속성	의미
hasTouchInput	터치 입력 표면이 있습니다.
hasPhysicalButtonInput	물리 버튼 입력이 있습니다.
requiresOnDeviceVoiceAssistantGuidance	호스트 앱에서 기기 내 음성 비서 사용 안내를 제공해야 합니다.

callStatus 사용합니다 CallStatus:

값	의미
.notInCall	No call 입니다 active.
.ringing	incoming call 입니다 ringing.
.inCall	call 입니다 active.
.threeWayRinging	three-way call 입니다 ringing, 때 지원되는.
.aiChat	기기 보고서 AI conversation as its 현재 call-channel activity.
.unknown	Call state 입니다 사용할 수 없는 또는 unrecognized.

사용 예제

읽기 Device Details

following examples follow same approach as SDK Demo's DeviceInfoDetailsController: 읽기 base device properties first, then conditionally include 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;
}

Render returned rows using your application's own view model 및 localization. Demo 사용합니다 table view 및 converts enum values into localized display strings.

Refresh 저장 공간 또는 Media Information

storageInfo 및 mediaCountInfo 입니다 snapshot properties. 만약 your screen 필요합니다 fresh value, request update first 및 then 읽기 corresponding property 후에 operation succeeds.

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

사용 requestQueryMediaCountInfo(_:) 에서 Swift 또는 requestQueryMediaCountInfoWithCompletion: 에서 Objective-C 때 you need refresh mediaCountInfo.

오류 처리

Property access itself 하지 않습니다 반환 asynchronous 오류. Explicit refresh operations 보고서 failures 통해 their completion handlers. Handle 사용할 수 없는 information by:

1. Checking device.isConnectedAndReady 때 live values 입니다 required.
2. Confirming protocol conformance 전에 reading DeviceInfoAPI properties.
3. 모든 기기 모델이 모든 값을 보고한다고 가정하지 말고 선택적 속성을 처리하세요. nil인 deviceCapabilities는 미지원이 아니라 알 수 없음으로 처리하세요.
4. Treating advertisement fields as latest received advertisement snapshot.
5. Handling success 및 error 위한 explicit refresh operations such as 저장 공간 또는 media-count queries.

권장 사항

1. 확인 Protocol Conformance: Confirm DeviceInfoAPI support 전에 reading its extended properties.

2. 보고된 값으로 기능 제어: 제품명이나 하드코딩된 제한 대신 deviceCapabilities의 정규화된 플래그, 권장 녹화·녹음 시간 배열 및 minimumBatteryLevelForMediaOperations를 우선 사용하세요.

3. 값을 스냅샷으로 처리: 모든 속성이 동시에 갱신되었다고 가정하지 마세요.

4. 선택적 값 처리: 임의의 대체 기기 데이터를 만들지 말고 사용할 수 없음 상태를 표시하세요.

5. 필요할 때만 갱신: 화면에 현재 값이 필요할 때 저장 공간 및 미디어 수 쿼리 메서드를 사용하세요.

6. 표시 값 현지화: 제품, 언어, 통화 상태 및 기타 열거형을 사용자용 현지화 텍스트로 변환하세요.

참고

• 기기 기능과 사용 가능한 필드는 제품 및 펌웨어에 따라 다릅니다. DeviceProduct.headphones는 오버이어 헤드폰 제품을, BatteryComponent.headphones는 해당 배터리 항목을 나타냅니다.
• supportedLanguages contains NSNumber values map DeviceLanguage.rawValue.
• StorageInfoModel 보고서 usedSpaceInMB 및 freeSpaceInMB.
• MediaCountInfoModel 보고서 photoCount, videoCount, 및 audioCount.
• Prefer model properties over parsing description 때 your UI needs individual values.