Getting the Main Bundle

The main bundle is the bundle that contains the code and resources for the running application. If you are an application developer, this is the most commonly used bundle. The main bundle is also the easiest to retrieve because it does not require you to provide any information.

To get the main bundle in a Cocoa application, call the mainBundle class method of the NSBundle class, as shown in Listing 3-1.

Listing 3-1  Getting a reference to the main bundle using Cocoa

NSBundle* mainBundle;

// Get the main bundle for the app.

mainBundle = [NSBundle mainBundle];

If you are writing a C-based application, you can use the CFBundleGetMainBundle function to retrieve the main bundle for your application, as shown in Listing 3-2.

Listing 3-2  Getting a reference to the main bundle using Core Foundation

CFBundleRef mainBundle;

// Get the main bundle for the app

mainBundle = CFBundleGetMainBundle();

When getting the main bundle, it is still a good idea to make sure the value you get back represents a valid bundle. When retrieving the main bundle from any application, the returned value might be NULL in the following situations:

• If a program is not bundled, attempting to get the main bundle might return a NULL value. The bundle code may try to create a main bundle to represent your program’s contents, but doing so is not possible in all cases.

• If the agent that launched the program did not specify the full path to the program's executable in the argv parameters, the main bundle value might be NULL. Bundles rely on either the path to the executable being in argv[0] or the presence of the executable's path in the PATH environment variable. If neither of these is present, the bundle routines might not be able to find the main bundle directory. Programs launched by xinetd often experience this problem when xinetd changes the current directory to /.

Getting Bundles by Path

If you want to access a bundle other than the main bundle, you can create an appropriate bundle object if you know the path to the bundle directory. Creating a bundle by path is useful in situations where you are defining frameworks or other loadable bundles and know in advance where those bundles will be located.

To obtain the bundle at a specific path using Cocoa, call the bundleWithPath: class method of the NSBundle class. (You can also use the initWithPath: instance method to initialize a new bundle object.) This method takes a string parameter representing the full path to the bundle directory. Listing 3-3 shows an example that accesses a bundle in a local directory.

Listing 3-3  Locating a Cocoa bundle using its path

NSBundle* myBundle;

// Obtain a reference to a loadable bundle.

myBundle = [NSBundle bundleWithPath:@"/Library/MyBundle.bundle"];

To obtain the bundle at a specific path using Core Foundation, call the CFBundleCreate function. When specifying the path location in Core Foundation, you must do so using a CFURLRef type. Listing 3-4 shows an example that takes the fixed directory from the preceding example, converts it to a URL, and uses that URL to access the bundle.

Listing 3-4  Locating a Core Foundation bundle using its path

CFURLRef bundleURL;

CFBundleRef myBundle;

// Make a CFURLRef from the CFString representation of the

// bundle’s path.

bundleURL = CFURLCreateWithFileSystemPath(

                kCFAllocatorDefault,

                CFSTR("/Library/MyBundle.bundle"),

                kCFURLPOSIXPathStyle,

                true );

// Make a bundle instance using the URLRef.

myBundle = CFBundleCreate( kCFAllocatorDefault, bundleURL );

// You can release the URL now.

CFRelease( bundleURL );

// Use the bundle...

// Release the bundle when done.

CFRelease( myBundle );

Getting Bundles in Known Directories

Even if you do not know the exact path to a bundle, you can still search for it in some known location. For example, an application with a PlugIns directory might want to get a list of all the bundles in that directory. Once you have the path to the directory, you can use the appropriate routines to iterate that directory and return any bundles.

The simplest way to find all of the bundles in a specific directory is to use the CFBundleCreateBundlesFromDirectory function. This function returns new CFBundleRef types for all of the bundles in a given directory. Listing 3-5 shows how you would use this function to retrieve all of the plug-ins in the application’s PlugIns directory.

Listing 3-5  Obtaining bundle references for a set of plug-ins

CFBundleRef mainBundle = CFBundleGetMainBundle();

CFURLRef plugInsURL;

CFArrayRef bundleArray;

// Get the URL to the application’s PlugIns directory.

plugInsURL = CFBundleCopyBuiltInPlugInsURL(mainBundle);

// Get the bundle objects for the application’s plug-ins.

bundleArray = CFBundleCreateBundlesFromDirectory( kCFAllocatorDefault,

                    plugInsURL, NULL );

// Release the CF objects when done with them.

CFRelease( plugInsURL );

CFRelease( bundleArray );

Getting Bundles by Identifier

Locating bundles using a bundle identifier is an efficient way to locate bundles that were previously loaded into memory. A bundle identifier is the string assigned to the CFBundleIdentifier key in the bundle’s Info.plist file. This string is typically formatted using reverse-DNS notation so as to prevent name space conflicts with developers in other companies. For example, a Finder plug-in from Apple might use the string com.apple.Finder.MyGetInfoPlugin as its bundle identifier. Rather than passing a pointer to a bundle object around your code, clients that need a reference to a bundle can simply use the bundle identifier to retrieve it.

To retrieve a bundle using a bundle identifier in Cocoa, call the bundleWithIdentifier: class method of the NSBundle class, as shown in Listing 3-6.

Listing 3-6  Locating a bundle using its identifier in Cocoa

NSBundle* myBundle = [NSBundle bundleWithIdentifier:@"com.apple.myPlugin"];

Listing 3-7 shows how to retrieve a bundle using its bundle identifier in Core Foundation.

Listing 3-7  Locating a bundle using its identifier in Core Foundation

CFBundleRef requestedBundle;

 // Look for a bundle using its identifier

 requestedBundle = CFBundleGetBundleWithIdentifier(

        CFSTR("com.apple.Finder.MyGetInfoPlugIn") );

Remember that you can only use a bundle identifier to locate a bundle that has already been opened. For example, you could use this technique to open the main bundle and bundles for all statically linked frameworks. You could not use this technique to get a reference to a plug-in that had not yet been loaded.

Searching for Related Bundles

If you are writing a Cocoa application, you can obtain a list of bundles related to the application by calling the allBundles and allFrameworks class methods of NSBundle. These methods create an array of NSBundle objects corresponding to the bundles or frameworks currently in use by your application. You can use these methods as convenience functions rather than maintain a collection of loaded bundles yourself.

The bundleForClass: class method is another way get related bundle information in a Cocoa application. This method returns the bundle in which a particular class is defined. Again, this method is mostly for convenience so that you do not have to retain a pointer to an NSBundle object that you may use only occasionally.

The Bundle Search Pattern

As long as you use an NSBundle object or a CFBundleRef opaque type to locate resources, your bundle code need never concern itself with how resources are retrieved from a bundle. Both NSBundle and CFBundleRef retrieve the appropriate language-specific resource automatically based on the available user settings and bundle configuration. However, you still have to put all those language-specific resources into your bundle, so knowing how they are retrieved is important.

The bundle programming interfaces follow a specific search algorithm to locate resources within the bundle. Global resources have the highest priority, followed by region- and language-specific resources. When considering region- and language-specific resources, the algorithm takes into account both the settings for the current user and development region information in the bundle’s Info.plist file.

First, the bundle determines which localization to use for the application as a whole. If a .lproj folder exists for the preferred language, that localization is used. Otherwise, the bundle searches for an .lproj folder matching the next preferred language, and so on, until one is found. If there is no localization for a preferred language, the bundle chooses the development language localization.

Then the bundle searches for the resource in the following order:

1. Global (nonlocalized) resources

2. Region-specific localized resources (based on the user’s region preferences)

3. Language-specific localized resources (based on the user’s language preferences)

4. Development language resources (as specified by the CFBundleDevelopmentRegion in the bundle’s Info.plist file.)

Because global resources take precedence over language-specific resources, there should never be both a global and localized version of a given resource. If a global version of a resource exists, language-specific versions of the same resource are never returned. The reason for this precedence is performance. If localized resources were searched first, the bundle routines might search needlessly in several localized resource directories before discovering the global resource.

Device-Specific Resources in iOS

In iOS 4.0 and later, it is possible to mark individual resource files as usable only on a specific type of device. This capability simplifies the code you have to write for Universal applications. Rather than creating separate code paths to load one version of a resource file for iPhone and a different version of the file for iPad, you can let the bundle-loading routines choose the correct file. All you have to do is name your resource files appropriately.

To associate a resource file with a particular device, you add a custom modifier string to its filename. The inclusion of this modifier string yields filenames with the following format:

<basename><device>.<filename_extension>

The <basename> string represents the original name of the resource file. It also represents the name you use when accessing the file from your code. Similarly, the <filename_extension> string is the standard filename extension used to identify the type of the file. The <device> string is a case-sensitive string that can be one of the following values:

• ~ipad - The resource should be loaded on iPad devices only.

• ~iphone - The resource should be loaded on iPhone or iPod touch devices only.

You can apply device modifiers to any type of resource file. For example, suppose you have an image named MyImage.png. To specify different versions of the image for iPad and iPhone, you would create resource files with the names MyImage~ipad.png and MyImage~iphone.png and include them both in your bundle. To load the image, you would continue to refer to the resource as MyImage.png in your code and let the system choose the appropriate version, as shown here:

UIImage* anImage = [UIImage imageNamed:@"MyImage.png"];

On an iPhone or iPod touch device, the system loads the MyImage~iphone.png resource file, while on iPad, it loads the MyImage~ipad.png resource file. If a device-specific version of a resource is not found, the system falls back to looking for a resource with the original filename, which in the preceding example would be an image named MyImage.png.

Getting the Path to a Resource

In order to locate a resource file in a bundle, you need to know the name of the file, its type, or a combination of the two. Filename extensions are used to identify the type of a file; therefore, it is important that your resource files include the appropriate extensions. If you used custom subdirectories in your bundle to organize resource files, you can speed up the search by providing the name of the subdirectory that contains the desired file.

Even if you do not have a bundle object, you can still search for resources in directories whose paths you know. Both Core Foundation and Cocoa provide API for searching for files using only path-based information. (For example, in Cocoa you can use the NSFileManager object to enumerate the contents of directories and test for the existence of files.) However, if you plan to retrieve more than one resource file, it is always faster to use a bundle object. Bundle objects cache search information as they go, so subsequent searches are usually faster.

NSBundle* myBundle = [NSBundle mainBundle];

NSString* myImage = [myBundle pathForResource:@"Seagull" ofType:@"jpg"];

NSBundle* myBundle = [NSBundle mainBundle];

NSArray* myImages = [myBundle pathsForResourcesOfType:@"jpg"

                              inDirectory:nil];

    CFURLRef    seagullURL;

    // Look for a resource in the main bundle by name and type.

    seagullURL = CFBundleCopyResourceURL( mainBundle,

                    CFSTR("Seagull"),

                    CFSTR("jpg"),

                    NULL );

    CFArrayRef  birdURLs;

    // Find all of the JPEG images in a given directory.

    birdURLs = CFBundleCopyResourceURLsOfType( mainBundle,

                    CFSTR("jpg"),

                    CFSTR("BirdImages") );

Opening and Using Resource Files

Once you have a reference to a resource file, you can load its contents and use it in your application. The steps you must take to load and use resource files depends on the type of resource, and as such is not covered in this document. For detailed information about loading and using resources, see Resource Programming Guide.

Loading Functions

If you are working in C, C++, or even in Objective-C, you can publish your interface as a set of C-based symbols, such as function pointers and global variables. Using the Core Foundation functions, you can load references to those symbols from a bundle’s executable file.

You can retrieve symbols using any of several functions. To retrieve function pointers, call either CFBundleGetFunctionPointerForName or CFBundleGetFunctionPointersForNames. To retrieve a pointer to a global variable, call CFBundleGetDataPointerForName or CFBundleGetDataPointersForNames. For example, suppose a loadable bundle defines the function shown in Listing 3-14.

Listing 3-14  An example function for a loadable bundle

    // Add one to the incoming value and return it.

    long addOne(short number)

    {

        return ( (long)number + 1 );

    }

Given a CFBundleRef opaque type, you would need to search for the desired function before you could use it in your code. Listing 3-15 shows a code fragment that illustrates this process. In this example, the myBundle variable is a CFBundleRef opaque type pointing to the bundle.

Listing 3-15  Finding a function in a loadable bundle

// Function pointer.

AddOneFunctionPtr addOne = NULL;

// Value returned from the loaded function.

long result = 0;

// Get a pointer to the function.

addOne = (void*)CFBundleGetFunctionPointerForName(

            myBundle, CFSTR("addOne") );

    // If the function was found, call it with a test value.

if (addOne)

{

    // This should add 1 to whatever was passed in

    result = addOne ( 23 );

}

Loading Objective-C Classes

If you are writing a Cocoa application, you can load the code for an entire class using the methods of NSBundle. The NSBundle methods for loading a class are for use with Objective-C classes only and cannot be used to load classes written in C++ or other object-oriented languages.

If a loadable bundle defines a principal class, you can load it using the principalClass method of NSBundle. The principalClass method uses the NSPrincipalClass key of the bundle’s Info.plist file to identify and load the desired class. Using the principal class alleviates the need to agree on specific naming conventions for external classes, instead letting you focus on the behavior of those interfaces. For example, you might use an instance of the principal class as a factory for creating other relevant objects.

If you want to load an arbitrary class from a loadable bundle, call the classNamed: method of NSBundle. This method searches the bundle for a class matching the name you specify. If the class exists in the bundle, the method returns the corresponding Class object, which you can then use to create instances of the class.

Listing 3-16 shows you a sample method for loading a bundle’s principal class.

Listing 3-16  Loading the principal class of a bundle

- (void)loadBundle:(NSString*)bundlePath

{

    Class exampleClass;

    id newInstance;

    NSBundle *bundleToLoad = [NSBundle bundleWithPath:bundlePath];

    if (exampleClass = [bundleToLoad principalClass])

    {

        newInstance = [[exampleClass alloc] init];

        // [newInstance doSomething];

    }

}

For more information about the methods of the NSBundle class, see NSBundle Class Reference.

Unloading Bundles

In macOS v10.5 and later, you can unload the code associated with an NSBundle object using the unload method. You might use this technique to free up memory in an application by removing plug-ins or other loadable bundles that you no longer need.

If you used Core Foundation to load your bundle, you can use the CFBundleUnloadExecutable function to unload it. If your bundle might be unloaded, you need to ensure that string constants are handled correctly by setting an appropriate compiler flag.

When you compile a bundle with a minimum deployment target of macOS v10.2 (or later), the compiler automatically switches to generating strings that are truly constant in response to CFSTR("..."). The compiler also generates these constant strings if you compile with the flag -fconstant-cfstrings. Constant strings have many benefits and should be used when possible, however if you reference constant strings after the executable containing them is unloaded, the references will be invalid and will cause a crash. This might happen even if the strings have been retained, for example, as a result of being put in data structures, retained directly, and, in some cases, even copied. Rather than trying to make sure all such references are cleaned up at unload time (and some references might be created within the libraries, making them hard to track), it is best to compile unloadable bundles with the flag -fno-constant-cfstrings.