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