This chapter provides reference material for the time manager.
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, vol. I.
Time Manager Data Structures
The time manager uses these structures to store information.
DateFormatType Enum
Purpose
The DateFormatType
enum specifies the different display formats for date values.
Prototype
typedef enum { dfMDYWithSlashes, dfDMYWithSlashes, dfDMYWithDots, dfDMYWithDashes, dfYMDWithSlashes, dfYMDWithDots, dfYMDWithDashes, dfMDYLongWithComma, dfDMYLong, dfDMYLongWithDot, dfDMYLongNoDay, dfDMYLongWithComma, dfYMDLongWithDot, dfYMDLongWithSpace, dfMYMed, dfMYMedNoPost, dfMDYWithDashes } DateFormatType;
Constants
-
dfMDYWithSlashes
- The month, day, and year numbers separated by slashes. For example,
12/31/95.
- This is considered a short format.
-
dfDMYWithSlashes
- The day, month, and year numbers separated by slashes. For example,
31/12/95.
- This is considered a short format.
-
dfDMYWithDots
- The day, month, and year numbers separated by dots. For example,
31.12.95.
- This is considered a short format.
-
dfDMYWithDashes
- The day, month, and year numbers separated by dashes. For example,
31-12-95.
- This is considered a short format.
-
dfYMDWithSlashes
- The year, month, and day numbers separated by slashes. For example,
95/12/31.
- This is considered a short format.
-
dfYMDWithDots
- The year, month, and day numbers separated by dots. For example,
95.12.31.
- This is considered a short format.
-
dfYMDWithDashes
- The year, month, and day numbers separated by dashes. For example,
95-12-31.
- This is considered a short format.
-
dfMDYLongWithComma
- The month, day, and year in long format, with a comma. For example,
Dec 31, 1995.
- This is considered a long format.
-
dfDMYLong
- The month, day, and year in long format. For example,
31 Dec 1995.
- This is considered a long format.
-
dfDMYLongWithDot
- The month, day, and year in long format, with a dot. For example,
31. Dec 1995.
- This is considered a long format.
-
dfDMYLongNoDay
- The month and year in long format. For example,
Dec 1995.
- This is considered a long format.
-
dfDMYLongWithComma
- The day, month, and year in long format, with a comma. For example,
31 Dec, 1995.
- This is considered a long format.
-
dfYMDLongWithDot
- The year, month, and day in long format with dot separators. For example,
1995.12.31.
- This is considered a long format.
-
dfYMDLongWithSpace
- The year, month, and day in long format with space separators. For example,
1995 Dec 31.
- This is considered a long format.
-
dfMYMed
- The month in long format with the two-digit year, preceded by an apostrophe. For example,
Dec '95.
- This is considered a medium format.
-
dfMYMedNoPost
- The month in long format with the two-digit year. For example,
Dec 95
. - This is considered a medium format.
-
dfMDYWithDashes
- The month, day, and year numbers separated by dashes. For example,
12-31-95.
- This is considered a short format.
Compatibility
The dfMDYWithDashes
constant is defined in Palm OS® 4.0 and higher.
DateTimeType Struct
Purpose
The DateTimeType
structure represents a date and time value.
Prototype
typedef struct{ Int16 second; Int16 minute; Int16 hour; Int16 day; Int16 month; Int16 year; Int16 weekDay; } DateTimeType
typedef DateTimeType *DateTimePtr;
Fields
-
second
- The number of seconds. This is a value between 0 and 59.
-
minute
- The number of minutes. This is a value between 0 and 59.
-
hour
- The number of hours. This is a value between 0 and 23.
-
day
- The day number. This is a value between 1 and 31.
-
month
- The month number. This is a value between 1 and 12.
-
year
- The year number.
-
weekDay
- The day number. This represents the number of days since Sunday and is thus a value between 0 and 6.
DateType Struct
Purpose
The DateType
structure represents a date value.
Prototype
typedef struct{ UInt16 year :7; UInt16 month:4; UInt16 day:5; } DateType;
typedef DateType *DatePtr;
Fields
-
year
- The number of years since 1904.
- Note that this is the format used on Macintosh computers.
-
month
- The month number. This is a value between 1 and 12.
-
day
- The day number. This is a value between 1 and 31.
DaylightSavingsTypes Enum
Purpose
The DaylightSavingsTypes
enum specifies the different forms of daylight savings times that you can specify for date and time values.
Note that the table uses "DST" to represent daylight savings time.
Prototype
typedef enum { dsNone, dsUSA, dsAustralia, dsWesternEuropean, dsMiddleEuropean, dsEasternEuropean, dsGreatBritain, dsRumania, dsTurkey, dsAustraliaShifted } DaylightSavingsTypes;
Constants
-
dsNone
- No DST (daylight savings time)
-
dsUSA
- U.S.A. DST
-
dsAustralia
- Australian DST
-
dsWesternEuropean
- Western European DST
-
dsMiddleEuropean
- Middle European DST
-
dsEasternEuropean
- Eastern European DST
-
dsGreatBritain
- Great Britain and Eire DST
-
dsRumania
- Rumanian DST
-
dsTurkey
- Turkish DST
-
dsAustraliaShifted
- Australian DST, with the 1986 shift
Compatibility
If 4.0 New Feature Set is present, this data type is obsolete. In versions 4.0 and higher, Palm OS represents daylight savings time as an integer value that gives the number of minutes to add to the current time for daylight savings time.
DayOfMonthType Enum
Purpose
The DayOfMonth
enum specifies the different day-of-the-week numeric values that are returned by the DayOfMonth()
function. These values are used to represent repeating appointments that occur on specific days of the month; for example, the first Friday or the third Tuesday of each month.
Prototype
typedef enum { dom1stSun, dom1stMon, dom1stTue, dom1stWen, dom1stThu, dom1stFri, dom1stSat, dom2ndSun, dom2ndMon, dom2ndTue, dom2ndWen, dom2ndThu, dom2ndFri, dom2ndSat, dom3rdSun, dom3rdMon, dom3rdTue, dom3rdWen, dom3rdThu, dom3rdFri, dom3rdSat, dom4thSun, dom4thMon, dom4thTue, dom4thWen, dom4thThu, dom4thFri, dom4thSat, domLastSun, domLastMon, domLastTue, domLastWen, domLastThu, domLastFri, domLastSat } DayOfWeekType;
Constants
-
dom1stSun
- The first Sunday of the month.
-
dom1stMon
- The first Monday of the month.
-
dom1stTue
- The first Tuesday of the month.
-
dom1stWen
- The first Wednesday of the month.
-
dom1stThu
- The first Thursday of the month.
-
dom1stFri
- The first Friday of the month.
-
dom1stSat
- The first Saturday of the month.
-
dom2ndSun
- The second Sunday of the month.
-
dom2ndMon
- The second Monday of the month.
-
dom2ndTue
- The second Tuesday of the month.
-
dom2ndWen
- The second Wednesday of the month.
-
dom2ndThu
- The second Thursday of the month.
-
dom2ndFri
- The second Friday of the month.
-
dom2ndSat
- The second Saturday of the month.
-
dom3rdSun
- The third Sunday of the month.
-
dom3rdMon
- The third Monday of the month.
-
dom3rdTue
- The third Tuesday of the month.
-
dom3rdWen
- The third Wednesday of the month.
-
dom3rdThu
- The third Thursday of the month.
-
dom3rdFri
- The third Friday of the month.
-
dom3rdSat
- The third Saturday of the month.
-
dom4thSun
- The fourth Sunday of the month.
-
dom4thMon
- The fourth Monday of the month.
-
dom4thTue
- The fourth Tuesday of the month.
-
dom4thWen
- The fourth Wednesday of the month.
-
dom4thThu
- The fourth Thursday of the month.
-
dom4thFri
- The fourth Friday of the month.
-
dom4thSat
- The fourth Saturday of the month.
-
domLastSun
- The last Sunday of the month.
-
domLastMon
- The last Monday of the month.
-
domLastTue
- The last Tuesday of the month.
-
domLastWen
- The last Wednesday of the month.
-
domLastThu
- The last Thursday of the month.
-
domLastFri
- The last Friday of the month.
-
domLastSat
- The last Saturday of the month.
Compatibility
On Palm OS versions earlier than 4.0, this type was named DayOfWeekType
.
TimeFormatType Enum
Purpose
The TimeFormatType
enum specifies the different display formats for time values.
Prototype
typedef enum { tfColon, tfColonAMPM, tfColon24h, tfDot, tfDotAMPM, tfDot24h, tfHoursAMPM, tfHours24h, tfComma24h, } TimeFormatType;
typedef TimeFormatType *TimeFormatPtr;
Constants
-
tfColon
- The hour and minutes separated by a colon character. For example,
1:00
. -
tfColonAMPM
- The hour and minutes separated by a colon and followed by an AM/PM indication. For example,
1:00 pm
. -
tfColon24h
- The 24-hour time with the hour and minutes separated by a colon character. For example,
13:00
. -
tfDot
- The hour and minutes separated by a dot character. For example,
1.00
. -
tfDotAMPM
- The hour and minutes separated by a period and followed by an AM/PM indication. For example,
1.00 pm
. -
tfDot24h
- The 24-hour time with the hour and minutes separated by a dot character. For example,
13.00
. -
tfHoursAMPM
- The hour value followed by an AM/PM indication. For example,
1 pm
. -
tfHours24h
- The 24-hour value, followed by an AM/PM indication. For example,
13
. -
tfComma24h
- The 24-hour time with the hour and minutes separated by a comma character. For example,
13,00
.
TimeType Struct
Purpose
The TimeType
structure represents a time value.
Prototype
typedef struct { UInt8 hours; UInt8 minutes; } TimeType;
typedef TimeType *TimePtr;
Fields
-
hours
- The number of hours. This is a value between 0 and 23.
-
minutes
- The number of minutes. This is value between 0 and 59.
Time Manager Constants
The following table shows the constants that represent the maximum lengths of strings returned by the date and time formatting routines DateToAscii()
, DateToDOWDMFormat()
, and TimeToAscii()
.
Time Manager Functions
DateAdjust Function
Purpose
Return a new date +/- the days adjustment.
Declared In
DateTime.h
Prototype
void DateAdjust ( DateType *dateP, Int32 adjustment )
Parameters
-
↔
dateP
- A pointer to a
DateType
structure with the date to be adjusted. -
→
adjustment
- The number of days by which to adjust the date.
Returns
Returns nothing. Upon return, dateP
contains the adjusted date.
Comments
This function advances the date and manages month and year wrapping conditions.
See Also
DateDaysToDate Function
Purpose
Converts a date specified as the number of days since January 1, 1904 to a DateType
structure.
Declared In
DateTime.h
Prototype
void DateDaysToDate ( UInt32 days, DateType *dateP )
Parameters
-
→
days
- The number of days since 1/1/1904.
-
↔
dateP
- A pointer to a
DateType
structure that is updated with the computed date values.
Returns
Returns nothing. Upon return, the date information is returned in the structure referenced by the date
parameter.
See Also
DateSecondsToDate()
, DateToDays()
DateSecondsToDate Function
Purpose
Converts a date specified as the number of seconds since January 1, 1904 to a DateType
structure.
Declared In
DateTime.h
Prototype
void DateSecondsToDate ( UInt32 seconds, DateType *dateP )
Parameters
-
→
seconds
- The number of seconds since 1/1/1904.
-
←
dateP
- A pointer to a
DateType
structure that is updated with the computed date values.
Returns
Returns nothing. The structure referenced by the date
parameter is updated with the date information.
See Also
DateDaysToDate()
, DateToDays()
DateTemplateToAscii Function
Purpose
Convert the specified date values into a string that is formatted according to a formatting template specification.
Declared In
DateTime.h
Prototype
UInt16 DateTemplateToAscii ( const Char *templateP, UInt8 months, UInt8 days, UInt16 years, Char *stringP, Int16 stringLen )
Parameters
-
→
templateP
- A pointer to the template string used to format the date.
- See the Comments section below for details on how to specify date formatting in this template string.
-
→
months
- The month number, which must be a value between
1
and12
. -
→
days
- The day number, which must be a value between
1
and31
. -
→
years
- The four-digit year number. For example,
1995
. -
←
stringP
- A pointer to a string that is updated with the result.
- If
stringP
isNULL
, this function does not write an output string; however, it does return the length required for the output string. - If
stringP
is notNULL
, this function writes the formatted string tostringP
, writing up tostringSize
bytes intostringP
. -
→
stringLen
- The size of the
stringP
buffer.
Returns
The length of the formatted string, without the terminating null byte.
The DateTemplateToAscii
returns the required length of the formatted string even if the stringP
parameter is NULL
; this allows you to determine the buffer size at runtime.
Comments
This function is intended as a replacement for the DateToAscii()
and DateToDOWDMFormat()
functions.
This function uses the formatting template referenced by templateP
to create a formatted string from the date values that you pass in.
You specify a series of formatting substrings in templateP
. Each substring has the form:
^<valueType><formatModifier>
Each substring has three components:
- The
^
character begins a substring. - The
<valueType>
component is a single-digit value that specifies the value type. - The
<formatModifier>
component is a single-letter value that specifies how you want that value formatted.
The following is an example of a template specification with three substrings:
^0z ^2l ^4r
Table 57.1 shows the values you can specify for the <valueType
> component. Note that the formatted result depends on the <modifier
> value.
Table 57.1 Template value types for the DateTemplateToAscii function
Table 57.2 shows the values you can specify for the <modifier> component of each template substring.
Table 57.2 Template modifier types for the DateTemplateToAscii function
Finally, Table 57.3 shows examples of each value type formatted with each modifier type.
Table 57.3 Examples of formatted values
For example, calling DateTemplateToAscii
as follows:
DateTemplateToAscii("^0z ^2l ^4r", 2, 7, 2000, myStr, 20)
Produces the following formatted string:
07 February 2000
Compatibility
Implemented only if 3.5 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call DateGlueTemplateToAscii
. For more information, see Chapter 80, "PalmOSGlue Library."
See Also
DateToAscii()
, DateToDOWDMFormat()
DateToAscii Function
Purpose
Convert the passed date to a string using the format specified by the dateFormat
parameter.
Declared In
DateTime.h
Prototype
void DateToAscii ( UInt8 months, UInt8 days, UInt16 years, DateFormatType dateFormat, Char *pString )
Parameters
-
→
months
- The month number, which must be a value between
1
and12
. -
→
days
- The day number, which must be a value between
1
and31
. -
→
years
- The four-digit year number. For example,
1995
. -
→
dateFormat
- Any
DateFormatType
format. -
←
pString
- A pointer to string that is updated with the result.
- This string must be of length
dateStringLength
for short formats orlongDateStrLength
for medium or long formats. Note that these lengths do include the terminating null byte. For more information about required string lengths, see Time Manager Constants.
Returns
Returns nothing. The string reference by pString
is updated with the formatted string.
Comments
If you are using a debug ROM, the string buffer is filled with either dateStringLength
or longStrLength
debugging bytes, depending on the value of the dateFormat
parameter.
It is important to allocate enough space for your string buffer. Finding buffer overflow errors can be difficult when using a debug ROM. One common situation is when you pass a buffer that is too small from a form, for an element such as a label or title. Then, the buffer overflow can clobber objects that follow the form in memory. When a form element's location information is corrupted, it disappears from the display.
Note that you can use the DateTemplateToAscii()
function instead of this function if the 3.5 feature set is present. You can call the DateTemplateToAscii()
function with a NULL string buffer to predetermine the required size for your buffer.
See Also
TimeToAscii()
, DateToDOWDMFormat()
, DateTemplateToAscii()
DateToDays Function
Purpose
Convert the DateType
structure to the number of days elapsed from January 1, 1904.
Declared In
DateTime.h
Prototype
UInt32 DateToDays ( DateType date )
Parameters
-
→
date
- A
DateType
structure.
Returns
Returns the number of days elapsed from January 1, 1904 to the specified date
.
See Also
DateToDOWDMFormat Function
Purpose
Convert a date to a formatted string using the format specified by the dateFormat
parameter. The resultant string includes the name of the day of the week.
Declared In
DateTime.h
Prototype
void DateToDOWDMFormat ( UInt8 months, UInt8 days, UInt16 years, DateFormatType dateFormat, Char *pString )
Parameters
-
→
months
- The month number, which must be a value between
1
and12
. -
→
days
- The day number, which must be a value between
1
and31
. -
→
years
- The four-digit year number. For example,
1995
. -
→
dateFormat
- Any
DateFormatType
format. -
←
pString
- A pointer to a string that is updated with the result. The string must be of length
dowDateStringLength
for short formats ordowLongDateStrLength
for medium or long date formats. See Time Manager Constants for string buffer lengths.
Returns
Returns nothing. The string referenced by pString
is updated with the formatted string.
Comments
The values of some of the Time Manager Constants that specify the required string buffer lengths do change from time to time. You should always use the constants or verify the required lengths by checking the datetime.h
file.
It is important to allocate enough space for your string buffer. Finding buffer overflow errors can be difficult when using a debug ROM. One common situation is when you pass a buffer that is too small from a form, for an element such as a label or title. Then, the buffer overflow can clobber objects that follow the form in memory. When a form element's location information is corrupted, it disappears from the display.
Note that you can use the DateTemplateToAscii()
function instead of this function if the 3.5 feature set is present. You can call the DateTemplateToAscii()
function with a NULL
string buffer to predetermine the required size for your buffer.
Compatibility
On Palm OS 3.1 Japanese ROMs, this function contains a bug that prevented it from properly displaying 4-byte long day names. To prevent this bug from affecting your application, use DateGlueToDOWDMFormat
in the PalmOSGlue library instead of calling this function directly. For more information, see Chapter 80, "PalmOSGlue Library."
See Also
DateToAscii()
,
DateTemplateToAscii()
DayOfMonth Function
Purpose
Return a value that represents the day of a month on which the specified date occurs. The value represents a quantity such as "First Monday" or "Third Friday" as is used for repeating appointments in the Datebook.
Declared In
DateTime.h
Prototype
Int16 DayOfMonth ( Int16 month, Int16 day, Int16 year )
Parameters
-
→
month
- The month number, which must be a value between
1
and12
. -
→
day
- The day number, which must be a value between
1
and31
. -
→
year
- The four-digit year number. For example,
1995
.
Returns
Returns a value that represents day of the month. This value is one of the DayOfMonthType
values.
Comments
The returns value can be used to specify on which day of the month an appointment repeats.
DayOfWeek Function
Purpose
Return the day of the week value for a specified date.
Declared In
DateTime.h
Prototype
Int16 DayOfWeek ( Int16 month, Int16 day, Int16 year )
Parameters
-
→
month
- The month number, which must be a value between
1
and12
. -
→
day
- The day number, which must be a value between
1
and31
. -
→
year
- The four-digit year number. For example,
1995
.
Returns
Returns one of the following values for the day of the week of the specified date, as shown in the following table:
DaysInMonth Function
Purpose
Return the number of days in the month.
Declared In
DateTime.h
Prototype
Int16 DaysInMonth ( Int16 month, Int16 year )
Parameters
-
→
month
- The month number, which must be a value between
1
and12
. -
→
year
- The four-digit year number. For example,
1995
.
Returns
Returns the number of days in the month for the specified year.
TimAdjust Function
Purpose
Return a new date, with the time adjusted by the specified number of seconds.
Declared In
DateTime.h
Prototype
void TimAdjust ( DateTimeType *dateTimeP, Int32 adjustment )
Parameters
-
↔
dateTimeP
- A pointer to a
DateType
structure. -
→
adjustment
- The number of seconds by which to adjust the time.
Returns
Returns nothing. The structure referenced by dateTimeP
is modified to contain the updated date and time.
Comments
This function advances the time by the specified number of seconds and takes care of any wraparound conditions.
See Also
TimDateTimeToSeconds Function
Purpose
Return the number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the specified date and time.
Declared In
DateTime.h
Prototype
UInt32 TimDateTimeToSeconds ( const DateTimeType *dateTimeP )
Parameters
-
→
dateTimeP
- A pointer to a
DateTimeType
structure.
Returns
The number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the date referenced by dateTimeP
.
See Also
TimGetSeconds Function
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 TimGetSeconds ( void )
Parameters
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
TimGetTicks Function
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
UInt32 TimGetTicks ( void )
Parameters
Returns
Comments
You can call the SysTicksPerSecond()
routine to determine the number of ticks per second.
See Also
TimSecondsToDateTime Function
Purpose
Converts a date specified as the number of seconds since January 1, 1904 to a DateTimeType
structure.
Declared In
DateTime.h
Prototype
void TimSecondsToDateTime ( UInt32 seconds, DateTimeType *dateTimeP )
Parameters
-
→
seconds
- A date specified as the number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the date
-
←
dateTimeP
- A pointer to a
DateTimeType
structure that is updated with the date and time values.
Returns
Returns nothing. The structure referenced by dateTimeP
is updated with the date and time computed for the number of seconds since 12:00 A.M. on January 1, 1904.
See Also
TimSetSeconds Function
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
void TimSetSeconds ( UInt32 seconds )
Parameters
Returns
Comments
If the Notification Feature Set is present, this function broadcasts the sysNotifyTimeChangeEvent
to all interested parties. See Chapter 43, "Notification Manager," for more information.
See Also
TimeToAscii Function
Purpose
Convert the time to a string that is formatted according to the specified timeFormat
.
Declared In
DateTime.h
Prototype
void TimeToAscii ( UInt8 hours, UInt8 minutes, TimeFormatType timeFormat, Char *pString )
Parameters
-
→
hours
- The number of hours. This must be a value between
0
and23
. -
→
minutes
- The number of minutes. This must be a value between
0
and59
. -
→
timeFormat
- The time format for the resultant string. This must be one of the
TimeFormatType
values. -
←
pString
- A pointer to a string that is updated with the resultant string. This string must be of length
timeStringLength
. - See Time Manager Constants for information on string buffer lengths.
Returns
Returns nothing. The string referenced by pString
is updated with the formatted string.
Comments
If you are using a debug ROM in Palm OS 3.5, the string buffer is filled with timeStringLength
debugging bytes.
It is important to allocate enough space for your string buffer. Finding buffer overflow errors can be difficult when using a debug ROM. One common situation is when you pass a buffer that is too small from a form, for an element such as a label or title. Then, the buffer overflow can clobber objects that follow the form in memory. When a form element's location information is corrupted, it disappears from the display.
See Also
TimeZoneToAscii Function
Purpose
Convert a time zone to a string.
Declared In
DateTime.h
Prototype
void TimeZoneToAscii ( Int16 timeZone, const LmLocaleType *localeP, Char *string )
Parameters
-
→
timeZone
- A pointer to the time zone, given as minutes east of Greenwich Mean Time (GMT).
-
→
localeP
- A pointer to a locale (see
LmLocaleType
) that identifies the time zone country. You can use the constantlmAnyLanguage
as the value for the language field of the structure pointed to by this parameter. -
←
string
- A pointer to a string in which to return the result. This string must be of length
timeZoneStringLength
.
Returns
Comments
This function returns a descriptive string for the specified time zone. This string identifies the time zone first by its country, such as "USA (Mountain)" or "Canada (Eastern)." If the function cannot find a time zone that matches the specified GMT offset and country, it returns a string containing the time zone as a numeric offset from the GMT (for example, "GMT+9:00").
Compatibility
Implemented only if 4.0 New Feature Set is present.
TimTimeZoneToUTC Function
Purpose
Converts a date and time from a given time zone to Universal Coordinated Time (UTC). UTC is also known as Greenwich Mean Time (GMT).
Declared In
DateTime.h
Prototype
UInt32 TimTimeZoneToUTC ( UInt32 seconds, Int16 timeZone, Int16 daylightSavingAdjustment )
Parameters
-
→
seconds
- The number of seconds since 12:00 A.M. on January 1, 1904.
-
→
timeZone
- The time zone, given as the number of minutes east of UTC. For time zones west of UTC but before the international dateline, this is a negative number.
-
→
daylightSavingAdjustment
- The number of minutes to add to the current time for daylight savings time in this time zone.
Returns
Returns the same time as seconds
but in the Universal Coordinated Time. The value is still given as the number of seconds since 12:00 A.M. on January 1, 1904.
Comments
The returned value is not necessarily the time in Greenwich because Greenwich may be observing daylight saving time.
You can use this function to convert the local time to UTC. The time zone and the daylight savings adjustment are system preferences that can be retrieved using PrefGetPreference()
. For example, the following code converts the current local time to UTC:
Int16 timeZone = PrefGetPreference(prefTimeZone); Int16 daylightSavingAdjustment = PrefGetPreference( prefDaylightSavingAdjustment); UInt32 utcTime = TimTimeZoneToUTC(TimGetSeconds(), timeZone, daylightSavingAdjustment);
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
TimUTCToTimeZone Function
Purpose
Converts a date and time from Universal Coordinated Time (UTC) to the specified time zone. UTC is also known as Greenwich Mean Time (GMT).
Declared In
DateTime.h
Prototype
UInt32 TimUTCToTimeZone ( UInt32 seconds, Int16 timeZone, Int16 daylightSavingAdjustment )
Parameters
-
→
seconds
- The number of seconds since 12:00 A.M. on January 1, 1904 in UTC.
-
→
timeZone
- The time zone, given as the number of minutes east of UTC. For time zones west of UTC before the international dateline, this is a negative number.
-
→
daylightSavingAdjustment
- The number of minutes to add to the current time for daylight savings time in this time zone.
Returns
Returns the same time as seconds
but in the specified time zone. The value is still given as the number of seconds since 12:00 A.M. on January 1, 1904.
Comments
The seconds
value is not necessarily the time in Greenwich because Greenwich may be observing daylight saving time.
Compatibility
Implemented only if 4.0 New Feature Set is present.