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