Class: NSBundle

Returns an array of all of the application’s bundles that represent frameworks. The returned array includes frameworks that are linked into an application when the application is built and bundles for frameworks that have been dynamically created.

Returns the NSBundle object with which the specified class is associated.

Returns the previously created NSBundle instance that has the specified bundle identifier. This method is typically used by frameworks and plug-ins to locate their own bundle at runtime. This method may be somewhat more efficient than trying to locate the bundle using the bundleForClass: method. However, if the initial lookup of an already loaded and cached bundle with the specified identifier fails, this method uses potentially time-consuming heuristics to attempt to locate the bundle.

Returns an NSBundle object that corresponds to the specified directory. This method allocates and initializes the returned object if there is no existing NSBundle associated with fullPath, in which case it returns the existing object.

Returns an NSBundle object that corresponds to the specified file URL. This method allocates and initializes the returned object if there is no existing NSBundle associated with url, in which case it returns the existing object.

Returns the NSBundle object that corresponds to the directory where the current application executable is located. This method allocates and initializes a bundle object if one doesn’t already exist. The new object corresponds to the directory where the application executable is located. Be sure to check the return value to make sure you have a valid bundle. This method may return a valid bundle object even for unbundled applications. In general, the main bundle corresponds to an application file package or application wrapper: a directory that bears the name of the application and is marked by a “.app” extension.

Returns the full pathname for the resource file identified by the specified name and extension and residing in a given bundle directory. The method first looks for a matching resource file in the non-localized resource directory of the specified bundle. (In OS X, this directory is typically called Resources but in iOS, it is the main bundle directory.) If a matching resource file is not found, it then looks in the top level of any available language-specific “.lproj” directories. (The search order for the language-specific directories corresponds to the user’s preferences.) It does not recurse through other subdirectories at any of these locations. For more details see Internationalization Programming Topics.Note: This method is best suited only for the occasional retrieval of resource files. In most cases where you need to retrieve bundle resources, it is preferable to use the NSBundle instance methods instead.

Returns an array containing the pathnames for all bundle resources having the specified extension and residing in the bundle directory at the specified path. This method provides a means for dynamically discovering multiple bundle resources of the same type. The method first looks for matching resource files in the nonlocalized resource directory of the specified bundle. (In OS X, this directory is typically called Resources but in iOS, it is the main bundle directory.) It then looks in the top level of any available language-specific “.lproj” directories. It does not recurse through other subdirectories at any of these locations. For more details see Internationalization Programming Topics.Note: This method is best suited only for the occasional retrieval of resource files. In most cases where you need to retrieve bundle resources, it is preferable to use the NSBundle instance methods instead.

Returns one or more localizations from the specified list that a bundle object would use to locate resources for the current user. This method does not return all localizations in preference order but only those from which NSBundle would get localized content, typically either a single non-region-specific localization or a region-specific localization followed by a corresponding non-region-specific localization as a fallback.However, clients who want all localizations in preference order can make repeated calls, each time taking the top localizations out of the list of localizations passed in.

Returns the localizations that a bundle object would prefer, given the specified bundle and user preference localizations. This method does not return all localizations in preference order but only those from which NSBundle would get localized content, typically either a single non-region-specific localization or a region-specific localization followed by a corresponding non-region-specific localization as a fallback.However, clients who want all localizations in preference order can make repeated calls, each time taking the top localizations out of the list of localizations passed in.

Creates and returns a file URL for the resource with the specified name and extension in the specified bundle.

Returns an array containing the file URLs for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, within the specified bundle.

Returns the file URL of the receiver's subdirectory containing plug-ins. This method returns the appropriate path for modern application and framework bundles. This method may not return a URL for non-standard bundle formats or for some older bundle formats.

Returns the receiver’s bundle identifier.

Returns the full pathname of the receiver’s bundle directory.

Returns the full URL of the receiver’s bundle directory.

Returns the Class object for the specified name. If the bundle’s executable code is not yet loaded, this method dynamically loads it into memory. Classes (and categories) are loaded from just one file within the bundle directory; this code file has the same name as the directory, but without the extension (“.bundle”, “.app”, “.framework”). As a side effect of code loading, the receiver posts NSBundleDidLoadNotification after all classes and categories have been loaded; see “Notifications” for details.

Returns the localization used to create the bundle. The returned localization corresponds to the value in the CFBundleDevelopmentRegion key of the bundle’s property list (Info.plist).

Returns an array of numbers indicating the architecture types supported by the bundle’s executable. This method scans the bundle’s Mach-O executable and returns all of the architecture types it finds. Because they are taken directly from the executable, the returned values may not always correspond to one of the well-known CPU types defined in “Mach-O Architecture.”

Returns the full pathname of the receiver's executable file.

Returns the file URL of the receiver's executable file.

Returns a dictionary that contains information about the receiver. Common keys for accessing the values of the dictionary are CFBundleIdentifier, NSMainNibFile, and NSPrincipalClass.

Returns an NSBundle object initialized to correspond to the specified directory. It’s not necessary to allocate and initialize an instance for the main bundle; use the mainBundle class method to get this instance. You can also use the bundleWithPath: class method to obtain a bundle identified by its directory path.

Returns an NSBundle object initialized to correspond to the specified file URL. It’s not necessary to allocate and initialize an instance for the main bundle; use the mainBundle class method to get this instance. You can also use the bundleWithURL: class method to obtain a bundle identified by its file URL.

Obtains information about the load status of a bundle.

Dynamically loads the bundle’s executable code into a running program, if the code has not already been loaded. You can use this method to load the code associated with a dynamically loaded bundle, such as a plug-in or framework. Prior to OS X version 10.5, a bundle would attempt to load its code—if it had any—only once. Once loaded, you could not unload that code. In OS X version 10.5 and later, you can unload a bundle’s executable code using the unload method. You don’t need to load a bundle’s executable code to search the bundle’s resources.

Loads the bundle’s executable code and returns any errors. If this method returns NO and you pass a value for the error parameter, a suitable error object is returned in that parameter. Potential errors returned are in the Cocoa error domain and include the types that follow. For a full list of error types, see FoundationErrors.h. NSFileNoSuchFileError - returned if the bundle’s executable file was not located.NSExecutableNotLoadableError - returned if the bundle’s executable file exists but could not be loaded. This error is returned if the executable is not recognized as a loadable executable. It can also be returned if the executable is a PEF/CFM executable but the current process does not support that type of executable. NSExecutableArchitectureMismatchError - returned if the bundle executable does not include code that matches the processor architecture of the current processor. NSExecutableRuntimeMismatchError - returned if the bundle’s required Objective-C runtime information is not compatible with the runtime of the current process.NSExecutableLoadError - returned if the bundle’s executable failed to load for some detectable reason prior to linking. This error might occur if the bundle depends on a framework or library that is missing or if the required framework or library is not compatible with the current architecture or runtime version.NSExecutableLinkError - returned if the executable failed to load due to link errors but is otherwise alright.The error object may contain additional debugging information in its description that you can use to identify the cause of the error. (This debugging information should not be displayed to the user.) You can obtain the debugging information by invoking the error object’s description method in your code or by using the print-object command on the error object in gdb.

Returns a list of all the localizations contained within the receiver’s bundle.

Returns a dictionary with the keys from the bundle’s localized property list. This method uses the preferred localization for the current user when determining which resources to return. If the preferred localization is not available, this method chooses the most appropriate localization found in the bundle.

Returns a localized version of the string designated by the specified key and residing in the specified table. For more details about string localization and the specification of a .strings file, see ““String Resources”.”Using the user default NSShowNonLocalizedStrings, you can alter the behavior of localizedStringForKey:value:table: to log a message when the method can’t find a localized string. If you set this default to YES (in the global domain or in the application’s domain), then when the method can’t find a localized string in the table, it logs a message to the console and capitalizes key before returning it.The following example cycles through a static array of keys when a button is clicked, gets the value for each key from a strings table named Buttons.strings, and sets the button title with the returned value:

Returns the value associated with the specified key in the receiver's information property list. Use of this method is preferred over other access methods because it returns the localized value of a key when one is available.

Returns the full pathname of the executable with the specified name in the receiver’s bundle. This method returns the appropriate path for modern application and framework bundles. This method may not return a path for non-standard bundle formats or for some older bundle formats.

Returns the full pathname for the resource identified by the specified name and file extension. The method first looks for a matching resource file in the non-localized resource directory of the specified bundle. (In OS X, this directory is typically called Resources but in iOS, it is the main bundle directory.) If a matching resource file is not found, it then looks in the top level of any available language-specific “.lproj” directories. (The search order for the language-specific directories corresponds to the user’s preferences.) It does not recurse through other subdirectories at any of these locations. For more details see Internationalization Programming Topics.The following code fragment gets the path to a plist within the bundle, and loads it into an NSDictionary.

Returns the full pathname for the resource identified by the specified name and file extension and located in the specified bundle subdirectory. If subpath is nil, this method searches the top-level nonlocalized resource directory and the top-level of any language-specific directories. (In OS X, the top-level nonlocalized resource directory is typically called Resources but in iOS, it is the main bundle directory.) For example, suppose you have a Mac app with a modern bundle and you specify @“Documentation” for the subpath parameter. This method would first look in the Contents/Resources/Documentation directory of the bundle, followed by the Documentation subdirectories of each language-specific .lproj directory. Whether this method recurses through subdirectories is dependent on the extension parameter. If nil or an empty string it will recurse, otherwise, it does not. (The search order for the language-specific directories corresponds to the user’s preferences.) For more details see Internationalization Programming Topics.

Returns the full pathname for the resource identified by the specified name and file extension, located in the specified bundle subdirectory, and limited to global resources and those associated with the specified localization. This method is equivalent to pathForResource:ofType:inDirectory:, except that only nonlocalized resources and those in the language-specific .lproj directory specified by localizationName are searched.There should typically be little reason to use this method—see “Getting the Current Language and Locale”. See also preferredLocalizationsFromArray:forPreferences: for how to determine what localizations are available.

Returns an array containing the pathnames for all bundle resources having the specified filename extension and residing in the resource subdirectory. This method provides a means for dynamically discovering multiple bundle resources of the same type. If extension is an empty string or nil, all bundle resources in the specified resource directory are returned. The argument subpath specifies the name of a specific subdirectory to search within the current bundle’s resource directory hierarchy. If subpath is nil, this method searches the top-level nonlocalized resource directory and the top-level of any language-specific directories. (In OS X, the top-level nonlocalized resource directory is typically called Resources but in iOS, it is the main bundle directory.) For example, suppose you have a Mac app with a modern bundle and you specify @“Documentation” for the subpath parameter. This method would first look in the Contents/Resources/Documentation directory of the bundle, followed by the Documentation subdirectories of each language-specific .lproj directory. (The search order for the language-specific directories corresponds to the user’s preferences.) This method does not recurse through any other subdirectories at any of these locations. For more details see Internationalization Programming Topics.

Returns an array containing the file for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, and limited to global resources and those associated with the specified localization. This method is equivalent to pathsForResourcesOfType:inDirectory:, except that only nonlocalized resources and those in the language-specific .lproj directory specified by localizationName are searched.

Returns an array of strings indicating the actual localizations contained in the receiver’s bundle.

Returns a Boolean value indicating whether the bundle’s executable code could be loaded successfully. This method does not actually load the bundle’s executable code. Instead, it performs several checks to see if the code could be loaded and with one exception returns the same errors that would occur during an actual load operation. The one exception is the NSExecutableLinkError error, which requires the actual loading of the code to verify link errors. For a list of possible load errors, see the discussion for the loadAndReturnError: method.

Returns the receiver’s principal class. The principal class typically controls all the other classes in the bundle; it should mediate between those classes and classes external to the bundle. Classes (and categories) are loaded from just one file within the bundle directory. NSBundle obtains the name of the code file to load from the dictionary returned from infoDictionary, using “NSExecutable” as the key. The bundle determines its principal class in one of two ways:It first looks in its own information dictionary, which extracts the information encoded in the bundle’s property list (Info.plist). NSBundle obtains the principal class from the dictionary using the key NSPrincipalClass. For non-loadable bundles (applications and frameworks), if the principal class is not specified in the property list, the method returns nil. If the principal class is not specified in the information dictionary, NSBundle identifies the first class loaded as the principal class. When several classes are linked into a dynamically loadable file, the default principal class is the first one listed on the ld command line. In the following example, Reporter would be the principal class:The order of classes in Xcode’s project browser is the order in which they will be linked. To designate the principal class, control-drag the file containing its implementation to the top of the list.As a side effect of code loading, the receiver posts NSBundleDidLoadNotification after all classes and categories have been loaded; see “Notifications” for details. The following method obtains a bundle by specifying its path (bundleWithPath:), then loads the bundle with principalClass and uses the returned class object to allocate and initialize an instance of that class:

Returns the full pathname of the receiver's subdirectory containing private frameworks. This method returns the appropriate path for modern application and framework bundles. This method may not return a path for non-standard bundle formats or for some older bundle formats.

Returns the file URL of the receiver's subdirectory containing private frameworks. This method returns the appropriate path for modern application and framework bundles. This method may not return a URL for non-standard bundle formats or for some older bundle formats.

Returns the full pathname of the receiving bundle’s subdirectory containing resources.

Returns the file URL of the receiver's subdirectory containing resource files. This method returns the appropriate path for modern application and framework bundles. This method may not return a path for non-standard bundle formats or for some older bundle formats.

Returns the full pathname of the receiver's subdirectory containing shared frameworks. This method returns the appropriate path for modern application and framework bundles. This method may not return a path for non-standard bundle formats or for some older bundle formats.

Returns the file URL of the receiver's subdirectory containing shared frameworks. This method returns the appropriate path for modern application and framework bundles. This method may not return a URL for non-standard bundle formats or for some older bundle formats.

Returns the full pathname of the receiver's subdirectory containing shared support files. This method returns the appropriate path for modern application and framework bundles. This method may not return a path for non-standard bundle formats or for some older bundle formats.

Returns the file URL of the receiver's subdirectory containing shared support files. This method returns the appropriate path for modern application and framework bundles. This method may not return a path for non-standard bundle formats or for some older bundle formats.

Unloads the code associated with the receiver. This method attempts to unload a bundle’s executable code using the underlying dynamic loader (typically dyld). You may use this method to unload plug-in and framework bundles when you no longer need the code they contain. You should use this method to unload bundles that were loaded using the methods of the NSBundle class only. Do not use this method to unload bundles that were originally loaded using the bundle-manipulation functions in Core Foundation.It is the responsibility of the caller to ensure that no in-memory objects or data structures refer to the code being unloaded. For example, if you have an object whose class is defined in a bundle, you must release that object prior to unloading the bundle. Similarly, your code should not attempt to access any symbols defined in an unloaded bundle.

Returns the file URL of the executable with the specified name in the receiver’s bundle. This method returns the appropriate path for modern application and framework bundles. This method may not return a URL for non-standard bundle formats or for some older bundle formats.

Returns the file URL for the resource identified by the specified name and file extension. If extension is an empty string or nil, the returned pathname is the first one encountered where the file name exactly matches name. The method first looks for a matching resource file in the nonlocalized resource directory of the specified bundle. (In OS X, this directory is typically called Resources but in iOS, it is the main bundle directory.) If a matching resource file is not found, it then looks in the top level of any available language-specific “.lproj” directories. (The search order for the language-specific directories corresponds to the user’s preferences.) It does not recurse through other subdirectories at any of these locations. For more details see Internationalization Programming Topics.

Returns the file URL for the resource file identified by the specified name and extension and residing in a given bundle directory. The method first looks for a matching resource file in the non-localized resource directory of the specified bundle. (In OS X, this directory is typically called Resources but in iOS, it is the main bundle directory.) If a matching resource file is not found, it then looks in the top level of any available language-specific “.lproj” directories. (The search order for the language-specific directories corresponds to the user’s preferences.) It does not recurse through other subdirectories at any of these locations. For more details see Internationalization Programming Topics.

Returns the file URL for the resource identified by the specified name and file extension, located in the specified bundle subdirectory, and limited to global resources and those associated with the specified localization. This method is equivalent to URLsForResourcesWithExtension:subdirectory:, except that only nonlocalized resources and those in the language-specific .lproj directory specified by localizationName are searched.There should typically be little reason to use this method—see “Getting the Current Language and Locale”. See also preferredLocalizationsFromArray:forPreferences: for how to determine what localizations are available.

Returns the file URL for the resource identified by the specified name and file extension and located in the specified bundle subdirectory. If subpath is nil, this method searches the top-level non-localized resource directory and the top-level of any language-specific directories. (In OS X, the top-level non-localized resource directory is typically called Resources but in iOS, it is the main bundle directory.) For example, suppose you have a Mac app with a modern bundle and you specify @“Documentation” for the subpath parameter. This method would first look in the Contents/Resources/Documentation directory of the bundle, followed by the Documentation subdirectories of each language-specific .lproj directory. (The search order for the language-specific directories corresponds to the user’s preferences.) This method does not recurse through any other subdirectories at any of these locations. For more details see Internationalization Programming Topics.

Returns an array containing the file URLs for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, and limited to global resources and those associated with the specified localization. This method is equivalent to URLsForResourcesWithExtension:subdirectory:, except that only nonlocalized resources and those in the language-specific .lproj directory specified by localizationName are searched.