com.webos.service.hfp

API Summary

Provides the HFP service functions in webOS.

Overview of the API

About HFP

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.

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: 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 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.

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

# 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/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: If the adapterAddress is not specified, then the default adapter will be 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.

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

# 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: If the adapterAddress is not specified, then the default adapter will be 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

# 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: If the adapterAddress is not specified, then the default adapter will be 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

# 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: If the adapterAddress is not specified, then the default adapter will be 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

# 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: If the adapterAddress is not specified, then the default adapter will be 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

# 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: If the adapterAddress is not specified, then the default adapter will be 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

# 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: If the adapterAddress is not specified, then the default adapter will be 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

# 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: If the adapterAddress is not specified, then the default adapter will be 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

# 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 : 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
104	Only one subscription allowed	Indicates that only one client is allowed to subscribe to this method.
105	Required 'address' parameter is not supplied	Indicates that the address parameter (a mandatory parameter) was not supplied by the caller of the method.
106	Device with supplied address is not available	Indicates that the remote Bluetooth device with the supplied address is not available in the list of discovered devices to continue the operation of this method.
131	Webos-bluetooth-service is not running	Indicates that Webos-Bluetooth-Service is not running or is not responding (answering).
143	Invalid JSON input	Indicates that the given JSON input has an invalid format and cannot be parsed.
144	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.