27 Time Manager

This chapter provides reference material for the time manager.

• Time Manager Data Structures
  
  
• Time Manager Functions
  

The header file DateTime.h declares the API that this chapter describes. For more information on the time manager, see the section "Time" in the Palm OS Programmer's Companion.

Time Manager Data Structures

The time manager uses these structures to store information.

TimeFormatType

typedef enum

    {
    tfColon,
    tfColonAMPM, // 1:00 pm
    tfColon24h, // 13:00
    tfDot,
    tfDotAMPM, // 1.00 pm
    tfDot24h, // 13.00
    tfHoursAMPM, // 1 pm
    tfHours24h, // 13
    tfComma24h // 13,00
    } TimeFormatType;

typedef TimeFormatType* TimeFormatPtr;

DaylightSavingsTypes

typedef enum {

    dsNone, //Daylight Savings Time not
//observed
    dsUSA, //United States Daylight
//Savings Time
    dsAustralia, //Australian Daylight
//Savings Time
    dsWesternEuropean, //Western European Daylight
//Savings Time
    dsMiddleEuropean, //Middle European Daylight
//Savings Time
    dsEasternEuropean, //Eastern European Daylight
//Savings Time
    dsGreatBritain, //Great Britain and Eire
//Daylight Savings Time
    dsRumania, //Rumanian Daylight Savings
//Time
    dsTurkey, //Turkish Daylight Savings
//Time
    dsAustraliaShifted //Australian Daylight
//Savings Time with shift
//in 1986
} DaylightSavingsTypes;

DateFormatType

typedef enum {

    dfMDYWithSlashes, // 12/31/95
    dfDMYWithSlashes, // 31/12/95
    dfDMYWithDots, // 31.12.95
    dfDMYWithDashes, // 31-12-95
    dfYMDWithSlashes, // 95/12/31
    dfYMDWithDots, // 95.12.31
    dfYMDWithDashes, // 95-12-31

    dfMDYLongWithComma, // Dec 31, 1995
    dfDMYLong, // 31 Dec 1995
    dfDMYLongWithDot, // 31. Dec 1995
    dfDMYLongNoDay, // Dec 1995
    dfDMYLongWithComma, // 31 Dec, 1995
    dfYMDLongWithDot, // 1995.12.31
    dfYMDLongWithSpace, // 1995 Dec 31

    dfMYMed, // Dec '95
    dfMYMedNoPost // Dec 95
//added for French 2.0 ROM)
    } DateFormatType;

DateTimeType

typedef struct{

Int16 second;
Int16 minute;
Int16 hour;
Int16 day;
Int16 month;
Int16 year;
Int16 weekDay ; //Days since Sunday (0 to 6)
}DateTimeType;

typedef DateTimeType * DateTimePtr;

TimeType

typedef struct {

UInt8 hours;
UInt8 minutes;
}TimeType;

typedef TimeType * TimePtr;

DateType

typedef struct{

UInt16 year :7 ; //years since 1904 (Mac format)
UInt16 month :4;
UInt16 day :5;
}DateType;

typedef DateType * DatePtr;

Time Manager Constants

Maximum lengths of strings returned by the date and time formatting routines DateToAscii, DateToDOWDMFormat, and TimeToAscii.

Constant	Value	Description
dateStringLength	9	Max length of string returned by DateToAscii for short date formats.
longDateStrLength	15	Max length of string returned by DateToAscii for medium and long date formats.
timeStringLength	9	Max length of string returned by TimeToAscii.
dowDateStringLength	19	Max length of string returned by DateToDOWDMFormat for short date formats.
dowLongDateStrLength	25	Max length of string returned by DateToDOWDMFormat for long date formats

Time Manager Functions

DateAdjust

Purpose

Return a new date +/- the days adjustment.

Prototype

void DateAdjust (DatePtr dateP, Int32 adjustment)

Parameters

dateP

A "DateType" structure with the date to be adjusted (see DateTime.h).

adjustment

The adjustment in number of days.

Result

Changes dateP to contain the new date.

Comments

This function is useful for advancing a day or week and not worrying about month and year wrapping.

If the time is advanced out of bounds, it is cut at the bounds surpassed.

DateDaysToDate

Purpose

Return the date, given days.

Prototype

void DateDaysToDate (UInt32 days, DatePtr date)

Parameters

days

Days since 1/1/1904.

date

Pointer to "DateType" structure (returned).

Result

Returns nothing, stores the date in date.

See Also

TimAdjust, DateToDays

DateSecondsToDate

Purpose

Return the date given seconds.

Prototype

void DateSecondsToDate (UInt32 seconds, DatePtr date)

Parameters

seconds

Seconds since 1/1/1904.

date

Pointer to "DateType" structure (returned).

Result

Returns nothing; stores the date in date.

DateTemplateToAscii

Purpose

Convert the date passed to a string, using the formatting specified by the templateP string.

Prototype

UInt16 DateTemplateToAscii(const Char *templateP, UInt8 months, UInt8 days, UInt16 years, Char *stringP, Int16 stringLen)

Parameters

templateP pointer to template string used to format date. Max length is maxDateTemplateLen bytes, excluding the terminating null.

months months (1-12)

days days (1-31)

years years. For example, 1995.

stringP pointer to string which gets the result. Up to stringLen bytes (excluding the terminating null byte.) Can be NULL, in which case the required string length is still returned by the function. If not NULL, then the formatted string is written to it,

stringLen size of string buffer, excluding the terminating NULL byte.

Result

The length of the formatted string (without the terminating null byte) is always returned, even if the stringP parameter is null.

This then lets you allocate a buffer at run time, without having to previously fix it to some max size.

Comments

The stringP parameter can be NULL, in which case the required string length is still returned.

---

NOTE:  

This routine is only available in PalmOS 3.5 or later ROMs.

---

This routine uses the template text contained in templateP, and creates a properly formatted date string in stringP for the values passed in months, days, and years.

Template strings:

A template string contains a mixture of regular text and formatting substrings. Each formatting substring has the format

"^<number><modifier>". The possible values for number are:

dateTemplateDayNum = '0',	// Day number (1..31)
dateTemplateDOWName,	// Day name (e.g. Tue)
dateTemplateMonthName,	// Month name (e.g. Aug)
dateTemplateMonthNum,	// Month number (1..12)
dateTemplateYearNum	// Year (e.g. 1995)

The possible values for modifier are:

#define dateTemplateShortModifier	's'
#define dateTemplateRegularModifier	'r'
#define dateTemplateLongModifier	'l'
#define dateTemplateLeadZeroModifier	'z'

The meaning of each modifier depends on what type of formatting string it's part of. An example of each is as follows:

Format	Short	Regular	Long	Zero
DayNum	5	5	5	05
DOWName	T	Tue	Tuesday	n/a
MonthName	A	Aug	August	n/a
MonthNum	8	8	8	08
YearNum	00	2000	2000	n/a

So, for example, the formatting string to get "02 February 2000" would be:

"^0z ^2l ^4r"

See Also

DateToAscii, DateToDOWDMFormat

DateToAscii

Purpose

Convert the date passed to a string using the format specified by the dateFormat parameter.

Prototype

void DateToAscii (UInt8 months, UInt8 days, UInt16 years, DateFormatType dateFormat, Char* pString)

Parameters

months

Months (1-12).

days

Days (1-31).

years

Years (for example 1995).

dateFormat

Any "DateFormatType" format.

pString

Pointer to string which gets the result. Must be of length dateStringLength for standard formats or longDateStrLength for medium or long formats. (See "Time Manager Constants" for allowed lengths.

Result

Returns nothing. Stores the result in pString.

Comments

---

NOTE:  

If you are using a debug ROM, the string buffer is filled with dateStringLength or longStrLength debugging bytes, depending on the dateFormat parameter.

---

Common situations where buffers overflow on debug ROMs include stack-based or global variables, form titles, form labels, and control labels. Overflowing a form object is sometimes very hard to catch, because often what happens is that the following form object's data (such as its position) is overwritten, and so suddenly the form object disappears.

See Also

TimeToAscii, DateToDOWDMFormat, DateTemplateToAscii

DateToDays

Purpose

Return the date in days since 1/1/1904.

Prototype

UInt32 DateToDays (DateType date)

Parameters

date

"DateType" structure.

Result

Returns the days since 1/1/1904.

See Also

TimAdjust, DateDaysToDate

DateToDOWDMFormat

Purpose

Convert a date to a formatted string using the format specified by the dateFormat parameter. The string passed must include the name of the day of the week.

Prototype

void DateToDOWDMFormat (UInt8 month, UInt8 day, UInt16 year, DateFormatType dateFormat, Char * pString)

Parameters

month

Month (1-12).

day

Days (1-31).

year

Years (for example 1995).

dateFormat

Any "DateFormatType" format.

pString

Pointer to string which gets the result. Must be of length dateStringLength for standard formats or longDateStrLength for medium or long date formats. (See "Time Manager Constants" for string buffer lengths.)

Result

Returns nothing; stores formatted string in pString.

Comments

For the routines that return the day-of-week name in addition to the date, the size of the buffers has been expanded, so developers need to check the maximum lengths defined in DateTime.h.

Common situations where buffers overflow on debug ROMs include stack-based or global variables, form titles, form labels, and control labels. Overflowing a form object is sometimes very hard to catch, because often what happens is that the following form object's data (such as its position) is overwritten, and so suddenly the form object disappears.

See Also

DateToAscii, DateTemplateToAscii

DayOfMonth

Purpose

Return the day of a month on which the specified date occurs.

Prototype

Int16 DayOfMonth (Int16 month, Int16 day, Int16 year)

Parameters

month

Month (1-12).

day

Day (1-31).

year

Year (for example 1995).

Result

Returns the day of the month; see DateTime.h.

Comments

For example, "first Monday" is returned for 2/7/00.

DayOfWeek

Purpose

Return the day of the week.

Prototype

Int16 DayOfWeek (Int16 month, Int16 day, Int16 year)

Parameters

month

Month (1-12).

day

Day (1-31).

year

Year (for example 1995).

Result

Returns the day of the week (Sunday = 0, Monday = 1, etc.).

DaysInMonth

Purpose

Return the number of days in the month.

Prototype

Int16 DaysInMonth (Int16 month, Int16 year)

Parameters

month

Month (1-12).

year

Year (for example, 1995).

Result

Returns the number of days in the month for that year.

TimAdjust

Purpose

Return a new date, +/- the time adjustment.

Prototype

void TimAdjust (DateTimePtr dateTimeP, Int32 adjustment)

Parameters

dateTimeP

A "DateType" structure (see DateTime.h).

adjustment

The adjustment in seconds.

Result

Returns nothing. Changes dateTimeP to the new date and time.

Comments

This function is useful for advancing a day or week and not worrying about month and year wrapping.

If the time is advanced out of bounds it is cut at the bounds surpassed.

See Also

DateAdjust

TimDateTimeToSeconds

Purpose

Return the number of seconds since 1/1/1904 to the passed date and time.

Prototype

UInt32 TimDateTimeToSeconds (DateTimePtr dateTimeP)

Parameters

dateTimeP

Pointer to a "DateTimeType" structure (see DateTime.h).

Result

The time in seconds since 1/1/1904.

See Also

TimSecondsToDateTime

TimGetSeconds

Purpose

Return the current date and time of the device in seconds since 1/1/1904 12AM.

Prototype

UInt32 TimGetSeconds (void)

Parameters

Result

Returns the number of seconds.

See Also

TimSetSeconds

TimGetTicks

Purpose

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

Prototype

UInt32 TimGetTicks (void)

Parameters

Result

Returns the tick count.

Comments

Use to determine the number of ticks per second.

TimSecondsToDateTime

Purpose

Return the date and time, given seconds.

Prototype

void TimSecondsToDateTime (UInt32 seconds, DateTimePtr dateTimeP)

Parameters

seconds

Seconds to advance from 1/1/1904.

dateTimeP

A "DateTimeType" structure that's filled by the function.

Result

Returns nothing. Stores the date and time given seconds since 1/1/1904 in dateTimeP.

See Also

TimDateTimeToSeconds

TimSetSeconds

Purpose

Set the clock of the device to the date and time passed as the number of seconds since 1/1/1904 12AM.

Prototype

void TimSetSeconds (UInt32 seconds)

Parameters

seconds

The seconds since 1/1/1904.

Result

Returns nothing.

Comments

On systems where the Notification Feature Set is present, this function broadcasts the sysNotifyTimeChangeEvent to all interested parties. See the "Notification Manager" chapter for more information.

See Also

TimGetSeconds

TimeToAscii

Purpose

Convert the time passed to a formatted string.

Prototype

void TimeToAscii (UInt8 hours, UInt8 minutes, TimeFormatType timeFormat, Char* pString)

Parameters

hours

Hours (0-23).

minutes

Minutes (0-59).

timeFormat

FALSE to use AM and PM.

pString

Pointer to string which gets the result. Must be of length timeStringLength. See "Time Manager Constants" for information on string buffer lengths.

Result

Returns nothing. Stores the formatted string in pString.

Comments

---

NOTE:  

If you are using a debug ROM in PalmOS 3.5, the string buffer is filled with timeStringLength debugging bytes.

---

For the routines that return the day-of-week name in addition to the date, the size of the buffers has been expanded, so developers need to check the maximum lengths defined in DateTime.h. See "Time Manager Constants".

See Also

DateToAscii