CFBundle Reference

Overview

CFBundle allows you to use a folder hierarchy called a bundle to organize and locate many types of application resources including images, sounds, localized strings, and executable code. In OS X, bundles can also be used by CFM applications to load and execute functions from Mach-O frameworks. You can use bundles to support multiple languages or execute your application on multiple operating environments.

You create a bundle object using one of the CFBundleCreate... functions. CFBundle provides several functions for finding resources within a bundle. The CFBundleCopyResourceURL function returns the location of a resource of the specified name and type, and in the specified subdirectory. Use CFBundleCopyResourceURLForLocalization to restrict the search to a specific localization name. Use CFBundleCopyResourceURLsOfType to get the locations of all resources of a specified type.

CFBundle provides functions for getting bundle information, such as its identifier and information dictionary. Use the CFBundleGetIdentifier function to get the identifier of a bundle, and the CFBundleGetInfoDictionary function to get its information dictionary. The principal intended purpose for locating bundles by identifier is so that code (in frameworks, plugins, etc.) can find its own bundle.

You can also obtain locations of subdirectories in a bundle represented as CFURL objects. The CFBundleCopyExecutableURL function returns the location of the application’s executable. The functions CFBundleCopyResourceURL, CFBundleCopySharedFrameworksURL, CFBundleCopyPrivateFrameworksURL, CFBundleCopySharedSupportURL, and CFBundleCopyBuiltInPlugInsURL return the location of a bundle’s subdirectory containing resources, shared frameworks, private frameworks, shared support files, and plug-ins respectively.

Other functions are used to manage localizations. The CFBundleCopyLocalizedString and CFBundleCopyLocalizationsForURL functions return a localized string from a bundle’s strings file. The CFBundleCopyLocalizationsForPreferences function returns the localizations that CFBundle would prefer, given the specified bundle and user preference localizations.

Unlike some other Core Foundation opaque types with similar Cocoa Foundation names (such as CFString and NSString), NSBundle objects cannot be cast (“toll-free bridged”) to CFBundle objects.

Unlike NSBundle, which does not support unloading (because the Objective C runtime does not support the unloading of Objective C code), you can unload CFBundle objects.

CFBundleGetFunctionPointerForName and related calls automatically load a bundle if it is not already loaded. When the last reference to the CFBundle object is released and it is finally deallocated, then the code will be unloaded if it is still loaded and if the executable is of a type that supports unloading. If you keep this in mind, and if you make sure that everything that uses the bundle keeps a retain on the CFBundle object, then you can just use the bundle naturally and never have to worry about when it is loaded and unloaded.

On the other hand, if you want to manually manage when the bundle is loaded and unloaded, then you can use CFBundleLoadExecutable and CFBundleUnloadExecutable—although this technique is not recommended. These functions force immediate loading and unloading of the executable (if it has not already been loaded/unloaded, and in the case of unloading if the executable is of a type that supports unloading). If you do this, then the code calling CFBundleUnloadExecutable is responsible for making sure that there are no remaining references to anything in the bundle's code before it is unloaded. In the previous approach, by contrast, this responsibility can be distributed to the individual code sections that use the bundle, by making sure that each one keeps its own retain on the CFBundle object.

One further point about CFBundle reference counting: if you are taking the first approach, but do not actually wish the bundle’s code to be unloaded (as is often the case), or if you are taking the second approach of manually managing the unloading yourself, then in many cases you do not actually have to worry about releasing a CFBundle object. CFBundle instances are uniqued, so there is only one CFBundle object for a given bundle, and rarely are there so many bundles being considered at once that the memory usage for CFBundle objects would be significant. There are cases in which a process could create CFBundle objects for potentially an unlimited number of bundles, and such processes would wish to balance retains and releases carefully, but such cases are likely to be rare.

Note that it is best to compile any unloadable bundles with the flag -fno-constant-cfstrings—see Bundle Programming Guide for more details.

Functions by Task

Creating and Accessing Bundles

• CFBundleCreate
• CFBundleCreateBundlesFromDirectory
• CFBundleGetAllBundles
• CFBundleGetBundleWithIdentifier
• CFBundleGetMainBundle

Loading and Unloading a Bundle

• CFBundleIsExecutableLoaded
• CFBundlePreflightExecutable
• CFBundleLoadExecutable
• CFBundleLoadExecutableAndReturnError
• CFBundleUnloadExecutable

Finding Locations in a Bundle

• CFBundleCopyAuxiliaryExecutableURL
• CFBundleCopyBuiltInPlugInsURL
• CFBundleCopyExecutableURL
• CFBundleCopyPrivateFrameworksURL
• CFBundleCopyResourcesDirectoryURL
• CFBundleCopySharedFrameworksURL
• CFBundleCopySharedSupportURL
• CFBundleCopySupportFilesDirectoryURL

Locating Bundle Resources

• CFBundleCloseBundleResourceMap
• CFBundleCopyResourceURL
• CFBundleCopyResourceURLInDirectory
• CFBundleCopyResourceURLsOfType
• CFBundleCopyResourceURLsOfTypeInDirectory
• CFBundleCopyResourceURLForLocalization
• CFBundleCopyResourceURLsOfTypeForLocalization
• CFBundleOpenBundleResourceFiles
• CFBundleOpenBundleResourceMap

Managing Localizations

• CFBundleCopyBundleLocalizations
• CFBundleCopyLocalizedString
• CFBundleCopyLocalizationsForPreferences
• CFBundleCopyLocalizationsForURL
• CFBundleCopyPreferredLocalizationsFromArray
• CFCopyLocalizedString
• CFCopyLocalizedStringFromTable
• CFCopyLocalizedStringFromTableInBundle
• CFCopyLocalizedStringWithDefaultValue

Managing Executable Code

• CFBundleGetDataPointerForName
• CFBundleGetDataPointersForNames
• CFBundleGetFunctionPointerForName
• CFBundleGetFunctionPointersForNames
• CFBundleGetPlugIn

Getting Bundle Properties

• CFBundleCopyBundleURL
• CFBundleGetDevelopmentRegion
• CFBundleGetIdentifier
• CFBundleGetInfoDictionary
• CFBundleGetLocalInfoDictionary
• CFBundleGetValueForInfoDictionaryKey
• CFBundleCopyInfoDictionaryInDirectory
• CFBundleCopyInfoDictionaryForURL
• CFBundleGetPackageInfo
• CFBundleGetPackageInfoInDirectory
• CFBundleCopyExecutableArchitectures
• CFBundleCopyExecutableArchitecturesForURL
• CFBundleGetVersionNumber

Getting the CFBundle Type ID

• CFBundleGetTypeID

Functions

CFBundleCloseBundleResourceMap

Closes an open resource map for a bundle.

void CFBundleCloseBundleResourceMap (
   CFBundleRef bundle,
   CFBundleRefNum refNum
);

CFBundleCopyAuxiliaryExecutableURL

Returns the location of a bundle’s auxiliary executable code.

CFURLRef CFBundleCopyAuxiliaryExecutableURL (
   CFBundleRef bundle,
   CFStringRef executableName
);

CFBundleCopyBuiltInPlugInsURL

Returns the location of a bundle’s built in plug-in.

CFURLRef CFBundleCopyBuiltInPlugInsURL (
   CFBundleRef bundle
);

CFBundleCopyBundleLocalizations

Returns an array containing a bundle’s localizations.

CFArrayRef CFBundleCopyBundleLocalizations (
   CFBundleRef bundle
);

CFBundleCopyBundleURL

Returns the location of a bundle.

CFURLRef CFBundleCopyBundleURL (
   CFBundleRef bundle
);

CFBundleCopyExecutableArchitectures

Returns an array of CFNumbers representing the architectures a given bundle provides.

CFArrayRef CFBundleCopyExecutableArchitectures (
   CFBundleRef bundle
);

CFBundleCopyExecutableArchitecturesForURL

Returns an array of CFNumbers representing the architectures a given URL provides.

CFArrayRef CFBundleCopyExecutableArchitecturesForURL (
   CFURLRef url
);

CFBundleCopyExecutableURL

Returns the location of a bundle’s main executable code.

CFURLRef CFBundleCopyExecutableURL (
   CFBundleRef bundle
);

CFBundleCopyInfoDictionaryForURL

Returns the information dictionary for a given URL location.

CFDictionaryRef CFBundleCopyInfoDictionaryForURL (
   CFURLRef url
);

CFBundleCopyInfoDictionaryInDirectory

Returns a bundle’s information dictionary.

CFDictionaryRef CFBundleCopyInfoDictionaryInDirectory (
   CFURLRef bundleURL
);

CFBundleCopyLocalizationsForPreferences

Given an array of possible localizations and preferred locations, returns the one or more of them that CFBundle would use, without reference to the current application context.

CFArrayRef CFBundleCopyLocalizationsForPreferences (
   CFArrayRef locArray,
   CFArrayRef prefArray
);

CFBundleCopyLocalizationsForURL

Returns an array containing the localizations for a bundle or executable at a particular location.

CFArrayRef CFBundleCopyLocalizationsForURL (
   CFURLRef url
);

CFBundleCopyLocalizedString

Returns a localized string from a bundle’s strings file.

CFStringRef CFBundleCopyLocalizedString (
   CFBundleRef bundle,
   CFStringRef key,
   CFStringRef value,
   CFStringRef tableName
);

CFBundleCopyPreferredLocalizationsFromArray

Given an array of possible localizations, returns the one or more of them that CFBundle would use in the current application context.

CFArrayRef CFBundleCopyPreferredLocalizationsFromArray (
   CFArrayRef locArray
);

CFBundleCopyPrivateFrameworksURL

Returns the location of a bundle’s private Frameworks directory.

CFURLRef CFBundleCopyPrivateFrameworksURL (
   CFBundleRef bundle
);

CFBundleCopyResourcesDirectoryURL

Returns the location of a bundle’s Resources directory.

CFURLRef CFBundleCopyResourcesDirectoryURL (
   CFBundleRef bundle
);

CFBundleCopyResourceURL

Returns the location of a resource contained in the specified bundle.

CFURLRef CFBundleCopyResourceURL (
   CFBundleRef bundle,
   CFStringRef resourceName,
   CFStringRef resourceType,
   CFStringRef subDirName
);

CFBundleCopyResourceURL(bundle, CFSTR("Water1"), CFSTR("aiff"), CFSTR("WaterSounds"));

CFBundleCopyResourceURLForLocalization

Returns the location of a localized resource in a bundle.

CFURLRef CFBundleCopyResourceURLForLocalization (
   CFBundleRef bundle,
   CFStringRef resourceName,
   CFStringRef resourceType,
   CFStringRef subDirName,
   CFStringRef localizationName
);

CFBundleCopyResourceURLInDirectory

Returns the location of a resource contained in the specified bundle directory without requiring the creation of a CFBundle object.

CFURLRef CFBundleCopyResourceURLInDirectory (
   CFURLRef bundleURL,
   CFStringRef resourceName,
   CFStringRef resourceType,
   CFStringRef subDirName
);

CFBundleCopyResourceURLsOfType

Assembles an array of URLs specifying all of the resources of the specified type found in a bundle.

CFArrayRef CFBundleCopyResourceURLsOfType (
   CFBundleRef bundle,
   CFStringRef resourceType,
   CFStringRef subDirName
);

CFBundleCopyResourceURLsOfTypeForLocalization

Returns an array containing copies of the URL locations for a specified bundle, resource, and localization name.

CFArrayRef CFBundleCopyResourceURLsOfTypeForLocalization (
   CFBundleRef bundle,
   CFStringRef resourceType,
   CFStringRef subDirName,
   CFStringRef localizationName
);

CFBundleCopyResourceURLsOfTypeInDirectory

Returns an array of CFURL objects describing the locations of all resources in a bundle of the specified type without needing to create a CFBundle object.

CFArrayRef CFBundleCopyResourceURLsOfTypeInDirectory (
   CFURLRef bundleURL,
   CFStringRef resourceType,
   CFStringRef subDirName
);

CFBundleCopySharedFrameworksURL

Returns the location of a bundle’s shared frameworks directory.

CFURLRef CFBundleCopySharedFrameworksURL (
   CFBundleRef bundle
);

CFBundleCopySharedSupportURL

Returns the location of a bundle’s shared support files directory.

CFURLRef CFBundleCopySharedSupportURL (
   CFBundleRef bundle
);

CFBundleCopySupportFilesDirectoryURL

Returns the location of the bundle’s support files directory.

CFURLRef CFBundleCopySupportFilesDirectoryURL (
   CFBundleRef bundle
);

CFBundleCreate

Creates a CFBundle object.

CFBundleRef CFBundleCreate (
   CFAllocatorRef allocator,
   CFURLRef bundleURL
);

CFBundleCreateBundlesFromDirectory

Searches a directory and constructs an array of CFBundle objects from all valid bundles in the specified directory.

CFArrayRef CFBundleCreateBundlesFromDirectory (
   CFAllocatorRef allocator,
   CFURLRef directoryURL,
   CFStringRef bundleType
);

CFBundleGetAllBundles

Returns an array containing all of the bundles currently open in the application.

CFArrayRef CFBundleGetAllBundles (
   void
);

CFBundleGetBundleWithIdentifier

Locate a bundle given its program-defined identifier.

CFBundleRef CFBundleGetBundleWithIdentifier (
   CFStringRef bundleID
);

CFBundleGetDataPointerForName

Returns a data pointer to a symbol of the given name.

void * CFBundleGetDataPointerForName (
   CFBundleRef bundle,
   CFStringRef symbolName
);

CFBundleGetDataPointersForNames

Returns a C array of data pointer to symbols of the given names.

void CFBundleGetDataPointersForNames (
   CFBundleRef bundle,
   CFArrayRef symbolNames,
   void *stbl[]
);

CFBundleGetDevelopmentRegion

Returns the bundle’s development region from the bundle’s information property list.

CFStringRef CFBundleGetDevelopmentRegion (
   CFBundleRef bundle
);

CFBundleGetFunctionPointerForName

Returns a pointer to a function in a bundle’s executable code using the function name as the search key.

void * CFBundleGetFunctionPointerForName (
   CFBundleRef bundle,
   CFStringRef functionName
);

CFBundleGetFunctionPointersForNames

Constructs a function table containing pointers to all of the functions found in a bundle’s main executable code.

void CFBundleGetFunctionPointersForNames (
   CFBundleRef bundle,
   CFArrayRef functionNames,
   void *ftbl[]
);

CFBundleGetIdentifier

Returns the bundle identifier from a bundle’s information property list.

CFStringRef CFBundleGetIdentifier (
   CFBundleRef bundle
);

CFBundleGetInfoDictionary

Returns a bundle’s information dictionary.

CFDictionaryRef CFBundleGetInfoDictionary (
   CFBundleRef bundle
);

CFBundleGetLocalInfoDictionary

Returns a bundle’s localized information dictionary.

CFDictionaryRef CFBundleGetLocalInfoDictionary (
   CFBundleRef bundle
);

CFBundleGetMainBundle

Returns an application’s main bundle.

CFBundleRef CFBundleGetMainBundle (
   void
);

CFBundleGetPackageInfo

Returns a bundle’s package type and creator.

void CFBundleGetPackageInfo (
   CFBundleRef bundle,
   UInt32 *packageType,
   UInt32 *packageCreator
);

CFBundleGetPackageInfoInDirectory

Returns a bundle’s package type and creator without having to create a CFBundle object.

Boolean CFBundleGetPackageInfoInDirectory (
   CFURLRef url,
   UInt32 *packageType,
   UInt32 *packageCreator
);

CFBundleGetPlugIn

Returns a bundle’s plug-in.

CFPlugInRef CFBundleGetPlugIn (
   CFBundleRef bundle
);

CFBundleGetTypeID

Returns the type identifier for the CFBundle opaque type.

CFTypeID CFBundleGetTypeID (
   void
);

CFBundleGetValueForInfoDictionaryKey

Returns a value (localized if possible) from a bundle’s information dictionary.

CFTypeRef CFBundleGetValueForInfoDictionaryKey (
   CFBundleRef bundle,
   CFStringRef key
);

CFBundleGetVersionNumber

Returns a bundle’s version number.

UInt32 CFBundleGetVersionNumber (
   CFBundleRef bundle
);

CFBundleIsExecutableLoaded

Obtains information about the load status for a bundle’s main executable.

Boolean CFBundleIsExecutableLoaded (
   CFBundleRef bundle
);

CFBundleLoadExecutable

Loads a bundle’s main executable code into memory and dynamically links it into the running application.

Boolean CFBundleLoadExecutable (
   CFBundleRef bundle
);

CFBundleLoadExecutableAndReturnError

Returns a Boolean value that indicates whether a given bundle is loaded, attempting to load it if necessary.

Boolean CFBundleLoadExecutableAndReturnError (
   CFBundleRef bundle,
   CFErrorRef *error
);

CFBundleOpenBundleResourceFiles

Opens the non-localized and localized resource files (if any) for a bundle in separate resource maps.

SInt32 CFBundleOpenBundleResourceFiles (
   CFBundleRef bundle,
   CFBundleRefNum *refNum,
   CFBundleRefNum *localizedRefNum
);

CFBundleOpenBundleResourceMap

Opens the non-localized and localized resource files (if any) for a bundle in a single resource map.

CFBundleRefNum CFBundleOpenBundleResourceMap (
   CFBundleRef bundle
);

CFBundlePreflightExecutable

Returns a Boolean value that indicates whether a given bundle is loaded or appears to be loadable.

Boolean CFBundlePreflightExecutable (
   CFBundleRef bundle,
   CFErrorRef *error
);

CFBundleUnloadExecutable

Unloads the main executable for the specified bundle.

void CFBundleUnloadExecutable (
   CFBundleRef bundle
);

CFCopyLocalizedString

Searches the default strings file Localizable.strings for the string associated with the specified key.

CFStringRef CFCopyLocalizedString (
   CFStringRef key,
   const char *comment
);

CFCopyLocalizedStringFromTable

Searches the specified strings file for the string associated with the specified key.

CFStringRef CFCopyLocalizedStringFromTable (
   CFStringRef key,
   CFStringRef tableName,
   const char *comment
);

CFCopyLocalizedStringFromTableInBundle

Returns a localized version of the specified string.

CFStringRef CFCopyLocalizedStringFromTableInBundle (
   CFStringRef key,
   CFStringRef tableName,
   CFBundleRef bundle,
   const char *comment
);

CFCopyLocalizedStringWithDefaultValue

Returns a localized version of a localization string.

CFStringRef CFCopyLocalizedStringWithDefaultValue (
   CFStringRef key,
   CFStringRef tableName,
   CFBundleRef bundle,
   CFStringRef value,
   const char *comment
);

Data Types

CFBundleRef

A reference to a CFBundle object.

typedef struct __CFBundle *CFBundleRef;

CFBundleRefNum

Type that identifies a distinct reference number for a resource map.

#if __LP64__
typedef int CFBundleRefNum;
#else /* __LP64__ */
typedef SInt16 CFBundleRefNum;
#endif /* __LP64__ */

Constants

Information Property List Keys

Standard keys found in a bundle’s information property list file.

const CFStringRef kCFBundleInfoDictionaryVersionKey;
const CFStringRef kCFBundleExecutableKey;
const CFStringRef kCFBundleIdentifierKey;
const CFStringRef kCFBundleVersionKey;
const CFStringRef kCFBundleDevelopmentRegionKey;
const CFStringRef kCFBundleNameKey;
const CFStringRef kCFBundleLocalizationsKey;

Constants

kCFBundleInfoDictionaryVersionKey

The version of the information property list format.

Available in iOS 2.0 and later.

Declared in CFBundle.h.

kCFBundleExecutableKey

The name of the executable in this bundle (if any).

Available in iOS 2.0 and later.

Declared in CFBundle.h.

kCFBundleIdentifierKey

The bundle identifier.

Available in iOS 2.0 and later.

Declared in CFBundle.h.

kCFBundleVersionKey

The version number of the bundle.

Available in iOS 2.0 and later.

Declared in CFBundle.h.

kCFBundleDevelopmentRegionKey

The name of the development language of the bundle.

When CFBundle looks for resources, the fallback is to look in the lproj whose name is given by the kCFBundleDevelopmentRegionKey in the Info.plist file. You must, therefore, ensure that a bundle contains an lproj with that exact name containing a copy of every localized resource, otherwise CFBundle cannot guarantee the fallback mechanism will work.

Available in iOS 2.0 and later.

Declared in CFBundle.h.

kCFBundleNameKey

The human-readable name of the bundle.

This key is often found in the InfoPlist.strings since it is usually localized.

Available in iOS 2.0 and later.

Declared in CFBundle.h.

kCFBundleLocalizationsKey

Allows an unbundled application that handles localization itself to specify which localizations it has available.

Available in iOS 2.0 and later.

Declared in CFBundle.h.

Architecture Types

Constants that identify executable architecture types.

enum {
   kCFBundleExecutableArchitectureI386     = 0x00000007,
   kCFBundleExecutableArchitecturePPC      = 0x00000012,
   kCFBundleExecutableArchitectureX86_64   = 0x01000007,
   kCFBundleExecutableArchitecturePPC64    = 0x01000012
};

Constants

kCFBundleExecutableArchitectureI386

Specifies the 32-bit Intel architecture.

Available in iOS 2.0 and later.

Declared in CFBundle.h.

kCFBundleExecutableArchitecturePPC

Specifies the 32-bit PowerPC architecture.

Available in iOS 2.0 and later.

Declared in CFBundle.h.

kCFBundleExecutableArchitectureX86_64

Specifies the 64-bit Intel architecture.

Available in iOS 2.0 and later.

Declared in CFBundle.h.

kCFBundleExecutableArchitecturePPC64

Specifies the 64-bit PowerPC architecture.

Available in iOS 2.0 and later.

Declared in CFBundle.h.