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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# 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

104Only one subscription allowed

Indicates that only one client is allowed to subscribe to this method.

105Required 'address' parameter is not supplied

Indicates that the address parameter (a mandatory parameter) was not supplied by the caller of the method.

106Device 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.

131Webos-bluetooth-service is not running

Indicates that Webos-Bluetooth-Service is not running or is not responding (answering).

143Invalid JSON input

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

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

Contents