< Previous PageNext Page > Hide TOC

Getting Information From a Bundle

Both CFBundle and NSBundle contain interfaces for retrieving information about the bundle itself. From an appropriate bundle object, you can retrieve path information for the bundle as well as configuration data from its information property list. Remember though that the bundle provides information as read-only data. For information on how to modify the value of a property list from Core Foundation, see Property List Programming Topics for Core Foundation.

Contents:

Getting Path Information
Getting Configuration Data

Getting Path Information

With a valid bundle object, you can retrieve the path to the bundle as well as paths to many of its subdirectories. Modern bundles can contain many specific subdirectories (see “Anatomy of a Modern Bundle”). Most of these directories contain plug-ins and other executable code or they contain various types of resource files used by the application. Using the available interfaces to retrieve directory paths insulates your code from having to know the exact structure of the bundle.

Core Foundation defines functions for retrieving several different internal bundle directories. To get the path of the bundle itself, you can use the CFBundleCopyBundleURL function. Core Foundation always returns bundle paths in a CFURLRef object. You can use this object to extract a CFStringRef that you can then pass to other Core Foundation routines. For a complete list of path-based functions, see the CFBundle Reference.

NSBundle also contains similar methods for retrieving paths to a bundle’s internal directories. It also contains a bundlePath method for getting the path to the bundle itself. However, NSBundle returns path information in an NSString object, which you can pass directly to most other NSBundle methods. For more information, see the NSBundle class description.

Getting Configuration Data

One file that every bundle should contain is an information property list (Info.plist) file. This file is an XML-based text file that contains specific types of key-value pairs. These key-value pairs specify information about the bundle, such as its ID string, version number, development region, type, and other important properties. (See Runtime Configuration Guidelines for the list of keys you can include in this file.) Bundles may also include other types of configuration data, mostly organized in XML-based property lists.

Core Foundation offers functions for retrieving several specific pieces of data from a bundle’s information property list file, including the bundle’s ID string, version, and development region. You can retrieve the localized value for a key using the CFBundleGetValueForInfoDictionaryKey function. You can also retrieve the entire dictionary of non-localized keys using CFBundleGetInfoDictionary. See CFBundle Reference for a complete list of functions.

NSBundle provides the objectForInfoDictionaryKey: and infoDictionary methods for retrieving information property list data. The objectForInfoDictionaryKey: method returns the localized value for a key and is the preferred method to call. The infoDictionary method returns an NSDictionary with all of the keys from the property list; however, it does not return any localized values for these keys. For more information, see the NSBundle class description.

Listing 1 demonstrates how to retrieve the bundle’s version number from the information property list using Core Foundation functions. Though the value in the information property list may be written as a string, for example “2.1.0b7”, the value is returned as an unsigned long integer similar to the value in a vers resource on Mac OS 9.

Listing 1  Obtaining the bundle’s version

    // This is the ‘vers’ resource style value for 1.0.0

    #define kMyBundleVersion1 0x01008000

    UInt32  bundleVersion;

    // Look for the bundle’s version number.

    bundleVersion = CFBundleGetVersionNumber( mainBundle );

    // Check the bundle version for compatibility with the app.

    if (bundleVersion < kMyBundleVersion1)

        return (kErrorFatalBundleTooOld);

Listing 2 shows you how to retrieve arbitrary values from the information property list using CFBundleGetInfoDictionary. Because the resulting information property list is an instance of the standard Core Foundation type CFDictionaryRef, you can use the dictionary lookup routines from CFDictionary.h to find and retrieve your properties.

Listing 2  Retrieving information from a bundle’s information property list

    CFDictionaryRef bundleInfoDict;

    CFStringRef     myPropertyString;

    // Get an instance of the non-localized keys.

    bundleInfoDict = CFBundleGetInfoDictionary( myBundle );

    // If we succeeded, look for our property.

    if ( bundleInfoDict != NULL ) {

        myPropertyString = CFDictionaryGetValue( bundleInfoDict,

                    CFSTR("MyPropertyKey") );

    }

It is also possible to obtain an instance of a bundle’s information dictionary without a bundle object. To do this you use either the Core Foundation function CFBundleCopyInfoDictionaryInDirectory or the Cocoa NSDictionary class. This can be useful for searching the information property lists of a set of bundles without first creating bundle objects.

< Previous PageNext Page > Hide TOC