# Key Service

The Key service provides information about keypresses and other events on the device. Status methods are provided for different types of key events.

## Methods

This section describes the following methods:

- audio/status (volume keys)
- media/status (bluetooth AVRCP keys)
- switches/status (device hard keys)
- headset/status (wired headset keys)

### audio/status

Returns status events for the following keys:

- volume_up
- volume_down

#### Parameters

Parameter | Type | Description
--- | --- | ---
subscribe | boolean | When set to true, the status method returns events indicating each keypress.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | true
key | string | The key.
state | string | Describes the state of the key: up down
subscribed | boolean | Indicates whether the subscription succeeded.

When subscribed, status() returns an update for each key event, in the following format:

Attribute | Type | Description
--- | --- | ---
key | string | The key.
state | string | Describes the state of the key: up down

#### Example

>     this.controller.serviceRequest('palm://com.palm.keys/audio', {
>       method:'status',
>       parameters:{}
>     });

### media/status

Returns status events for the following keys:

- play
- pause
- stop
- next
- prev

#### Parameters

Parameter | Type | Description
--- | --- | ---
subscribe | boolean | When set to true, the status method returns events indicating each keypress.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | true
key | string | The key.
state | string | Describes the state of the key: up down
subscribed | boolean | Indicates whether the subscription succeeded.

When subscribed, status() returns an update for each key event, in the following format:

Attribute | Type | Description
--- | --- | ---
key | string | The key.
state | string | Describes the state of the key: up down

#### Example

>     this.controller.serviceRequest('palm://com.palm.keys/media', {
>       method:'status',
>       parameters:{}
>     });

### switches/status

Returns status events for the following keys:

- ringer
- slider

#### Parameters

Parameter | Type | Description
--- | --- | ---
subscribe | boolean | When set to true, the status method returns events indicating each keypress.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | true
key | string | The key.
state | string | Describes the state of the key: up down
subscribed | boolean | Indicates whether the subscription succeeded.

When subscribed, status() returns an update for each key event, in the following format:

Attribute | Type | Description
--- | --- | ---
key | string | The key.
state | string | Describes the state of the key: up down

#### Example

>     this.controller.serviceRequest('palm://com.palm.keys/switches', {
>       method:'status',
>       parameters:{}
>     });

### headset/status

Returns status events for the following keys:

- headset_button
- headset-mic

#### Parameters

Parameter | Type | Description
--- | --- | ---
subscribe | boolean | When set to true, the status method returns events indicating each keypress.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | true
key | string | The key.
state | string | Describes the state of the key. for headset_button: up down hold single-click double-click for headset-mic up down
subscribed | boolean | Indicates whether the subscription succeeded.

When subscribed, status() returns an update for each key event, in the following format:

Attribute | Type | Description
--- | --- | ---
key | string | The key.
state | string | Describes the state of the key: up down

#### Example

>     this.controller.serviceRequest('palm://com.palm.keys/headset', {
>       method:'status',
>       parameters:{}
>     });