System Service

Service URI - luna://com.palm.systemservice

Provides information about the system time.  Apps can subscribe to this method to get system time updates.

Methods

Method	Description	Supported in Emulator
time/getSystemTime	Returns the detailed information of a device.	Yes

 

Open All

time/getSystemTime

DESCRIPTION

Requests the system time. Apps can subscribe to this method and receive notifications when the time zone changes and/or the system time changes by a significant amount (currently 5 minutes).

SYNTAX

time/getSystemTime([Boolean subscribe])

PARAMETERS

Name	Required	Type	Description
subscribe	Optional	Boolean	Flag that decides whether to subscribe or not. If the app wants to receive notifications when the time zone changes and/or the system time changes by a system-defined threshold, it should set subscribe to true. The current system-defined threshold is 5 minutes. If the app does not wish to receive notifications of change in time zone and/or the system time changes, it should set subscribe to false. true: Subscribe. false: Do no subscribe. Call the method only once. (Default)

CALL RETURNS

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
subscribed	Optional	Boolean	Flag that indicates whether the subscription is enabled or not. true: Enabled false: Not enabled.
utc	Required	Number	The number of milliseconds since Epoch (midnight of January 1, 1970, UTC), also known as the Unix time.
localtime	Required	Object	The object that contains information about the current system time.
offset	Required	Number	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	Required	String	The current system time zone. It has the same format as the TZ environment variable. For information, visit http://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html.
TZ	Required	String	Contains the time zone abbreviation in the standard Unix format, for example, PDT (which stands for Pacific Daylight Time). The timezone corresponds to the current time zone of the system.
timeZoneFile	Required	String	Linux zone information file for the currently set zone. For more information, visit http://linux.die.net/man/5/tzfile.
NITZValid	Required	String	Deprecated. Formerly it was used to alert the UI whether if the method managed to set the time correctly using NITZ. Currently, it does not indicate anything meaningful.

SUBSCRIPTION RETURN

Name	Required	Type	Description
utc	Required	Number	The number of milliseconds since Epoch (midnight of January 1, 1970, UTC), also know as the Unix time.
localtime	Required	Object	The object that contains information about the current system time.
offset	Required	Number	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	Required	String	The current system time zone. It has the same format as the TZ environment variable. For information, visit http://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html.
TZ	Required	String	Contains the time zone abbreviation in the standard Unix format, for example, PDT (which stands for Pacific Daylight Time). The timezone corresponds to the current time zone of the system.
timeZoneFile	Required	String	Linux zone information file for the currently set zone. For more information, visit http://linux.die.net/man/5/tzfile.
NITZValid	Required	String	Deprecated. Formerly it was used to alert the UI whether if the method managed to set the time correctly using NITZ. Currently, it does not indicate anything meaningful.
NITZValidTime	Optional	String	Indicates that a valid time was correctly set using NITZ. This value is needed because sometimes the time-zone may be received ahead of the time.
NITZValidZone	Optional	String	Indicates that a valid time-zone was correctly set using NITZ. This value is needed because sometimes the time may be received ahead of the time-zone.

EXAMPLE

// One-time call
var request = webOS.service.request("luna://com.palm.systemservice", {
    method: "time/getSystemTime",
    parameters: { "subscribe": false },
    onSuccess: function (inResponse) {
        console.log("Result: " + JSON.stringify(inResponse));
        // To-Do something
    },
	onFailure: function (inError) {
		console.log("Failed to get system time information");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});
 
// Subscription
var subscriptionHandle;
 
subscriptionHandle = webOS.service.request("luna://com.palm.systemservice", {
    method: "time/getSystemTime",
    parameters: { "subscribe": true },
    onSuccess: function (inResponse) {
        if (!inResponse.subscribed) {
            console.log("Failed to subscribe the system time information");
            return;
        }

		console.log("Result: " + JSON.stringify(inResponse));
		// To-Do something
    },
	onFailure: function (inError) {
		console.log("Failed to get system time information");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});
...
// If you need to unsubscribe the data, use cancel() method as below
subscriptionHandle.cancel();

RETURN EXAMPLE

{
    "timeZoneFile": "/var/luna/preferences/localtime",
    "utc": 1418745990,
    "localtime": {
        "month": 12,
        "day": 16,
        "hour": 11,
        "minute": 6,
        "year": 2014,
        "second": 30
    },
    "offset": -300,
    "timezone": "Asia/Seoul",
    "TZ": "EST",
    "systemTimeSource": "sdp"
}

SEE ALSO

None

Object

LocalTime Object

This object provides details of the current system time.

{
    "year": number,
    "month": number,
    "dayOfWeek": number,
    "day": number,
    "hour": number,
    "minute": number,
    "second": number
} 

Name	Required	Type	Description
year	Required	Number	The year
month	Required	Number	The month (1-12)
dayOfWeek	Optional	Number	Day of the week (0 - 6)
day	Required	Number	The day (1- 31)
hour	Required	Number	The hour (0 - 23)
minute	Required	Number	The minute (0 - 59)
second	Required	Number	The second (0 - 59 or 60 for leap seconds)