Core Physical Operations View Operation Mapping

View Operation Mapping

Read the mapping between physical device operations and assigned device functions.

Prerequisites

• The device is connected and ready
• The device supports DevicePhysicalOperationsAPI

API Reference

Framework

AIBuds.xcframework

Import

Swift

import AIBuds

Objective-C

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

Protocol

The mapping is exposed as a property of DevicePhysicalOperationsAPI.

Swift

/// The protocol for device physical operations API.
protocol DevicePhysicalOperationsAPI: DeviceAPI {
    /// Physical operations with functions mapping
    /// - Returns: A dictionary mapping physical operation identifiers to function identifiers.
    ///
    /// The dictionary is structured as follows:
    /// - Keys: Physical operation identifiers. Defined in ``DeviceOperation``.
    /// - Values: Function identifiers. Defined in ``DeviceFunction``.
    var physicalOperationsMapping: [NSNumber: NSNumber]? { get }
}

Objective-C

/// The protocol for device physical operations API.
@protocol AIBudsDevicePhysicalOperationsAPI <AIBudsDeviceAPI>
    /// Physical operations with functions mapping
    /// - Returns: A dictionary mapping physical operation identifiers to function identifiers.
    ///
    /// The dictionary is structured as follows:
    /// - Keys: Physical operation identifiers. Defined in ``DeviceOperation``.
    /// - Values: Function identifiers. Defined in ``DeviceFunction``.
    @property (nonatomic, readonly, copy) NSDictionary<NSNumber *, NSNumber *> * _Nullable physicalOperationsMapping;
@end

Properties

Property	Type	Description
physicalOperationsMapping	[NSNumber: NSNumber]?	Maps each DeviceOperation raw value to a DeviceFunction raw value.

Return Value

This is a read-only optional property, not an asynchronous query method.

Usage Examples

Swift

import AIBuds

guard let device = device as? DevicePhysicalOperationsAPI else {
    print("Device does not support physical-operation mapping")
    return
}

guard let mapping = device.physicalOperationsMapping else {
    print("Mapping is unavailable")
    return
}

for (operationValue, functionValue) in mapping {
    let operation = DeviceOperation(rawValue: operationValue.intValue)
    let function = DeviceFunction(rawValue: functionValue.intValue)
    print("\(String(describing: operation)) → \(String(describing: function))")
}

Objective-C

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

id<AIBudsDevicePhysicalOperationsAPI> device =
    (id<AIBudsDevicePhysicalOperationsAPI>)self.device;

if (![device conformsToProtocol:@protocol(AIBudsDevicePhysicalOperationsAPI)]) {
    NSLog(@"Device does not support physical-operation mapping");
    return;
}

[device.physicalOperationsMapping enumerateKeysAndObjectsUsingBlock:^(
    NSNumber *operation,
    NSNumber *function,
    BOOL *stop
) {
    NSLog(@"Operation %@ → function %@", operation, function);
}];

Error Handling

The property has no completion handler. Handle unsupported protocol conformance, a nil mapping, and raw values that do not initialize known enum cases.

Best Practices

1. Treat Values as Enum Raw Values: Convert keys and values through DeviceOperation and DeviceFunction.
2. Do Not Infer Missing Entries: A missing operation is not documented as supported.
3. Refresh UI After Assignment: Re-read the property after a successful assignment if the device updates it.

Notes

• The SDK Demo reads this property directly and sorts entries by operation raw value for display.
• The property does not use a Result callback or a KeyMapping model.