Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

38    Time Manager

System Management

Exploring Palm OS®

This chapter provides reference material for those APIs used to get and set the handheld's clock, and to get the amount of time elapsed since the handheld was last reset. It is organized as follows:

Time Manager Constants
Time Manager Functions and Macros

The header file TimeMgr.h declares the API that this chapter describes. For more information on using the Time Manager APIs, see Chapter 11, "Time."

Time Manager Constants ^TOP^

Time Manager Error Codes ^TOP^

Purpose

Error codes returned by the various Time manager functions.

Declared In

TimeMgr.h

Constants

#define timErrBadParam (timErrorClass | 3)
Returned from TimSetSeconds() if the specified date and time is outside the range of dates and times that the device can handle.
#define timErrMemory (timErrorClass | 1)
Insufficient memory.
#define timErrNoLunarCalendarSupport (timErrorClass | 2)

Time Manager Functions and Macros ^TOP^

TimGetSeconds Function ^TOP^

Purpose

Return the current date and time of the device in seconds since 12:00 A.M. on January 1, 1904.

Declared In

TimeMgr.h

Prototype

uint32_t TimGetSeconds (
   void
)

Parameters

None.

Returns

The number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the current date and time on the device.

See Also

TimSetSeconds()

TimGetTicks Function ^TOP^

Purpose

Return the tick count since the last reset. The tick count does not advance while the device is in sleep mode.

Declared In

TimeMgr.h

Prototype

uint64_t TimGetTicks (
   void
)

Parameters

None.

Returns

Returns the tick count.

Comments

You can call the SysTicksPerSecond() routine to determine the number of ticks per second.

TimInit Function ^TOP^

Purpose

Declared In

TimeMgr.h

Prototype

status_t TimInit (
   void
)

Parameters

None.

Returns

TimSetSeconds Function ^TOP^

Purpose

Set the clock of the device to the date and time passed as the number of seconds since 12:00 A.M. on January 1, 1904.

Declared In

TimeMgr.h

Prototype

status_t TimSetSeconds (
   uint32_t seconds
)

Parameters

seconds
The number of seconds since 12:00 A.M. on January 1, 1904.

Returns

Returns errNone if the operation completed successfully, or timErrBadParam if the specified date and time is outside the range of dates and times that the device can handle. Note that this range is defined by each Palm Powered device manufacturer, so the behavior of this function with certain dates may vary from one device to another.

Comments

This function broadcasts the sysNotifyTimeChangeEvent to all interested parties.

See Also

TimGetSeconds()