Documentation

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.

Methods

Preferences Methods -- URI is com.palm.systemservice/
Time Method -- URI is com.palm.systemservice/time/getSystemTime
Wallpaper Methods -- URI is com.palm.systemservice/wallpaper/

NOTE

The preferences database is not secure. Apps should not rely on it for system settings or storing data. Apps that require persistent storage should use the db8 database.

getPreferences

Retrieves the values for keys specified in a passed array. If subscribe is set to true, then getPreferences sends an update if the key values change.

Syntax

{
    "keys"      : string array,
    "subscribe" : boolean
}

Parameters

Parameter	Required	Type	Description
keys	Yes	string array	An array of key names.
subscribe	No	boolean	If true, getPreferences sends an update whenever the value of one of the keys changes.

Returns

{
   "returnValue" : boolean,
   "[no name]"   : object
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	true (success) or false (failure)
{no name}	No	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.

Examples

luna-send

luna-send -n 1 -f  luna://com.palm.systemservice/getPreferences '{"keys":["wallpaper"]}'
{
    "wallpaper": {
        "wallpaperThumbFile": "\/media\/internal\/.wallpapers\/tdumbs\/02.jpg",
        "wallpaperName": "02.jpg",
        "wallpaperFile": "\/media\/internal\/.wallpapers\/02.jpg"
    },
    "returnValue": true
}

Enyo

. . .

{
    name : "getPreferencesCall",
    kind : "PalmService",
    service : "palm://com.palm.systemservice/",
    method : "getPreferences",
    onSuccess : "getPrefsSuccess",
    onFailure : "getPrefsFailure",
    onResponse : "gotResponse",
    subscribe : true
 }, 

. . . 

getPrefsSuccess : function(inSender, inResponse) {
   enyo.log("getPreferences success, results=" + enyo.json.stringify(inResponse));
},
getPrefsFailure : function(inSender, inResponse) {
   enyo.log("getPreferences failure, results=" + enyo.json.stringify(inResponse));
},
getPrefs : function(inSender, inResponse)
{
   this.$.getPreferencesCall.call({"keys":["locale"] });
}

Mojo

this.controller.serviceRequest('palm://com.palm.systemservice', {
     method:"getPreferences",
     parameters:{"keys":["locale"]},
     onSuccess : function (e){ Mojo.Log.info("getPreferences success, results="+JSON.stringify(e)); },
     onFailure : function (e){ Mojo.Log.info("getPreferences failure, results="+JSON.stringify(e)); }
});

Success

getPreferences success, results=
{
   "locale":{
      "languageCode":"en",
      "countryCode":"us",
      "phoneRegion":{
         "countryName":"United States",
         "countryCode":"us"
      }
   },
   "returnValue":true
}

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.

Syntax

{
    "key" : string
}

Parameters

Parameter	Required	Type	Description
key	Yes	string	Key name

Returns

{
    "returnValue" : boolean,
    "[no name]"   : object
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	true (success) or false (failure)
{no name}	No	object	The key and the valid values.

Examples

luna-send

luna-send -n 1  luna://com.palm.systemservice/getPreferenceValues '{"key":"timeFormat"}'
{ "timeFormat": [ "HH12", "HH24" ], "returnValue": true }

Enyo

. . .

{
    name : "getPreferenceValuesCall",
    kind : "PalmService",
    service : "palm://com.palm.systemservice/",
    method : "getPreferenceValues",
    onSuccess : "getPrefValsSuccess",
    onFailure : "getPrefValsFailure",
    onResponse : "gotResponse",
    subscribe : true
},  

. . . 

getPrefValsSuccess : function(inSender, inResponse) {
    enyo.log("getPreferenceValues success, results=" + enyo.json.stringify(inResponse));
},
getPrefValsFailure : function(inSender, inResponse) {
    enyo.log("getPreferenceValues failure, results=" + enyo.json.stringify(inResponse));
},
getPrefVals : function(inSender, inResponse)
{
    this.$.getPreferenceValuesCall.call({"key":"timeFormat"});
}

Mojo

this.controller.serviceRequest('palm://com.palm.systemservice', {
    method:"getPreferenceValues",
    parameters:{"key":"timeFormat" },
    onSuccess : function (e){ Mojo.Log.info("getPreferenceValues success, results="+JSON.stringify(e)); },
    onFailure : function (e){ Mojo.Log.info("getPreferenceValues failure, results="+JSON.stringify(e)); }
});

Success

getPreferenceValues success, results=
{
   "timeFormat":[
      "HH12",
      "HH24"
   ],
   "returnValue":true
}

setPreferences

Sets preference keys to specified values.

Syntax

{
    "params" : object
}

Parameters

Parameter	Required	Type	Description
params	Yes	object	An object containing one or more key-value pairs or other objects.

Returns

{
    "returnValue" : boolean,
    "errorText"   : string
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	true (success) or false (failure).
errorText	No	string	Error message returned on failure.

Examples

luna-send

luna-send -n 1  luna://com.palm.systemservice/setPreferences '{"food":"pizza"}'
{ "returnValue": true }

Enyo

. . .

{
   name : "setPreferencesCall",
   kind : "PalmService",
   service : "palm://com.palm.systemservice/",
   method : "setPreferences",
   onSuccess : "setPrefsSuccess",
   onFailure : "setPrefsFailure",
   onResponse : "gotResponse",
   subscribe : true
},

. . . 

setPrefsSuccess : function(inSender, inResponse) {
    enyo.log("setPreferences success, results=" + enyo.json.stringify(inResponse));
},
setPrefsFailure : function(inSender, inResponse) {
    enyo.log("setPreferences failure, results=" + enyo.json.stringify(inResponse));
},
setPrefs : function(inSender, inResponse)
{
    this.$.setPreferencesCall.call({"food":"pizza"});
}

Mojo

 this.controller.serviceRequest('palm://com.palm.systemservice', {
    method:"setPreferences",
    parameters:{"food":"pizza"},
    onSuccess : function (e){ Mojo.Log.info("setPreferences success, results="+JSON.stringify(e)); },
    onFailure : function (e){ Mojo.Log.info("setPreferences failure, results="+JSON.stringify(e)); }
});

Success

setPreferences success, results=
{
    "returnValue":true
}

Failure

setPreferences failure, results=
{
   "returnValue":false,
   "errorText":"Some settings could not be saved"
}

Time Method

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 information about world time zones, see Wikipedia.

Syntax

{
    "subscribe" : boolean
}

Parameters

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

Returns

{
   "utc" : int,
   "localtime" : {
      "year"   : int,
      "month"  : int,
      "day"    : int,
      "hour"   : int,
      "minute" : int,
      "second" : int
   },
   "offset"       : int,
   "timezone"     : string,
   "TZ"           : string,
   "timeZoneFile" : string,
   "NITZValid"    : boolean
}

Attribute	Type	Description
utc	int	The number of milliseconds since Epoch (midnight of January 1, 1970 UTC), aka - Unix time.
localtime	object	See fields below.
year	int	The year, i.e., 2009.
month	int	The month, 1-12.
day	int	The day, 1-21
hour	int	The minute, 0-23
minute	int	The minute, 0-59
second	int	The second, 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)).
timeZoneFile	string	Linux zone information file for the currently set zone. For more information, see: http://linux.die.net/man/5/tzfile
NITZValid	boolean	Deprecated. Formerly used to alert the UI whether or not it managed to set the time correctly using NITZ. Currently, it does not indicate anything meaningful

Examples

luna-send

luna-send -n 1 -f  luna://com.palm.systemservice/time/getSystemTime '{}'
{
    "utc": 1312472027,
    "localtime": {
        "year": 2011,
        "month": 8,
        "day": 4,
        "hour": 8,
        "minute": 33,
        "second": 47
    },
    "offset": -420,
    "timezone": "America\/Los_Angeles",
    "TZ": "PDT",
    "timeZoneFile": "\/var\/luna\/preferences\/localtime",
    "NITZValid": false
}

Enyo

. . .

{
    name : "getSystemTimeCall",
    kind : "PalmService",
    service : "palm://com.palm.systemservice/time/",
    method : "getSystemTime",
    onSuccess : "getSysTimeSuccess",
    onFailure : "getSysTimeFailure",
    onResponse : "gotResponse",
    subscribe : true
},  

. . . 

getSysTimeSuccess : function(inSender, inResponse) {
    enyo.log("getSystemTime success, results=" + enyo.json.stringify(inResponse));
},
getSysTimeFailure : function(inSender, inResponse) {
    enyo.log("getSystemTime failure, results=" + enyo.json.stringify(inResponse));
},
getSysTime : function(inSender, inResponse)
{
    this.$.getSystemTimeCall.call({"subscribe":true});
}

Mojo

this.controller.serviceRequest('palm://com.palm.systemservice/time', {
    method:"getSystemTime",
    parameters:{"subscribe":true},
    onSuccess : function (e){ Mojo.Log.info("getSystemTime success, results="+JSON.stringify(e)); },
    onFailure : function (e){ Mojo.Log.info("getSystemTime failure, results="+JSON.stringify(e)); }
});

Wallpaper Methods

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 the wallpaper on the device:

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

Methods

deleteWallpaper
importWallpaper
info
refresh

deleteWallpaper

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

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

Syntax

{
    "wallpaperName" : string
}

Parameters

Parameter	Required	Type	Description
wallpaperName	Yes	string	The wallpaperName attribute of the wallpaper object to delete.

Returns

{
    "returnValue" : boolean,
    "wallpaper"  : {
        "wallpaperName" : string
    }   
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	true (success) or false (failure).
wallpaper	Yes	object	See field below.
wallpaperName	No	string	Wallpaper file name passed.
errorText	No	string	Error message returned on failure.

Examples

luna-send

luna-send -n 1 luna://com.palm.systemservice/wallpaper/deleteWallpaper '{"wallpaperName":"Mekong"}'
{ "returnValue": true, "wallpaper": { "wallpaperName": "Mekong" } }

Enyo

. . .

{
    name : "deleteCall",
    kind : "PalmService",
    service : "palm://com.palm.systemservice/wallpaper/",
    method : "deleteWallpaper",
    onSuccess : "deleteSuccess",
    onFailure : "deleteFailure",
    onResponse : "gotResponse",
    subscribe : true
 },     

. . . 

deleteSuccess : function(inSender, inResponse) {
    enyo.log("delete success, results=" + enyo.json.stringify(inResponse));
},
deleteFailure : function(inSender, inResponse) {
    enyo.log("delete failure, results=" + enyo.json.stringify(inResponse));
},
doDelete : function(inSender, inResponse)
{
    this.$.deleteCall.call({"wallpaperName":"Mekong"});
}

Mojo

this.controller.serviceRequest('palm://com.palm.systemservice/wallpaper', {
    method:"deleteWallpaper",
    parameters:{"wallpaperName":"flowers"},
    onSuccess : function (e){ Mojo.Log.info("deleteWallpaper success, results="+JSON.stringify(e)); },
    onFailure : function (e){ Mojo.Log.info("deleteWallpaper failure, results="+JSON.stringify(e)); }
 });

Success

deleteWallpaper success, results=
{
   "returnValue":true,
   "wallpaper":{
      "wallpaperName":"flowers"
   }
}

Failure

deleteWallpaper failure, results=
{
   "returnValue":false,
   "errorText":"must specify wallpaperName"
}

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.

Syntax

{
    "target" : string,
    "focusX" : float,
    "focusY" : float,
    "scale"  : float
}

Parameters

Parameter	Required	Type	Description
target	Yes	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	No	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	No	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	No	float	The new scale of the image, from 0.1 to 10.0 times the current size.

Returns

{
   "returnValue" : boolean,
   "wallpaper"   : {
      "wallpaperName"      : string,
      "wallpaperFile"      : string,
      "wallpaperThumbFile" : string
   }
   "errorText" : string   
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	(true) Indicates whether the call was successful.
wallpaper	No	object	A wallpaper object that can be passed to setPreferences to set the wallpaper key. See fields below.
wallpaperName	No	string	Name of wallpaper file.
wallpaperFile	No	string	Path to wallpaper file.
wallpaperThumbFile	No	string	Path to wallpaper thumb file.
errorText	No	string	Error message returned on failure.

Examples

luna-send

luna-send -n 1 -f  luna://com.palm.systemservice/wallpaper/importWallpaper '{"target":"/media/internal/downloads/Mekong.jpg"}'
{
    "returnValue": true,
    "wallpaper": {
        "wallpaperName": "Mekong.jpg",
        "wallpaperFile": "\/media\/internal\/.wallpapers\/Mekong.jpg",
        "wallpaperThumbFile": "\/media\/internal\/.wallpapers\/tdumbs\/Mekong.jpg"
    }
}

Enyo

. . .

{
    name : "importCall",
    kind : "PalmService",
    service : "palm://com.palm.systemservice/wallpaper/",
    method : "importWallpaper",
    onSuccess : "importSuccess",
    onFailure : "importFailure",
    onResponse : "gotResponse",
    subscribe : true
},          

. . . 

importSuccess : function(inSender, inResponse) {
    enyo.log("import success, results=" + enyo.json.stringify(inResponse));
},
importFailure : function(inSender, inResponse) {
    enyo.log("import failure, results=" + enyo.json.stringify(inResponse));
},
doImport : function(inSender, inResponse)
{
    this.$.importCall.call({"target":"/media/internal/downloads/Mekong.jpg"});
}

Mojo

 this.controller.serviceRequest('palm://com.palm.systemservice/wallpaper', {
    method:"importWallpaper",
    parameters:{ "target":"/media/internal/downloads/Mekong.jpg" },
    onSuccess : function (e){ Mojo.Log.info("importWallpaper success, results="+JSON.stringify(e)); },
    onFailure : function (e){ Mojo.Log.info("importWallpaper failure, results="+JSON.stringify(e)); }
});

Success

importWallpaper success, results=
{
   "returnValue":true,
   "wallpaper":{
      "wallpaperName":"Mekong.jpg",
      "wallpaperFile":"/media/internal/.wallpapers/Mekong.jpg",
      "wallpaperThumbFile":"/media/internal/.wallpapers/tdumbs/Mekong.jpg"
   }
}

Failure

importWallpaper failure, results=
{
   "returnValue":false,
   "errorText":""
}

info

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

Syntax

{
    "wallpaperName" : string,
    "wallpaperFile" : string
}

Parameters

Parameter	Required	Type	Description
wallpaperName	No	string	Wallpaper name. Either this, or "wallpaperFile" is required.
wallpaperFile	No	string	Wallpaper's full path and file name. Either this, or "wallpaperName" is required.

Returns

{
   "returnValue" : boolean,
   "wallpaper"   : {
      "wallpaperName"      : string,
      "wallpaperFile"      : string,
      "wallpaperThumbFile" : string
   }
   "errorText" : string   
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	(true) Indicates whether the call was successful.
wallpaper	No	object	A wallpaper object that can be passed to setPreferences to set the wallpaper key. See fields below
wallpaperName	No	string	Name of wallpaper file.
wallpaperFile	No	string	Path to wallpaper file.
wallpaperThumbFile	No	string	Path to wallpaper thumb file.
errorText	No	string	Error message returned on failure.

Examples

luna-send

luna-send -n 1 -f luna://com.palm.systemservice/wallpaper/info '{"wallpaperFile":"/media/internal/wallpapers/Mekong.jpg"}'
{
    "returnValue": true,
    "wallpaper": {
        "wallpaperName": "Mekong.jpg",
        "wallpaperFile": "\/media\/internal\/.wallpapers\/Mekong.jpg",
        "wallpaperThumbFile": "\/media\/internal\/.wallpapers\/tdumbs\/Mekong.jpg"
    }
}

Enyo

. . .

{
    name : "infoCall",
    kind : "PalmService",
    service : "palm://com.palm.systemservice/wallpaper/",
    method : "info",
    onSuccess : "infoSuccess",
    onFailure : "infoFailure",
    onResponse : "gotResponse",
    subscribe : true
},      

. . . 

infoSuccess : function(inSender, inResponse) {
    enyo.log("info success, results=" + enyo.json.stringify(inResponse));
},
infoFailure : function(inSender, inResponse) {
    enyo.log("info failure, results=" + enyo.json.stringify(inResponse));
},
getInfo : function(inSender, inResponse)
{
    this.$.infoCall.call({"target":"/media/internal/downloads/Mekong.jpg"});
}

Mojo

this.controller.serviceRequest('palm://com.palm.systemservice/wallpaper', {
    method:"info",
    parameters:{"wallpaperFile":"/media/internal/wallpapers/Mekong.jpg"},
    onSuccess : function (e){ Mojo.Log.info("info success, results="+JSON.stringify(e)); },
    onFailure : function (e){ Mojo.Log.info("info failure, results="+JSON.stringify(e)); }
})

Success

info success, results=
{
   "returnValue":true,
   "wallpaper":{
      "wallpaperName":"Mekong.jpg",
      "wallpaperFile":"/media/internal/.wallpapers/Mekong.jpg",
      "wallpaperThumbFile":"/media/internal/.wallpapers/tdumbs/Mekong.jpg"
   }
}

Failure

info failure, results=
{ 
    "returnValue": false, 
    "errorText": "invalid wallpaper file specified (perhaps it doesn't exist in the wallpaper dir; was it imported?"
}

refresh

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

Parameters

None.

Returns

{
    returnValue : boolean
}

Attribute	Type	Description
returnValue	boolean	true (success) or false (failure).

Sample Code

See Services Sample.

Documentation

System Services

Preferences Methods

getPreferences

Syntax

Parameters

Returns

Examples

getPreferenceValues

Syntax

Parameters

Returns

Examples

setPreferences

Syntax

Parameters

Returns

Examples

Time Method

getSystemTime

Syntax

Parameters

Returns

Examples

Wallpaper Methods

deleteWallpaper

Syntax

Parameters

Returns

Examples

importWallpaper

Syntax

Parameters

Returns

Examples

info

Syntax

Parameters

Returns

Examples

refresh

Parameters

Returns

Sample Code

Why webOS

Getting Started

Videos

Stay up to date