xref: /interface/sdk-js/api/@ohos.bluetooth.access.d.ts

/*
 * Copyright (C) 2023-2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file
 * @kit ConnectivityKit
 */

import type { AsyncCallback, Callback } from './@ohos.base';

/**
 * Provides methods for enabling/disabling bluetooth or monitoring bluetooth state.
 *
 * @namespace access
 * @syscap SystemCapability.Communication.Bluetooth.Core
 * @since 10
 */
/**
 * Provides methods for enabling/disabling bluetooth or monitoring bluetooth state.
 *
 * @namespace access
 * @syscap SystemCapability.Communication.Bluetooth.Core
 * @atomicservice
 * @since 11
 */
/**
 * Provides methods for enabling/disabling bluetooth or monitoring bluetooth state.
 *
 * @namespace access
 * @syscap SystemCapability.Communication.Bluetooth.Core
 * @crossplatform
 * @atomicservice
 * @since 13
 */
declare namespace access {
  /**
   * Enables Bluetooth on a device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @since 10
   */
  /**
   * Enables Bluetooth on a device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @atomicservice
   * @since 12
   */
  /**
   * Enables Bluetooth on a device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @crossplatform
   * @atomicservice
   * @since 13
   */
  function enableBluetooth(): void;

  /**
   * Disables Bluetooth on a device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @since 10
   */
  /**
   * Disables Bluetooth on a device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @atomicservice
   * @since 12
   */
  /**
   * Disables Bluetooth on a device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @crossplatform
   * @atomicservice
   * @since 13
   */
  function disableBluetooth(): void;

  /**
   * Restrict Bluetooth BR/EDR ability on a device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
   * @returns { Promise<void> } Promise that returns no value.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @systemapi
   * @since 12
   */
  function restrictBluetooth(): Promise<void>;

  /**
   * Obtains the Bluetooth status of a device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @returns { BluetoothState } Returns the Bluetooth status.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @since 10
   */
  /**
   * Obtains the Bluetooth status of a device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @returns { BluetoothState } Returns the Bluetooth status.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @atomicservice
   * @since 11
   */
  /**
   * Obtains the Bluetooth status of a device.
   *
   * @returns { BluetoothState } Returns the Bluetooth status.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @crossplatform
   * @atomicservice
   * @since 13
   */
  function getState(): BluetoothState;

  /**
   * Restoring bluetooth settings.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
   * @param { AsyncCallback<void> } callback - Callback used to return the result.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
   * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
   * <br>2. Incorrect parameter types.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @systemapi
   * @since 11
   */
  function factoryReset(callback: AsyncCallback<void>): void;

  /**
   * Restoring bluetooth settings.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
   * @returns { Promise<void> } Promise that returns no value.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @systemapi
   * @since 11
   */
  function factoryReset(): Promise<void>;

  /**
   * Obtaining the MAC address of the local device.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.GET_BLUETOOTH_LOCAL_MAC
   * @returns { string } The local MAC address. For example, "11:22:33:AA:BB:FF".
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900001 - Service stopped.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @systemapi
   * @since 11
   */
  function getLocalAddress(): string;

  /**
   * Subscribe the event reported when the Bluetooth state changes.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for.
   * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
   * <br>2. Incorrect parameter types. 3. Parameter verification failed.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @since 10
   */
  /**
   * Subscribe the event reported when the Bluetooth state changes.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for.
   * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
   * <br>2. Incorrect parameter types. 3. Parameter verification failed.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @atomicservice
   * @since 12
   */
  /**
   * Subscribe the event reported when the Bluetooth state changes.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for.
   * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
   * <br>2. Incorrect parameter types. 3. Parameter verification failed.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @crossplatform
   * @atomicservice
   * @since 13
   */
  function on(type: 'stateChange', callback: Callback<BluetoothState>): void;

  /**
   * Unsubscribe the event reported when the Bluetooth state changes.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for.
   * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
   * <br>2. Incorrect parameter types. 3. Parameter verification failed.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @since 10
   */
  /**
   * Unsubscribe the event reported when the Bluetooth state changes.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for.
   * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
   * <br>2. Incorrect parameter types. 3. Parameter verification failed.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @atomicservice
   * @since 12
   */
  /**
   * Unsubscribe the event reported when the Bluetooth state changes.
   *
   * @permission ohos.permission.ACCESS_BLUETOOTH
   * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for.
   * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event.
   * @throws { BusinessError } 201 - Permission denied.
   * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
   * <br>2. Incorrect parameter types. 3. Parameter verification failed.
   * @throws { BusinessError } 801 - Capability not supported.
   * @throws { BusinessError } 2900099 - Operation failed.
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @crossplatform
   * @atomicservice
   * @since 13
   */
  function off(type: 'stateChange', callback?: Callback<BluetoothState>): void;

  /**
   * The enum of bluetooth state.
   *
   * @enum { number }
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @since 10
   */
  /**
   * The enum of bluetooth state.
   *
   * @enum { number }
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @atomicservice
   * @since 11
   */
  /**
   * The enum of bluetooth state.
   *
   * @enum { number }
   * @syscap SystemCapability.Communication.Bluetooth.Core
   * @crossplatform
   * @atomicservice
   * @since 13
   */
  export enum BluetoothState {
    /**
     * Indicates the local Bluetooth is off
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @since 10
     */
    /**
     * Indicates the local Bluetooth is off
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @atomicservice
     * @since 11
     */
    /**
     * Indicates the local Bluetooth is off
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @crossplatform
     * @atomicservice
     * @since 13
     */
    STATE_OFF = 0,
    /**
     * Indicates the local Bluetooth is turning on
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @since 10
     */
    /**
     * Indicates the local Bluetooth is turning on
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @atomicservice
     * @since 11
     */
    /**
     * Indicates the local Bluetooth is turning on
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @crossplatform
     * @atomicservice
     * @since 13
     */
    STATE_TURNING_ON = 1,
    /**
     * Indicates the local Bluetooth is on, and ready for use
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @since 10
     */
    /**
     * Indicates the local Bluetooth is on, and ready for use
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @atomicservice
     * @since 11
     */
    /**
     * Indicates the local Bluetooth is on, and ready for use
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @crossplatform
     * @atomicservice
     * @since 13
     */
    STATE_ON = 2,
    /**
     * Indicates the local Bluetooth is turning off
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @since 10
     */
    /**
     * Indicates the local Bluetooth is turning off
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @atomicservice
     * @since 11
     */
    /**
     * Indicates the local Bluetooth is turning off
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @crossplatform
     * @atomicservice
     * @since 13
     */
    STATE_TURNING_OFF = 3,
    /**
     * Indicates the local Bluetooth is turning LE mode on
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @since 10
     */
    /**
     * Indicates the local Bluetooth is turning LE mode on
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @atomicservice
     * @since 11
     */
    STATE_BLE_TURNING_ON = 4,
    /**
     * Indicates the local Bluetooth is in LE only mode
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @since 10
     */
    /**
     * Indicates the local Bluetooth is in LE only mode
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @atomicservice
     * @since 11
     */
    STATE_BLE_ON = 5,
    /**
     * Indicates the local Bluetooth is turning off LE only mode
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @since 10
     */
    /**
     * Indicates the local Bluetooth is turning off LE only mode
     *
     * @syscap SystemCapability.Communication.Bluetooth.Core
     * @atomicservice
     * @since 11
     */
    STATE_BLE_TURNING_OFF = 6
  }
}

export default access;