com.webos.service.hfp

Note
This API has been available since API level 12.

API Summary

Provides the HFP service functions in webOS.

Overview of the API

Hands-Free Profile (HFP) describes how a gateway device can be used to place and receive calls for a hand-free device. A common scenario would be a car kit in your vehicle. The car kit would connect to your mobile phone and be used to place and receive calls. Even more common would be the use of your wireless headset to place and receive calls when connected to a mobile phone.

The HFP service defines two roles:

Audio Gateway (AG): The device that is the gateway of the audio, both for input and output, typically a mobile phone.
Hands-Free unit (HF): The device acting as the Audio Gateway's remote audio input and output mechanism. It also provides some remote control means.

HFP service (com.webos.service.hfp) supports the main features of AG and HF. For example, monitoring or controlling call-related apps or services such as telephony, audio, call, etc.

To reduce system and device dependency, Bluetooth2 service (com.webos.service.bluetooth2) also provides a set of methods for HFP (com.webos.service.bluetooth2/hfp/*). It simply supports Bluetooth communication between AT commands and result codes. The methods can be called by com.webos.service.hfp.

Prerequisites

Before calling any method provided in the 'com.webos.service.hfp' service, you must do the following:

Get a list of the available adapter addresses.
# luna-send -i -f luna://com.webos.service.bluetooth2/adapter/getStatus '{"subscribe": true}'
Note: This step is needed only when default adapter address is not going to be used.
Power on your Bluetooth device, and put it in the pairing mode.
Start discovering devices that are available for connection to that adapter.
# luna-send -n 1 -f luna://com.webos.service.bluetooth2/adapter/startDiscovery '{"adapterAddress": "00:1a:7d:da:71:0a"}'
Get a list of available bluetooth devices and note down the address of the required device.
# luna-send -i -f luna://com.webos.service.bluetooth2/device/getStatus '{"adapterAddress": "00:1a:7d:da:71:0a","subscribe": true}'
Pair to selected bluetooth device (HFP).
# luna-send -i -f luna://com.webos.service.bluetooth2/adapter/pair '{ "adapterAddress": "00:1a:7d:da:71:0a","address": "98:09:cf:15:4e:67", "subscribe":true}'
Connect the HFP device.
# luna-send -i -f luna://com.webos.service.bluetooth2/hfp/connect '{ "adapterAddress": "00:1a:7d:da:71:0a","address": "98:09:cf:15:4e:67", "subscribe":true}'
Call any one of the HFP API.

Methods

hf/answerCall

ACG: bluetooth.management

Added: API level 12

Description

Answers the incoming call from the given AG.

Parameters

Name	Required	Type	Description
adapterAddress	Optional	String	Indicates the address of the adapter to be used in the case of multiple adapters. Note: If the adapterAddress is not specified, then the default adapter will be used. If the service is part of a container session, do not specify adapterAddress. Based on the session, by default, a pre-selected adapterAddress is used.
address	Required	String	Indicates the address of the remote device (AG).

Name

Required

Type

Description

adapterAddress

Optional

String

Indicates the address of the adapter to be used in the case of multiple adapters.

Note:

If the adapterAddress is not specified, then the default adapter will be used.
If the service is part of a container session, do not specify adapterAddress. Based on the session, by default, a pre-selected adapterAddress is used.

address

Required

String

Indicates the address of the remote device (AG).

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "Error Codes" section for more details.

Error Codes Reference

Error Code	Error Text	Error Description
105, 106, 131, 143, 144	See API Error Codes Reference	See the "API Error Codes Reference" section for more details.
151	answerCall is Failed	The device has failed to answer the incoming call.

Example

Example code

Check prerequisites in the 'Overview of the API' section.

# luna-send -n 1 -f luna://com.webos.service.hfp/hf/answerCall '{

"address":"00:18:6b:49:db:86"
}'

Response:

{
"returnValue":true
}

hf/call

ACG: bluetooth.management

Added: API level 12

Description

Dials the previous phone number (stored after the previous call) using the memory dialing.

Memory dialing: A telephone feature that allows placing a call by accessing a previously stored number.

Note:

If the number and the memoryDialing parameter are passed simultaneously, an error will be returned.
If none of the number and the memoryDialing parameter is passed, AG may place a call to the latest outgoing number (depends on AG).

Parameters

Name	Required	Type	Description
address	Required	String	Indicates the address (bdaddr) of the remote device (AG).
adapterAddress	Optional	String	Indicates the address of the adapter to be used in the case of multiple adapters. Note: If the adapterAddress is not specified, then the default adapter will be used. If the service is part of a container session, do not specify adapterAddress. Based on the session, by default, a pre-selected adapterAddress is used.
number	Optional	String	Indicates the phone number to be dialed.
memoryDialing	Optional	Number	Indicates the last stored number(used in the previous call) that can be used for memory dialing.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed.Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "Error Codes" section for more details.

Error Codes Reference

Error Code	Error Text	Error Description
104, 106, 131, 143, 144	See API Error Codes Reference	See the "API Error Codes Reference" section for more details.

Example

Example code

Check prerequisites in the 'Overview of the API' section.

# luna-send -n 1 -f luna://com.webos.service.hfp/hf/call '{
"address":"00:18:6b:49:db:86"
}'

Response:

{
"returnValue":true
}

hf/getStatus

ACG: bluetooth.query

Added: API level 12

Description

Returns the current status of the connected AG devices.

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Indicates if subscribed to get notifications. Possible values are: true: Subscribed for notifications false: Not subscribed Default: false

Name

Required

Type

Description

Optional

Boolean

Indicates if subscribed to get notifications.

Possible values are:

true: Subscribed for notifications
false: Not subscribed

Default: false

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are : true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
subscribed	Required	Boolean	Indicates if subscribed to get notifications. Possible values are: true: Subscribed for notifications. false: Not subscribed.
audioGateways	Required	Object array: audioGateway	Contains the information about each connected AG device in an array.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section for more details.

Subscription Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed.Check the "errorCode" and "errorText" fields for details.
subscribed	Required	Boolean	Indicates if subscribed to get notifications. Possible values are: true: Subscribed for notifications. false: Not subscribed.
audioGateways	Required	Object array: audioGateway	Contains the information about each AG device connected in an array.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section for more details.

Error Codes Reference

Error Code	Error Text	Error Description
104, 131, 143, 144	See API Error Codes Reference	See the "API Error Codes Reference" section for more details.

Example

Example code

Check prerequisites in the 'Overview of the API' section.

# luna-send -n 1 -f luna://com.webos.service.hfp/hf/getStatus '{
"subscribe":false
}'

Response:

{
"returnValue":true,
"subscribed":true,
"audioGateways":[
{
"address":"00:18:6b:49:db:86",
"callSatus":"incomming ",
"index":1,
"direction":"incoming",
"number":"010 - 1234 -4321",
"signal":3,
"battery":3,
"volume":7,
"sco":false
}
]
}

Subscription response:

hf/holdActiveCalls

ACG: bluetooth.management

Added: API level 12

Description

Places all the active calls (if any exist) on hold and answers another (held or waiting) call.

Parameters

Name

Required

Type

Description

address

Required

String

Indicates the address (bdaddr) of the remote device (AG).

index

Optional

Number

Indicates the index of a specific call to be active.

adapterAddress

Optional

String

Indicates the address of the adapter to be used in the case of multiple adapters.

Note:

If the adapterAddress is not specified, then the default adapter will be used.
If the service is part of a container session, do not specify adapterAddress. Based on the session, by default, a pre-selected adapterAddress is used.

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
index	Required	Number	Indicates the index of a specific call to be active.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section for more details.

Error Codes Reference

Error Code	Error Text	Error Description
104, 106, 131, 143, 144	See API Error Codes Reference	See the "API Error Codes Reference" section for more details.

Example

Example code

Check prerequisites in the 'Overview of the API' section.

# luna-send -n 1 -f luna://com.webos.service.hfp/hf/holdActiveCalls '{
"address":"00:18:6b:49:db:86"
}'

Response:

{
"returnValue":true,
"index":0
}

hf/mergeCall

ACG: bluetooth.management

Added: API level 12

Description

Adds a held call to the conversation ( merging calls into a conference call ).

Parameters

Name

Required

Type

Description

address

Required

String

Indicates the address (bdaddr) of the remote device (AG).

adapterAddress

Optional

String

Indicates the address of the adapter to be used in the case of multiple adapters.

Note:

If the adapterAddress is not specified, then the default adapter will be used.
If the service is part of a container session, do not specify adapterAddress. Based on the session, by default, a pre-selected adapterAddress is used.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "Error Codes" section for more details.

Error Codes Reference

Error Code	Error Text	Error Description
104, 106, 131, 143, 144	See API Error Codes Reference	See the "API Error Codes Reference" section for more details.

Example

Example code

Check prerequisites in the 'Overview of the API' section.

# luna-send -n 1 -f luna://com.webos.service.hfp/hf/mergeCall '{
"address":"00:18:6b:49:db:86"
}'

Response:

{
"returnValue":true
}

hf/releaseActiveCalls

ACG: bluetooth.management

Added: API level 12

Description

Releases all the active and answers the waiting call of the given AG.

Parameters

Name

Required

Type

Description

address

Required

String

Indicates the address (bdaddr) of the remote device (AG).

adapterAddress

Optional

String

Indicates the address of the adapter to be used in the case of multiple adapters.

Note:

If the adapterAddress is not specified, then the default adapter will be used.
If the service is part of a container session, do not specify adapterAddress. Based on the session, by default, a pre-selected adapterAddress is used.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "Error Codes" section for more details.

Error Codes Reference

Error Code	Error Text	Error Description
104, 106, 131, 143, 144	See API Error Codes Reference	See the "API Error Codes Reference" section for more details.

Example

Example code

Check prerequisites in the 'Overview of the API' section.

# luna-send -n 1 -f luna://com.webos.service.hfp/hf/releaseHeldCalls '{
"address":"00:18:6b:49:db:86"
}'

Response:

{
"returnValue":true
}

hf/releaseHeldCalls

ACG: bluetooth.management

Added: API level 12

Description

Releases all the held calls of the given AG.

Parameters

Name

Required

Type

Description

address

Required

String

Indicates the address (bdaddr) of the remote device (AG).

adapterAddress

Optional

String

Indicates the address of the adapter to be used in the case of multiple adapters.

Note:

If the adapterAddress is not specified, then the default adapter will be used.
If the service is part of a container session, do not specify adapterAddress. Based on the session, by default, a pre-selected adapterAddress is used.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for more details.

Error Codes Reference

Error Code	Error Text	Error Description
104, 106, 131, 143, 144	See API Error Codes Reference	See the "API Error Codes Reference" section for more details.

Example

Example code

Check prerequisites in the 'Overview of the API' section.

# luna-send -n 1 -f luna://com.webos.service.hfp/hf/releaseHeldCalls '{
"address":"00:18:6b:49:db:86"
}'

Response:

{
"returnValue":true
}

hf/setVolume

ACG: bluetooth.management

Added: API level 12

Description

Sets the SCO volume level.

Parameters

Name

Required

Type

Description

address

Required

String

Indicates the address (bdaddr) of the remote device (AG).

volume

Required

Number

Indicates the SCO volume (level to be set).

Possible range: [0 - 15].

adapterAddress

Optional

String

Indicates the address of the adapter to be used in the case of multiple adapters.

Note:

If the adapterAddress is not specified, then the default adapter will be used.
If the service is part of a container session, do not specify adapterAddress. Based on the session, by default, a pre-selected adapterAddress is used.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "Error Codes" section for more details.

Error Codes Reference

Error Code	Error Text	Error Description
104, 106, 131, 143, 144	See API Error Codes Reference	See the "API Error Codes Reference" section for more details.

Example

Example code

Check prerequisites in the 'Overview of the API' section.

# luna-send -n 1 -f luna://com.webos.service.hfp/hf/setVolume '{
"address":"00:18:6b:49:db:86",
"volume":7
}'

Response:

{
"returnValue":true
}

hf/terminateCall

ACG: bluetooth.management

Added: API level 12

Description

Terminates the active call with the given AG.

Parameters

Name

Required

Type

Description

address

Required

String

Indicates the address (bdaddr) of the remote device (AG).

adapterAddress

Optional

String

Indicates the address of the adapter to be used in the case of multiple adapters.

Note:

If the adapterAddress is not specified, then the default adapter will be used.
If the service is part of a container session, do not specify adapterAddress. Based on the session, by default, a pre-selected adapterAddress is used.

index

Required

Number

Indicates the call to terminate.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

Error Codes Reference

Error Code	Error Text	Error Description
105, 106, 131, 143, 144	See API Error Codes Reference.	See the "API Error Codes Reference" section.
152	terminateCall is failed	Failed to terminate the call.

Example

Example code

Check prerequisites in the 'Overview of the API' section.

# luna-send -n 1 -f luna://com.webos.service.hfp/hf/terminateCall '{

"address":"00:18:6b:49:db:86",
"adapterAddress":"5c:f3:70:94:25:d4",
"index":1
}'

Response:

{
"returnValue":true
}

Objects

audioGateway

Contains the information about the connected AG device.

Name	Required	Type	Description
address	Required	String	Indicates the address (bdaddr) of the remote device (AG).
adapterAddress	Required	String	Indicates the address of the adapter to be used in the case of multiple adapters. Note: If the adapterAddress is not specified, then the default adapter will be used.
callStatus	Required	String	Indicates the status of the call. Possible values are : active: the call is active. held: the call is on hold. dialing: the call is being dialed (only for the outgoing call). waiting: the call is on wait (only for a 3-way call). call held by the response and hold. alerting (only for outgoing).
index	Required	Number	Indicates the number assigned to each call when setting up or receiving a call. Each call holds the index number until it is released. Index starts at 1. A new call takes the lowest available number. Refer to HFP 1.6 specification document for more information.
direction	Required	String	Indicates the direction of the call. Possible values are: outgoing incoming
number	Required	String	Indicates the number of the incoming or outgoing call.
signal	Required	Number	Indicates the signal strength of the remote device (AG). Possible range: 0 ~ 5.
battery	Required	Number	Indicates the battery capacity of the remote device (AG). Possible range: 0 ~ 5.
volume	Required	Number	Indicates the SCO volume of the remote device (AG). Possible range: 0 ~ 15.
sco	Required	Boolean	Indicates the SCO connection between the local and the remote device. Possible values are: true: The SCO is connected between local and remote device. false: The SCO connection is closed between the local and the remote device.
networkStatus	Required	String	Indicates the current registration status of the modem. Possible values are: unregistered: Not registered to any network registered: Registered to home network searching: Not registered, but searching denied: Registration has been denied unknown: Status is unknown roaming: Registered, but roaming
operatorName	Required	String	Indicates the current operator name.

API Error Codes Reference

Error Code	Error Text	Error Description
1	Invalid JSON input	Indicates that the given JSON input has an invalid format and cannot be parsed.
2	The JSON input does not match the expected schema	Indicates that one or more of the parameters do not have the correct parameter type. See the 'Parameters' table to know the expected data type for each input parameter. Note: Any required parameter missing will be a different error return based on the missing key.
3	Required 'subscribed' parameter not supplied	Indicates that method is only subscription call, subscribe parameter should be supplied
5	Required 'adapterAddress' parameter not supplied	Adapter address is required, it is not supplied in parameters
6	Required 'devices' parameter not supplied	Required 'devices' parameter not supplied
8	'address' parameter is invalid	Indicates that the remote Bluetooth device with the supplied address is not proper
9	Required 'address' parameter not supplied	Required 'address' parameter not supplied
10	The range of 'volume' parameter is from 0 to 15.	The range of 'volume' parameter is from 0 to 15.
12	Required 'volume' paramter not supplied	Required 'volume' paramter not supplied
13	Required 'enabled' parameter not supplied	Required 'enabled' parameter not supplied
14	Device with supplied address is not connected	Device with supplied address is not connected
15	No voice call to answer	Incoming voice call is not present to answer
16	Answer call failed	Answer call failed due to internal error in telephony stack
17	Terminate call failed	Terminate call failed due to internal telephony stack error
18	VoiceCall Index is missing	Voice call 'Index' parameter is missing
19	No voice call found	No voice call found to terminate call
20	Adapter is not available	Adapter mentioned in parameter is not available
21	No active voice call	No active voice call present for this operation (Eg. merging call or holding call etc)
22	No waiting voice call	No waiting voice call for method holdActiveCalls and releaseActiveCalls
23	No voice call on hold	No voice call on hold for releaseHeldCalls and mergeCall
24	Merge voice call failed	Merge voice call failed due to error in telephony stack
25	Hold Active Call failed	Hold Active Call failed due to error in telephony stack
26	Release Active voice call failed	Release Active voice call failed due to error in telephony stack