Core Basic Features Power Off

Power Off

The power off operation shuts down the device programmatically. This operation is useful when you need to turn off the device remotely or as part of a controlled shutdown sequence.

Prerequisites

Before performing a power off, ensure:

• The device is connected and in a stable state
• Any unsaved data has been saved
• The user understands that the device will disconnect after shutdown

API Reference

Framework

AIBuds.xcframework

Import

In the files where you want to use the SDK, import the main header:

Swift

import AIBuds

Objective-C

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

Protocol

The powerOff method is defined in the following protocol. The protocol inherits from the base device API protocol.

Swift

/// Defines common device operations including power off
protocol DeviceCommonAPI: DeviceAPI {
    /// Power off the device
    /// - Parameters:
    ///   - completion: Completion callback that returns the operation result
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func powerOff(_ completion: AIBudsCompletionHandler?)
}

Objective-C

/// Defines common device operations including power off
@protocol AIBudsDeviceCommonAPI <AIBudsDeviceAPI>
    /// Power off the device
    /// - Parameters:
    ///   - completion: Completion callback that returns the operation result
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    - (void)powerOffWithCompletion:(AIBudsCompletionHandler)completion;
@end

Instance Method

Powers off the device programmatically.

iOS 13.0+

Swift

/// Power off the device
/// - Parameters:
///   - completion: Completion callback that returns the operation result
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func powerOff(_ completion: AIBudsCompletionHandler?)

Objective-C

/// Power off the device
/// - Parameters:
///   - completion: Completion callback that returns the operation result
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
- (void)powerOffWithCompletion:(AIBudsCompletionHandler)completion;

Parameters

Parameter	Type	Description
completion	AIBudsCompletionHandler?	Optional completion callback that is called when the operation completes.

Callback Parameters:

Name	Type	Description
success	Bool	true if the operation succeeded, false otherwise.
error	NSError?	Contains error information if the operation failed, nil otherwise.

Return Value

This method does not return a value directly. The result is provided through the completion callback.

Usage Examples

Swift

import AIBuds

class DeviceManager {

    /// The connected device
    weak var device: DeviceConvertible?

    /// Powers off the connected device
    func powerOffDevice() {
        // Ensure the device supports power off protocol
        guard let device = device as? DeviceCommonAPI else {
            print("Device does not support power off")
            return
        }

        // Execute power off with completion handler
        device.powerOff { [weak self] success, error in
            // Handle failure case
            if !success {
                let errorMessage = {
                    if let error = error {
                        return "\(error)"
                    }
                    return "Unknown error"
                }()
                print("Power off failed: \(errorMessage)")
                return
            }
            // Handle success case
            print("Power off command sent successfully")
        }
    }
}

Objective-C

#import <AIBuds/AIBuds.h>

@interface DeviceManager ()

/// The connected device
@property (weak, nonatomic) id<AIBudsDeviceConvertible> device;

@end

@implementation DeviceManager

- (void)powerOffDevice {
    __weak typeof(self) weakSelf = self;

    id<AIBudsDeviceCommonAPI> device = (id<AIBudsDeviceCommonAPI>)self.device;
    // Ensure the device supports power off protocol
    if ([device conformsToProtocol:@protocol(AIBudsDeviceCommonAPI)]) {
        // Execute power off with completion handler
        [device powerOffWithCompletion:^(BOOL success, NSError * _Nullable error) {
            // Handle failure case
            if (!success) {
                NSLog(@"Power off failed: %@", error);
                return;
            }
            // Handle success case
            NSLog(@"Power off command sent successfully");
        }];
    }
}

@end

Error Handling

The completion handler may return the following error types:

Error Domain: AIBudsSDK.ErrorDomain

Swift

Error Code	Description	Recovery Suggestion
.deviceNotConnected	Device is not connected	Ensure device is paired and connected
.bleCommandExecFailedDueToTimeout	Operation timed out	Retry the operation
.deviceBusy	Device is busy with another operation	Wait for ongoing operations to complete
.deviceNotSupport	Power off is not supported on this device	Check device capabilities before calling

Objective-C

Error Code	Description	Recovery Suggestion
AIBudsSdkErrorCodeDeviceNotConnected	Device is not connected	Ensure device is paired and connected
AIBudsSdkErrorCodeBleCommandExecFailedDueToTimeout	Operation timed out	Retry the operation
AIBudsSdkErrorCodeDeviceBusy	Device is busy with another operation	Wait for ongoing operations to complete
AIBudsSdkErrorCodeDeviceNotSupport	Power off is not supported on this device	Check device capabilities before calling

Best Practices

1. Confirm with User: Consider displaying a confirmation dialog before initiating power off, as the device will disconnect.

2. Handle Background Execution: Wrap the completion handler in a DispatchQueue.main.async block when updating UI.

3. Weak Self Reference: Use [weak self] in the completion handler to prevent retain cycles.

4. Check Protocol Conformance: Verify the device conforms to DeviceCommonAPI protocol before calling the method.

5. Handle Disconnection: After a successful power off, handle the device disconnection gracefully.

Notes

• The device will disconnect after the power off command is executed
• The device can be turned back on manually by the user
• Any ongoing operations will be interrupted
• Power off may take a few seconds to complete