ohos.bluetooth.hfp (Bluetooth HFP Module)

Note:

Currently in the beta phase.

The hfp module provides methods to access Bluetooth call interfaces.

Importing the Module

import kit.ConnectivityKit.*

Permission List

ohos.permission.ACCESS_BLUETOOTH

Usage Instructions

API example code usage instructions:

• If the first line of example code contains a "// index.cj" comment, it indicates that the example can be compiled and run in the "index.cj" file of the Cangjie template project.
• If the example requires obtaining the Context application context, it needs to be configured in the "main_ability.cj" file of the Cangjie template project.

For the above example projects and configuration templates, please refer to Cangjie Example Code Instructions.

func createHfpAgProfile()

public func createHfpAgProfile(): HandsFreeAudioGatewayProfile

Function: Creates an hfp profile instance.

System Capability: SystemCapability.Communication.Bluetooth.Core

Initial Version: 22

Return Value:

Type	Description
HandsFreeAudioGatewayProfile	Returns an instance of this profile.

Example:

// index.cj

import kit.ConnectivityKit.*
import kit.PerformanceAnalysisKit.Hilog
import ohos.business_exception.BusinessException

try {
    let hdfProfile = createHfpAgProfile()
} catch (e: BusinessException) {
    Hilog.info(0, "Bluetooth", "errCode: ${e.code}, errMessage: ${e.message}")
}

class HandsFreeAudioGatewayProfile

public class HandsFreeAudioGatewayProfile <: BaseProfile {}

Function: Before using HandsFreeAudioGatewayProfile methods, you need to create an instance of this class for operations. Construct this instance via the createHfpAgProfile() method.

System Capability: SystemCapability.Communication.Bluetooth.Core

Initial Version: 22

Parent Type:

• BaseProfile

func getConnectedDevices()

public func getConnectedDevices(): Array<String>

Function: Gets the list of connected devices.

Required Permission: ohos.permission.ACCESS_BLUETOOTH

System Capability: SystemCapability.Communication.Bluetooth.Core

Initial Version: 22

Parent Type:

• BaseProfile

Return Value:

Type	Description
Array<String>	Returns the addresses of currently connected devices. For information security considerations, the device address obtained here is a randomized MAC address. This address remains unchanged after successful pairing; however, it will change when a paired device is unpaired and rescanned or when the Bluetooth service is powered off.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes and Bluetooth Service Subsystem Error Codes.

  Error Code ID	Error Message
  201	Permission denied.
  801	Capability not supported.
  2900001	Service stopped.
  2900003	Bluetooth disabled.
  2900004	Profile not supported.
  2900099	Operation failed.

Example:

// index.cj

import kit.ConnectivityKit.*
import kit.PerformanceAnalysisKit.Hilog
import ohos.business_exception.BusinessException

try {
    let hdfProfile = createHfpAgProfile()
    let retArray = hdfProfile.getConnectedDevices()
} catch (e: BusinessException) {
    Hilog.info(0, "Bluetooth", "errCode: ${e.code}, errMessage: ${e.message}")
}

func getConnectionState(String)

public func getConnectionState(deviceId: String): ProfileConnectionState

Function: Gets the connection state of a device profile.

Required Permission: ohos.permission.ACCESS_BLUETOOTH

System Capability: SystemCapability.Communication.Bluetooth.Core

Initial Version: 22

Parameters:

Parameter	Type	Required	Default Value	Description
deviceId	String	Yes	-	Remote device address.

Return Value:

Type	Description
ProfileConnectionState	Returns the connection state of the profile.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes and Bluetooth Service Subsystem Error Codes.

  Error Code ID	Error Message
  201	Permission denied.
  801	Capability not supported.
  2900001	Service stopped.
  2900003	Bluetooth disabled.
  2900004	Profile not supported.
  2900099	Operation failed.

• IllegalArgumentException:

  Error Message	Possible Causes	Handling Steps
  Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.	Incorrect input parameters.	Modify the input parameters.

Example:

// index.cj

import kit.ConnectivityKit.*
import kit.PerformanceAnalysisKit.Hilog
import ohos.business_exception.BusinessException

try {
    let hdfProfile = createHfpAgProfile()
    let ret = hdfProfile.getConnectionState("XX:XX:XX:XX:XX:XX")  // Please replace with your deviceId.
} catch (e: BusinessException) {
    Hilog.info(0, "Bluetooth", "errCode: ${e.code}, errMessage: ${e.message}")
}

func off(ProfileCallbackType, CallbackObject)

public func off(eventType: ProfileCallbackType, callback: CallbackObject): Unit

Function: Unsubscribes from connection state change events.

Required Permission: ohos.permission.ACCESS_BLUETOOTH

System Capability: SystemCapability.Communication.Bluetooth.Core

Initial Version: 22

Parameters:

Parameter	Type	Required	Default Value	Description
eventType	ProfileCallbackType	Yes	-	Callback event type.
callback	CallbackObject	Yes	-	Callback event.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  201	Permission denied.
  801	Capability not supported.

• IllegalArgumentException:

  Error Message	Possible Causes	Handling Steps
  Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.	Incorrect input parameters.	Modify the input parameters.

Example:

// index.cj

import ohos.callback_invoke.*
import ohos.business_exception.*
import kit.ConnectivityKit.*
import kit.PerformanceAnalysisKit.Hilog

// Define required dependencies here
class StateChangeCallback <: Callback1Argument<StateChangeParam> {
    public func invoke(err: ?BusinessException, arg: StateChangeParam): Unit {
        let connectionState = arg.state.toString()
        Hilog.info(0, "Bluetooth", "profile connection state has change to ${connectionState}")
    }
}

let changeCallBack = StateChangeCallback()
let hdfProfile = createHfpAgProfile()
try {
    hdfProfile.on(ProfileCallbackType.ConnectionStateChange, changeCallBack)
    hdfProfile.off(ProfileCallbackType.ConnectionStateChange)
} catch (e: BusinessException) {
    Hilog.info(0, "Bluetooth", "errCode: ${e.code}, errMessage: ${e.message}")
}

func off(ProfileCallbackType)

public func off(eventType: ProfileCallbackType): Unit

Function: Unsubscribes from connection state change events.

Required Permission: ohos.permission.ACCESS_BLUETOOTH

System Capability: SystemCapability.Communication.Bluetooth.Core

Initial Version: 22

Parameters:

Parameter	Type	Required	Default Value	Description
eventType	ProfileCallbackType	Yes	-	Callback event type.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  201	Permission denied.
  801	Capability not supported.

• IllegalArgumentException:

  Error Message	Possible Causes	Handling Steps
  Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.	Incorrect input parameters.	Modify the input parameters.

Example:

// index.cj

import ohos.callback_invoke.*
import ohos.business_exception.*
import kit.ConnectivityKit.*
import kit.PerformanceAnalysisKit.Hilog

// Define required dependencies here
class StateChangeCallback <: Callback1Argument<StateChangeParam> {
    public func invoke(err: ?BusinessException, arg: StateChangeParam): Unit {
        let connectionState = arg.state.toString()
        Hilog.info(0, "Bluetooth", "profile connection state has change to ${connectionState}")
    }
}

let changeCallBack = StateChangeCallback()
let hdfProfile = createHfpAgProfile()
try {
    hdfProfile.on(ProfileCallbackType.ConnectionStateChange, changeCallBack)
    hdfProfile.off(ProfileCallbackType.ConnectionStateChange)
} catch (e: BusinessException) {
    Hilog.info(0, "Bluetooth", "errCode: ${e.code}, errMessage: ${e.message}")
}

func on(ProfileCallbackType, Callback1Argument<StateChangeParam>)

public func on(eventType: ProfileCallbackType, callback: Callback1Argument<StateChangeParam>): Unit

Function: Subscribes to connection state change events. Uses Callback for asynchronous callbacks.

Required Permission: ohos.permission.ACCESS_BLUETOOTH

System Capability: SystemCapability.Communication.Bluetooth.Core

Initial Version: 22

Parameters:

Parameter	Type	Required	Default Value	Description
eventType	ProfileCallbackType	Yes	-	Set to CONNECTIONSTATECHANGE, indicating the connection state change event type.
callback	Callback1Argument<StateChangeParam>	Yes	-	Represents the input parameters of the callback function.

Exceptions:

• BusinessException: Corresponding error codes are listed below. For details, see Universal Error Codes.

  Error Code ID	Error Message
  201	Permission denied.
  801	Capability not supported.

• IllegalArgumentException:

  Error Message	Possible Causes	Handling Steps
  Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.	Incorrect input parameters.	Modify the input parameters.

Example:

// index.cj

import ohos.callback_invoke.*
import ohos.business_exception.*
import kit.ConnectivityKit.*
import kit.PerformanceAnalysisKit.Hilog

// Define required dependencies here
class StateChangeCallback <: Callback1Argument<StateChangeParam> {
    public func invoke(err: ?BusinessException, arg: StateChangeParam): Unit {
        let connectionState = arg.state.toString()
        Hilog.info(0, "Bluetooth", "profile connection state has change to ${connectionState}")
    }
}

let changeCallBack = StateChangeCallback()
let hdfProfile = createHfpAgProfile()
try {
    hdfProfile.on(ProfileCallbackType.ConnectionStateChange, changeCallBack)
} catch (e: BusinessException) {
    Hilog.info(0, "Bluetooth", "errCode: ${e.code}, errMessage: ${e.message}")
}