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:

  1. 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.
     
  2. Power on your Bluetooth device, and put it in the pairing mode.
     
  3. 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"}'
     
  4. 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}'
     
  5. 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}'
     
  6. 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}'
     
  7. 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

subscribeOptionalBoolean

Indicates if subscribed to get notifications.

Possible values are:

  • true: Subscribed for notifications
  • false: Not subscribed 

Default: false

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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

Indicates if subscribed to get notifications.

Possible values are:

  • true: Subscribed for notifications.
  • false: Not subscribed.
audioGatewaysRequiredObject array: audioGateway

Contains the information about each connected AG device in an array.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

Subscription Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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

Indicates if subscribed to get notifications.

Possible values are:

  • true: Subscribed for notifications.
  • false: Not subscribed.
audioGatewaysRequiredObject array: audioGateway

Contains the information about each AG device connected in an array.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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, 144See 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

adapterAddressOptionalString

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

Indicates the address of the remote device (AG).

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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

The error code for the failed operation.

errorTextOptionalString

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, 144See API Error Codes Reference

See the "API Error Codes Reference" section for more details.

151answerCall 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

addressRequiredString

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

adapterAddressOptionalString

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

Indicates the call to terminate.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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

The error code for the failed operation.

errorTextOptionalString

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, 144See API Error Codes Reference.

See the "API Error Codes Reference" section.

152terminateCall 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

addressRequiredString

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

adapterAddressOptionalString

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

returnValueRequiredBoolean

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

The error code for the failed operation.

errorTextOptionalString

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, 144See 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

addressRequiredString

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

adapterAddressOptionalString

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

returnValueRequiredBoolean

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

The error code for the failed operation.

errorTextOptionalString

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, 144See 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

addressRequiredString

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

indexOptionalNumber

Indicates the index of a specific call to be active.

adapterAddressOptionalString

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

returnValueRequiredBoolean

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

Indicates the index of a specific call to be active.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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, 144See 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

addressRequiredString

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

adapterAddressOptionalString

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

returnValueRequiredBoolean

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

The error code for the failed operation.

errorTextOptionalString

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, 144See 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

addressRequiredString

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

adapterAddressOptionalString

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

Indicates the phone number to be dialed.

memoryDialingOptionalNumber

Indicates the last stored number(used in the previous call) that can be used for memory dialing.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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

The error code for the failed operation.

errorTextOptionalString

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, 144See 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

addressRequiredString

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

volumeRequiredNumber

Indicates the SCO volume (level to be set).

Possible range: [0 - 15].

adapterAddressOptionalString

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

returnValueRequiredBoolean

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

The error code for the failed operation.

errorTextOptionalString

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, 144See 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

addressRequiredString

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

adapterAddressRequiredString

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.

callStatusRequiredString

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).
indexRequiredNumber

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.

directionRequiredString

Indicates the direction of the call.

Possible values are:

  • outgoing
  • incoming
numberRequiredString

Indicates the number of the incoming or outgoing call.

signalRequiredNumber

Indicates the signal strength of the remote device (AG).

Possible range: 0 ~ 5.

batteryRequiredNumber

Indicates the battery capacity of the remote device (AG).

Possible range: 0 ~ 5.

volumeRequiredNumber

Indicates the SCO volume of the remote device (AG). 

Possible range: 0 ~ 15.

scoRequiredBoolean

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

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
operatorNameRequiredString

Indicates the current operator name.

API Error Codes Reference

Error Code

Error Text

Error Description

1Invalid JSON input

Indicates that the given JSON input has an invalid format and cannot be parsed.

2The 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.

3Required 'subscribed' parameter not supplied

Indicates that method is only subscription call, subscribe parameter should be supplied

5Required 'adapterAddress' parameter not supplied

Adapter address is required, it is not supplied in parameters

6Required '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

9Required 'address' parameter not supplied

Required 'address' parameter not supplied

10The range of 'volume' parameter is from 0 to 15.

The range of 'volume' parameter is from 0 to 15.

12Required 'volume' paramter not supplied

Required 'volume' paramter not supplied

13Required 'enabled' parameter not supplied

Required 'enabled' parameter not supplied

14Device with supplied address is not connected

Device with supplied address is not connected

15No voice call to answer

Incoming voice call is not present to answer

16Answer call failed

Answer call failed due to internal error in telephony stack

17Terminate call failed

Terminate call failed due to internal telephony stack error

18VoiceCall Index is missing

Voice call 'Index' parameter is missing

19No voice call found

No voice call found to terminate call

20Adapter is not available

Adapter mentioned in parameter is not available

21No active voice call

No active voice call present for this operation (Eg. merging call or holding call etc)

22No waiting voice call

No waiting voice call for method holdActiveCalls and releaseActiveCalls

23No voice call on hold

No voice call on hold for releaseHeldCalls and mergeCall

24Merge voice call failed

Merge voice call failed due to error in telephony stack

25Hold Active Call failed

Hold Active Call failed due to error in telephony stack

26Release Active voice call failed

Release Active voice call failed due to error in telephony stack

Contents