# System Services

The system exposes a general set of services enabling applications to access various system settings. It is part of the System Manager and is available only when the UI is running. The following types of methods are available:

- Preferences
- Time
- Wallpaper

## Preferences Methods

This section describes the following methods:

- getPreferences
- getPreferenceValues
- setPreferences

### getPreferences

The getPreferences method retrieves the values for preferences keys specified in the passed array. If subscribe is set to true, then getPreferences sends an update any time the values of the keys change.

Required parameter:

- keys

#### Parameters

Parameter | Type | Description
--- | --- | ---
keys | array | An array of keys for which to retrieve values.
subscribe | boolean | If true, getPreferences sends an update whenever the value of one of the keys changes.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
{no name} | JSON object | Key-value pairs containing the values for the requested preferences. If the requested preferences key or keys do not exist, the object is empty.

onFailure

No onFailure callback is required.

#### Example

>     this.controller.serviceRequest('palm://com.palm.systemservice', {
>       method:"getPreferences",
>       parameters:{"keys":["locale"]},
>       onSuccess: myCallback,
>       onFailure: myFailureCallback
>     });

The above call returns the following, for example:

>     { "locale": { "languageCode": "en", "countryCode": "us" } }

### getPreferenceValues

Retrieve the list of valid values for the specified key. If the key is of a type that takes one of a discrete set of valid values, getPreferenceValues returns that set. For example, calling getPreferences on timeFormat returns "HH12" and "HH24". Otherwise, getPreferenceValues returns nothing for the key.

Required parameter:

- key

#### Parameters

Parameter | Type | Description
--- | --- | ---
key | text | The key for which to retrieve valid values.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
{no name} | JSON object | The key and the valid values.

onFailure

No return value.

#### Example

>     this.controller.serviceRequest('palm://com.palm.systemservice', {
>       method:"getPreferenceValues",
>       parameters:{"key":"timeFormat" },
>       onSuccess: myCallback,
>       onFailure: myFailureCallback
>     });

The above call returns the following JSON object:

>     { "timeFormat": [ "HH12", "HH24" ] }

### setPreferences

Sets preference keys to specified values.

Required parameter:

- params

#### Parameters

Parameter | Type | Description
--- | --- | ---
params | JSON object | An object containing one or more key-value pairs.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (true) Indicates whether the call was successful.

onFailure

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (false) Indicates whether the call was successful.
errorText | string | Text describing the reason the call failed.

#### Example

>     this.controller.serviceRequest('palm://com.palm.systemservice', {
>       method:"setPreferences",
>       parameters:{"food":"pizza"},
>       onSuccess: myCallback,
>       onFailure: myFailureCallback
>     });

## Time Method

This section describes the following method:

- getSystemTime

### getSystemTime

Requests the system time, and if the subscribe property is true, receives notifications when the time zone changes and/or the system time changes by a significant amount (currently 5 min.).

For info about world time zones, see Wikipedia®.

Required parameter:

- subscribe

#### Parameters

Parameter | Type | Description
--- | --- | ---
subscribe | boolean | If true, receives notifications when the time zone changes and/or the system time changes by a system-defined threshold (currently 5 min.).

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
localtime | object | The time and date for the current time zone. The format is: "year":, "month":, "day":, "hour":, "minute":, "second": Where: year: the year (i.e., 2009) month: the calendar number of the month (i.e., from 1 for January to 12 for December) day: the calendar number of the day (i.e., from 1 for the first day of the month to 28, 29, 30, or 31, depending on the month) hour: 24-hour time format (i.e., from 0 for midnight to 23 for 11 P.M.) minute: standard range of 0-59 second: standard range of 0-59
offset | integer | The number of minutes from UTC. This can be negative for time zones west of UTC and positive for time zones east of UTC.
timezone | string | The current system time zone. It has the same format as the " TZ " environment variable. For information, see http://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html .
TZ | string | The time zone abbreviation in standard Unix format that corresponds to the current time zone (e.g., PDT (Pacific Daylight Time)).
utc | integer | The number of seconds since Unix Epoch (midnight of January 1, 1970 UTC).

onFailure

The function always succeeds, providing that com.palm.systemservice is running.

#### Example

>     this.controller.serviceRequest('palm://com.palm.systemservice/time', {
>       method:"getSystemTime",
>       parameters:{},
>       onSuccess: myCallback,
>       onFailure: myFailureCallback
>     });

## Wallpaper Methods

This section describes the following methods:

- wallpaper/importWallpaper
- wallpaper/refresh
- wallpaper/info
- wallpaper/deleteWallpaper

The Wallpaper API lets your application change (or detect) the wallpaper (the image that appears on the screen behind the Launcher or Card view).

To set wallpaper on the device:

1. Use importWallpaper to convert an image to a wallpaper object.
2. Pass the wallpaper object as the new value for the wallpaper key in setPreferences.

### wallpaper/importWallpaper

Converts an image to a wallpaper for the device. The image is either re-centered and cropped, or scaled:

- If no focus or scale parameters are passed, importWallpaper scales the entire image to 320 x 480 pixels.
- If focus parameters are passed but scale is not specified, the image is re-centered at the point specified by the focus parameters and cropped. Black is added anywhere the image does not reach the edge of the screen.
- If scale is passed but focus is not specified, then the image is scaled and then cropped.
- If focus and scale parameters are passed, the image is first scaled and then re-centered and cropped.

The focusX and focusY parameters are the coordinates of the new center of the image. The scale parameter determines the new size of the image.

Once the image has been converted, the wallpaper is stored in the internal list of wallpapers on the device, and is available until deleted using deleteWallpaper. Note: the internal list of wallpapers is not the same as the Wallpapers folder that is visible to the user.

Required parameter:

- target

#### Parameters

Parameter | Type | Description
--- | --- | ---
target | string | The URL of the image file to be converted to a wallpaper (must be PNG or JPG). Only the file:// scheme is supported (no remote schemes are supported)
focusX | float | The horizontal coordinate of the new center of the image, from 0.0 (left edge) to 1.0 (right edge). A value of 0.5 preserves the current horizontal center of the image.
focusY | float | The vertical coordinate of the new center of the image, from 0.0 (top edge) to 1.0 (bottom edge). A value of 0.5 preserves the current vertical center of the image.
scale | float | The new scale of the image, from 0.1 to 10.0 times the current size.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (true) Indicates whether the call was successful.
wallpaper | JSON object | A wallpaper object that can be passed to setPreferences to set the wallpaper key.

onFailure

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (false) Indicates whether the call was successful.

#### Example

>     this.controller.serviceRequest('palm://com.palm.systemservice/wallpaper', {
>       method:"importWallpaper",
>       parameters:{
>           "target":"file:///media/internal/photos/mypic.jpg"
>       },
>       onSuccess: myCallback,
>       onFailure: myFailureCallback
>     });

### wallpaper/refresh

Refreshes the internal list of available wallpapers. Under normal circumstances, there is no need to call wallpaper/refresh directly.

#### Parameters

None.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (true) Indicates whether the call was successful.

onFailure

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (false) Indicates whether the call was successful.

### wallpaper/info

Retrieves a wallpaper object using either the wallpaperName or wallpaperFile attribute.

Required parameters:

- Either wallpaperName or wallpaperFile

#### Parameters

Parameter | Type | Description
--- | --- | ---
wallpaperName | string | The wallpaper attribute that specifies the name of the wallpaper.
wallpaperFile | string | The wallpaper attribute that specifies the file containing the wallpaper image.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (true) Indicates whether the call was successful.
wallpaper | JSON object | A wallpaper object that can be passed to setPreferences to set the wallpaper key.

onFailure

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (false) Indicates whether the call was successful.

#### Example

>     this.controller.serviceRequest('palm://com.palm.systemservice/wallpaper', {
>       method:"info",
>       parameters:{"wallpaperName":"flowers"},
>       onSuccess: myCallback,
>       onFailure: myFailureCallback
>     });

### wallpaper/deleteWallpaper

Deletes the specified wallpaper from the list of available wallpapers on the device.

Warning: Do not call deleteWallpaper on the currently active wallpaper!

Required parameter:

- wallpaperName

#### Parameters

Parameter | Type | Description
--- | --- | ---
wallpaperName | string | The wallpaperName attribute of the wallpaper object to delete.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (true) Indicates whether the call was successful.

onFailure

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | (false) Indicates whether the call was successful.

#### Example

>     this.controller.serviceRequest('palm://com.palm.systemservice/wallpaper', {
>       method:"deleteWallpaper",
>       parameters:{"wallpaperName":"flowers"},
>       onSuccess: myCallback,
>       onFailure: myFailureCallback
>     });

## Sample Code

See Services Sample.