关机

关机操作以编程方式关闭设备。当您需要远程关闭设备或作为受控关机序列的一部分时，此操作非常有用。

前提条件

执行关机前，请确保：

• 设备已连接且处于稳定状态
• 所有未保存的数据已保存
• 用户了解设备在关机后将断开连接

使用 AI 辅助实现

使用 AI 开发

让 AI 帮助实现此工作流

使用官方“实现 AIBuds 关机”技能，根据你的 App 完成实现。

请阅读并遵循 https://docs-aibuds.github.io/zh-Hans/skills/implement-aibuds-power-off，使用该技能在当前 iOS 项目中完成“实现 AIBuds 关机”，并验证结果。

查看官方技能↗

API 参考

框架

AIBuds.xcframework

导入

在要使用 SDK 的文件中，导入主头文件：

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

协议

powerOff 方法定义在以下协议中。该协议继承自基础设备 API 协议。

Swift

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

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

实例方法

以编程方式关闭设备。

iOS 13.0+

Swift

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

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;

参数

参数	类型	描述
completion	AIBudsCompletionHandler?	操作完成时调用的可选完成回调。

回调参数：

名称	类型	描述
success	Bool	操作成功返回 true，否则返回 false。
error	NSError?	如果操作失败则包含错误信息，否则为 nil。

返回值

此方法不直接返回值。结果通过完成回调提供。

使用示例

Swift

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

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

错误处理

完成回调可能返回以下错误类型：

错误域： AIBudsSDK.ErrorDomain

Swift

错误代码	描述	恢复建议
.deviceNotConnected	设备未连接	确保设备已配对并连接
.bleCommandExecFailedDueToTimeout	操作超时	重试操作
.deviceBusy	设备正忙于另一操作	等待正在进行的操作完成
.deviceNotSupport	此设备不支持关机	调用前检查设备功能

Objective-C

错误代码	描述	恢复建议
AIBudsSdkErrorCodeDeviceNotConnected	设备未连接	确保设备已配对并连接
AIBudsSdkErrorCodeBleCommandExecFailedDueToTimeout	操作超时	重试操作
AIBudsSdkErrorCodeDeviceBusy	设备正忙于另一操作	等待正在进行的操作完成
AIBudsSdkErrorCodeDeviceNotSupport	此设备不支持关机	调用前检查设备功能

最佳实践

1. 向用户确认：在启动关机之前，考虑显示确认对话框，因为设备将断开连接。

2. 切换到主线程更新 UI：在完成回调中使用 DispatchQueue.main.async 更新界面。

3. 弱引用 self：在完成回调中使用 [weak self]，避免循环引用。

4. 检查协议支持：调用方法前确认设备支持 DeviceCommonAPI。

5. 处理断开连接：成功关机后，优雅地处理设备断开连接。

注意事项

• 关机命令执行后，设备将断开连接
• 用户可以手动重新打开设备
• 任何正在进行的操作将被中断
• 关机可能需要几秒钟完成