전원 끄기

전원 끄기 작업은 프로그래밍 방식으로 기기를 종료합니다. 원격으로 기기를 끄거나 제어된 종료 시퀀스의 일부로 사용해야 할 때 이 작업이 유용합니다.

전제 조건

전원을 끄기 전에 다음을 확인하세요：

• 기기가 연결되어 안정적인 상태임
• 저장되지 않은 모든 데이터가 저장됨
• 사용자가 종료 후 기기가 연결 해제됨을 이해함

AI를 활용해 구현

AI로 구현

AI로 이 워크플로 구현

공식 “AIBuds 전원 끄기” 스킬을 사용해 앱에 맞게 구현하세요.

https://docs-aibuds.github.io/ko/skills/implement-aibuds-power-off을 읽고 지침을 따르세요. 이 스킬로 “AIBuds 전원 끄기”을 이 iOS 프로젝트에 구현하고 검증하세요.

공식 스킬 보기↗

API 참조

Framework

AIBuds.xcframework

Import

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 15.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 업데이트하기: 완료 핸들러에서 UI를 변경할 때는 DispatchQueue.main.async를 사용하세요.

3. 약한 참조 사용하기: 순환 참조를 방지하려면 완료 핸들러에서 [weak self]를 사용하세요.

4. 프로토콜 지원 확인하기: 메서드를 호출하기 전에 기기가 DeviceCommonAPI를 준수하는지 확인하세요.

5. 연결 해제 처리하기: 전원 끄기에 성공한 뒤 발생하는 연결 해제를 앱에서 적절히 처리하세요.

참고 사항

• 전원 끄기 명령을 실행하면 기기 연결이 해제됩니다
• 사용자가 기기의 전원을 수동으로 다시 켤 수 있습니다
• 진행 중인 작업은 중단됩니다
• 전원이 꺼질 때까지 몇 초 정도 걸릴 수 있습니다