com.webos.service.hfp
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/getStatus
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:
Default: false |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation. Possible values are :
|
| subscribed | Required | Boolean | Indicates if subscribed to get notifications. Possible values are:
|
| 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:
|
| subscribed | Required | Boolean | Indicates if subscribed to get notifications. Possible values are:
|
| 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
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:
{
"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
}
]
}
hf/answerCall
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:
|
| 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:
|
| 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
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/terminateCall
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:
|
| 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:
|
| 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
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
}
hf/releaseHeldCalls
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:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
| 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
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/releaseActiveCalls
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:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
| 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
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/holdActiveCalls
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:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
| 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
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
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:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
| 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
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/call
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:
|
| 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:
|
| 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
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/setVolume
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:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
| 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
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
}
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 :
|
| 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:
|
| 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:
|
| networkStatus | Required | String | Indicates the current registration status of the modem. Possible values are:
|
| 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 |