CFTimeZone Reference

Overview

CFTimeZone defines the behavior of time zone objects. Time zone objects represent geopolitical regions. Consequently, these objects have names for these regions. Time zone objects also represent a temporal offset, either plus or minus, from Greenwich Mean Time (GMT) and an abbreviation (such as PST for Pacific Standard Time).

CFTimeZone provides several functions to create time zone objects: CFTimeZoneCreateWithName and CFTimeZoneCreateWithTimeIntervalFromGMT. CFTimeZone also permits you to set the default time zone within your application using the CFTimeZoneSetDefault function. You can access this default time zone at any time with the CFTimeZoneCopyDefault function.

CFTimeZone is “toll-free bridged” with its Cocoa Foundation counterpart, NSTimeZone. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSTimeZone * parameter, you can pass in a CFTimeZoneRef, and in a function where you see a CFTimeZoneRef parameter, you can pass in an NSTimeZone instance. This fact also applies to concrete subclasses of NSTimeZone. See “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating a Time Zone

• CFTimeZoneCreateWithName
• CFTimeZoneCreateWithTimeIntervalFromGMT
• CFTimeZoneCreate

System and Default Time Zones and Information

• CFTimeZoneCopyAbbreviationDictionary
• CFTimeZoneCopyAbbreviation
• CFTimeZoneCopyDefault
• CFTimeZoneCopySystem
• CFTimeZoneSetDefault
• CFTimeZoneCopyKnownNames
• CFTimeZoneResetSystem
• CFTimeZoneSetAbbreviationDictionary

Getting Information About Time Zones

• CFTimeZoneGetName
• CFTimeZoneCopyLocalizedName
• CFTimeZoneGetSecondsFromGMT
• CFTimeZoneGetData

Getting Daylight Savings Time Information

• CFTimeZoneIsDaylightSavingTime
• CFTimeZoneGetDaylightSavingTimeOffset
• CFTimeZoneGetNextDaylightSavingTimeTransition

Getting the CFTimeZone Type ID

• CFTimeZoneGetTypeID

Functions

CFTimeZoneCopyAbbreviation

Returns the abbreviation of a time zone at a specified date.

CFStringRef CFTimeZoneCopyAbbreviation (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

CFTimeZoneCopyAbbreviationDictionary

Returns a dictionary holding the mappings of time zone abbreviations to time zone names.

CFDictionaryRef CFTimeZoneCopyAbbreviationDictionary (
   void
);

CFTimeZoneCopyDefault

Returns the default time zone set for your application.

CFTimeZoneRef CFTimeZoneCopyDefault (
   void
);

CFTimeZoneCopyKnownNames

Returns an array of strings containing the names of all the time zones known to the system.

CFArrayRef CFTimeZoneCopyKnownNames (
   void
);

CFTimeZoneCopyLocalizedName

Returns the localized name of a given time zone.

CFStringRef CFTimeZoneCopyLocalizedName (
   CFTimeZoneRef tz,
   CFTimeZoneNameStyle style,
   CFLocaleRef locale
);

CFTimeZoneCopySystem

Returns the time zone currently used by the system.

CFTimeZoneRef CFTimeZoneCopySystem (
   void
);

CFTimeZoneCreate

Creates a time zone with a given name and data.

CFTimeZoneRef CFTimeZoneCreate (
   CFAllocatorRef allocator,
   CFStringRef name,
   CFDataRef data
);

CFTimeZoneCreateWithName

Returns the time zone object identified by a given name or abbreviation.

CFTimeZoneRef CFTimeZoneCreateWithName (
   CFAllocatorRef allocator,
   CFStringRef name,
   Boolean tryAbbrev
);

CFTimeZoneCreateWithTimeIntervalFromGMT

Returns a time zone object for the specified time interval offset from Greenwich Mean Time (GMT).

CFTimeZoneRef CFTimeZoneCreateWithTimeIntervalFromGMT (
   CFAllocatorRef allocator,
   CFTimeInterval ti
);

CFTimeZoneGetData

Returns the data that stores the information used by a time zone.

CFDataRef CFTimeZoneGetData (
   CFTimeZoneRef tz
);

CFTimeZoneGetDaylightSavingTimeOffset

Returns the daylight saving time offset for a time zone at a given time.

CFTimeInterval CFTimeZoneGetDaylightSavingTimeOffset (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

CFTimeZoneGetName

Returns the geopolitical region name that identifies a given time zone.

CFStringRef CFTimeZoneGetName (
   CFTimeZoneRef tz
);

CFTimeZoneGetNextDaylightSavingTimeTransition

Returns the time in a given time zone of the next daylight saving time transition after a given time.

CFAbsoluteTime CFTimeZoneGetNextDaylightSavingTimeTransition (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

CFTimeZoneGetSecondsFromGMT

Returns the difference in seconds between the receiver and Greenwich Mean Time (GMT) at the specified date.

CFTimeInterval CFTimeZoneGetSecondsFromGMT (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

CFTimeZoneGetTypeID

Returns the type identifier for the CFTimeZone opaque type.

CFTypeID CFTimeZoneGetTypeID (
   void
);

CFTimeZoneIsDaylightSavingTime

Returns whether or not a time zone is in daylight savings time at a specified date.

Boolean CFTimeZoneIsDaylightSavingTime (
   CFTimeZoneRef tz,
   CFAbsoluteTime at
);

CFTimeZoneResetSystem

Clears the previously determined system time zone, if any.

void CFTimeZoneResetSystem (
   void
);

CFTimeZoneSetAbbreviationDictionary

Sets the abbreviation dictionary to a given dictionary.

void CFTimeZoneSetAbbreviationDictionary (
   CFDictionaryRef dict
);

CFTimeZoneSetDefault

Sets the default time zone for your application the given time zone.

void CFTimeZoneSetDefault (
   CFTimeZoneRef tz
);

Data Types

CFTimeZoneNameStyle

Index type for constants used to specify styles of time zone names.

typedef CFIndex CFTimeZoneNameStyle;

CFTimeZoneRef

A reference to a CFTimeZone object.

typedef const struct __CFTimeZone *CFTimeZoneRef;

Constants

Notification Name

Name of the notification posted when the time zone changes.

const CFStringRef kCFTimeZoneSystemTimeZoneDidChangeNotification;

Constants

kCFTimeZoneSystemTimeZoneDidChangeNotification

Name of the notification posted when the system time zone changes.

The object of the notification is the previous system time zone object. This notification carries no user info.

Keep in mind that there is no order in how notifications are delivered to observers; frameworks or other parts of your code may also be observing this notification to take their own actions, and these may not have occurred by the time you receive the notification.

Available in OS X v10.5 and later.

Declared in CFTimeZone.h.

Time Zone Name Styles

Constants to specify styles for time zone names.

typedef enum : CFIndex {
   kCFTimeZoneNameStyleStandard,
   kCFTimeZoneNameStyleShortStandard,
   kCFTimeZoneNameStyleDaylightSaving,
   kCFTimeZoneNameStyleShortDaylightSaving,
   kCFTimeZoneNameStyleGeneric,
   kCFTimeZoneNameStyleShortGeneric
} CFTimeZoneNameStyle;

Constants

kCFTimeZoneNameStyleStandard

Specifies the standard name style; for example, “Central Standard Time” for the Central time zone.

Available in OS X v10.5 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleShortStandard

Specifies the short standard name style; for example, “CST” for the Central time zone.

Available in OS X v10.5 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleDaylightSaving

Specifies the daylight saving name style; for example, “Central Daylight Time” for the Central time zone.

Available in OS X v10.5 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleShortDaylightSaving

Specifies the short daylight saving name style; for example, “CDT” for the Central time zone.

Available in OS X v10.5 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleGeneric

Specifies the generic name style, which does not distinguish between daylight saving and standard time; for example, “Central Time” for the Central time zone.

Available in OS X v10.6 and later.

Declared in CFTimeZone.h.

kCFTimeZoneNameStyleShortGeneric

Specifies the short generic name style, which does not distinguish between daylight saving and standard time; for example, “CT” for the Central time zone.

Available in OS X v10.6 and later.

Declared in CFTimeZone.h.