/*
* Copyright (c) 2009 Apple Inc. All rights reserved.
*
* @APPLE_LICENSE_HEADER_START@
*
* This file contains Original Code and/or Modifications of Original Code
* as defined in and that are subject to the Apple Public Source License
* Version 2.0 (the 'License'). You may not use this file except in
* compliance with the License. Please obtain a copy of the License at
* http://www.opensource.apple.com/apsl/ and read it before using this
* file.
*
* The Original Code and all software distributed under the License are
* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
* Please see the License for the specific language governing rights and
* limitations under the License.
*
* @APPLE_LICENSE_HEADER_END@
*//* CFBundle.h
Copyright (c) 1999-2009, Apple Inc. All rights reserved.
*/
#if !defined(__COREFOUNDATION_CFBUNDLE__)
#define__COREFOUNDATION_CFBUNDLE__ 1
#include<CoreFoundation/CFBase.h>
#include<CoreFoundation/CFArray.h>
#include<CoreFoundation/CFDictionary.h>
#include<CoreFoundation/CFError.h>
#include<CoreFoundation/CFString.h>
#include<CoreFoundation/CFURL.h>
CF_EXTERN_C_BEGIN
typedefstruct __CFBundle *CFBundleRef;
typedefstruct __CFBundle *CFPlugInRef;
/* ===================== Standard Info.plist keys ===================== */
CF_EXPORT
const CFStringRef kCFBundleInfoDictionaryVersionKey;
/* The version of the Info.plist format */
CF_EXPORT
const CFStringRef kCFBundleExecutableKey;
/* The name of the executable in this bundle, if any */
CF_EXPORT
const CFStringRef kCFBundleIdentifierKey;
/* The bundle identifier (for CFBundleGetBundleWithIdentifier()) */
CF_EXPORT
const CFStringRef kCFBundleVersionKey;
/* The version number of the bundle. For Mac OS 9 style version numbers (for example "2.5.3d5"), *//* clients can use CFBundleGetVersionNumber() instead of accessing this key directly since that *//* function will properly convert the version string into its compact integer representation. */
CF_EXPORT
const CFStringRef kCFBundleDevelopmentRegionKey;
/* The name of the development language of the bundle. */
CF_EXPORT
const CFStringRef kCFBundleNameKey;
/* The human-readable name of the bundle. This key is often found in the InfoPlist.strings since it is usually localized. */
CF_EXPORT
const CFStringRef kCFBundleLocalizationsKey AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;
/* Allows an unbundled application that handles localization itself to specify which localizations it has available. *//* ===================== Finding Bundles ===================== */
CF_EXPORT
CFBundleRef CFBundleGetMainBundle(void);
CF_EXPORT
CFBundleRef CFBundleGetBundleWithIdentifier(CFStringRef bundleID);
/* A bundle can name itself by providing a key in the info dictionary. *//* This facility is meant to allow bundle-writers to get hold of their *//* bundle from their code without having to know where it was on the disk. *//* This is meant to be a replacement mechanism for +bundleForClass: users. *//* Note that this does not search for bundles on the disk; it will locate *//* only bundles already loaded or otherwise known to the current process. */
CF_EXPORT
CFArrayRef CFBundleGetAllBundles(void);
/* This is potentially expensive, and not thread-safe. Use with care. *//* Best used for debuggging or other diagnostic purposes. *//* ===================== Creating Bundles ===================== */
CF_EXPORT
CFTypeID CFBundleGetTypeID(void);
CF_EXPORT
CFBundleRef CFBundleCreate(CFAllocatorRef allocator, CFURLRef bundleURL);
/* Might return an existing instance with the ref-count bumped. */
CF_EXPORT
CFArrayRef CFBundleCreateBundlesFromDirectory(CFAllocatorRef allocator, CFURLRef directoryURL, CFStringRef bundleType);
/* Create instances for all bundles in the given directory matching the given type *//* (or all of them if bundleType is NULL). Instances are created using CFBundleCreate() and are not released. *//* ==================== Basic Bundle Info ==================== */
CF_EXPORT
CFURLRef CFBundleCopyBundleURL(CFBundleRef bundle);
CF_EXPORT
CFTypeRef CFBundleGetValueForInfoDictionaryKey(CFBundleRef bundle, CFStringRef key);
/* Returns a localized value if available, otherwise the global value. *//* This is the recommended function for examining the info dictionary. */
CF_EXPORT
CFDictionaryRef CFBundleGetInfoDictionary(CFBundleRef bundle);
/* This is the global info dictionary. Note that CFBundle may add *//* extra keys to the dictionary for its own use. */
CF_EXPORT
CFDictionaryRef CFBundleGetLocalInfoDictionary(CFBundleRef bundle);
/* This is the localized info dictionary. */
CF_EXPORT
voidCFBundleGetPackageInfo(CFBundleRef bundle, UInt32 *packageType, UInt32 *packageCreator);
CF_EXPORT
CFStringRef CFBundleGetIdentifier(CFBundleRef bundle);
CF_EXPORT
UInt32 CFBundleGetVersionNumber(CFBundleRef bundle);
CF_EXPORT
CFStringRef CFBundleGetDevelopmentRegion(CFBundleRef bundle);
CF_EXPORT
CFURLRef CFBundleCopySupportFilesDirectoryURL(CFBundleRef bundle);
CF_EXPORT
CFURLRef CFBundleCopyResourcesDirectoryURL(CFBundleRef bundle);
CF_EXPORT
CFURLRef CFBundleCopyPrivateFrameworksURL(CFBundleRef bundle);
CF_EXPORT
CFURLRef CFBundleCopySharedFrameworksURL(CFBundleRef bundle);
CF_EXPORT
CFURLRef CFBundleCopySharedSupportURL(CFBundleRef bundle);
CF_EXPORT
CFURLRef CFBundleCopyBuiltInPlugInsURL(CFBundleRef bundle);
/* ------------- Basic Bundle Info without a CFBundle instance ------------- *//* This API is provided to enable developers to retrieve basic information *//* about a bundle without having to create an instance of CFBundle. *//* Because of caching behavior when a CFBundle instance exists, it will be faster *//* to actually create a CFBundle if you need to retrieve multiple pieces of info. */
CF_EXPORT
CFDictionaryRef CFBundleCopyInfoDictionaryInDirectory(CFURLRef bundleURL);
CF_EXPORT
Boolean CFBundleGetPackageInfoInDirectory(CFURLRef url, UInt32 *packageType, UInt32 *packageCreator);
/* ==================== Resource Handling API ==================== */
CF_EXPORT
CFURLRef CFBundleCopyResourceURL(CFBundleRef bundle, CFStringRef resourceName, CFStringRef resourceType, CFStringRef subDirName);
CF_EXPORT
CFArrayRef CFBundleCopyResourceURLsOfType(CFBundleRef bundle, CFStringRef resourceType, CFStringRef subDirName);
CF_EXPORT
CFStringRef CFBundleCopyLocalizedString(CFBundleRef bundle, CFStringRef key, CFStringRef value, CFStringRef tableName) CF_FORMAT_ARGUMENT(2);
#defineCFCopyLocalizedString(key, comment) \
CFBundleCopyLocalizedString(CFBundleGetMainBundle(), (key), (key), NULL)
#defineCFCopyLocalizedStringFromTable(key, tbl, comment) \
CFBundleCopyLocalizedString(CFBundleGetMainBundle(), (key), (key), (tbl))
#defineCFCopyLocalizedStringFromTableInBundle(key, tbl, bundle, comment) \
CFBundleCopyLocalizedString((bundle), (key), (key), (tbl))
#defineCFCopyLocalizedStringWithDefaultValue(key, tbl, bundle, value, comment) \
CFBundleCopyLocalizedString((bundle), (key), (value), (tbl))
/* ------------- Resource Handling without a CFBundle instance ------------- *//* This API is provided to enable developers to use the CFBundle resource *//* searching policy without having to create an instance of CFBundle. *//* Because of caching behavior when a CFBundle instance exists, it will be faster *//* to actually create a CFBundle if you need to access several resources. */
CF_EXPORT
CFURLRef CFBundleCopyResourceURLInDirectory(CFURLRef bundleURL, CFStringRef resourceName, CFStringRef resourceType, CFStringRef subDirName);
CF_EXPORT
CFArrayRef CFBundleCopyResourceURLsOfTypeInDirectory(CFURLRef bundleURL, CFStringRef resourceType, CFStringRef subDirName);
/* =========== Localization-specific Resource Handling API =========== *//* This API allows finer-grained control over specific localizations, *//* as distinguished from the above API, which always uses the user's *//* preferred localizations for the bundle in the current app context. */
CF_EXPORT
CFArrayRef CFBundleCopyBundleLocalizations(CFBundleRef bundle);
/* Lists the localizations that a bundle contains. */
CF_EXPORT
CFArrayRef CFBundleCopyPreferredLocalizationsFromArray(CFArrayRef locArray);
/* Given an array of possible localizations, returns the one or more *//* of them that CFBundle would use in the current application context. *//* To determine the localizations that would be used for a particular *//* bundle in the current application context, apply this function to the *//* result of CFBundleCopyBundleLocalizations(). */
CF_EXPORT
CFArrayRef CFBundleCopyLocalizationsForPreferences(CFArrayRef locArray, CFArrayRef prefArray) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;
/* Given an array of possible localizations, returns the one or more of *//* them that CFBundle would use, without reference to the current application *//* context, if the user's preferred localizations were given by prefArray. *//* If prefArray is NULL, the current user's actual preferred localizations will *//* be used. This is not the same as CFBundleCopyPreferredLocalizationsFromArray(), *//* because that function takes the current application context into account. *//* To determine the localizations that another application would use, apply *//* this function to the result of CFBundleCopyBundleLocalizations(). */
CF_EXPORT
CFURLRef CFBundleCopyResourceURLForLocalization(CFBundleRef bundle, CFStringRef resourceName, CFStringRef resourceType, CFStringRef subDirName, CFStringRef localizationName);
CF_EXPORT
CFArrayRef CFBundleCopyResourceURLsOfTypeForLocalization(CFBundleRef bundle, CFStringRef resourceType, CFStringRef subDirName, CFStringRef localizationName);
/* The localizationName argument to CFBundleCopyResourceURLForLocalization() or *//* CFBundleCopyResourceURLsOfTypeForLocalization() must be identical to one of the *//* localizations in the bundle, as returned by CFBundleCopyBundleLocalizations(). *//* It is recommended that either CFBundleCopyPreferredLocalizationsFromArray() or *//* CFBundleCopyLocalizationsForPreferences() be used to select the localization. *//* =================== Unbundled application info ===================== *//* This API is provided to enable developers to retrieve bundle-related *//* information about an application that may be bundled or unbundled. */
CF_EXPORT
CFDictionaryRef CFBundleCopyInfoDictionaryForURL(CFURLRef url) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;
/* For a directory URL, this is equivalent to CFBundleCopyInfoDictionaryInDirectory(). *//* For a plain file URL representing an unbundled executable, this will attempt to read *//* an info dictionary from the (__TEXT, __info_plist) section, if it is a Mach-o file, *//* or from a 'plst' resource. */
CF_EXPORT
CFArrayRef CFBundleCopyLocalizationsForURL(CFURLRef url) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;
/* For a directory URL, this is equivalent to calling CFBundleCopyBundleLocalizations() *//* on the corresponding bundle. For a plain file URL representing an unbundled executable, *//* this will attempt to determine its localizations using the CFBundleLocalizations and *//* CFBundleDevelopmentRegion keys in the dictionary returned by CFBundleCopyInfoDictionaryForURL,*//* or from a 'vers' resource if those are not present. */
CF_EXPORT
CFArrayRef CFBundleCopyExecutableArchitecturesForURL(CFURLRef url) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
/* For a directory URL, this is equivalent to calling CFBundleCopyExecutableArchitectures() *//* on the corresponding bundle. For a plain file URL representing an unbundled executable, *//* this will return the architectures it provides, if it is a Mach-o file, or NULL otherwise. *//* ==================== Primitive Code Loading API ==================== *//* This API abstracts the various different executable formats supported on *//* various platforms. It can load DYLD, CFM, or DLL shared libraries (on their *//* appropriate platforms) and gives a uniform API for looking up functions. */
CF_EXPORT
CFURLRef CFBundleCopyExecutableURL(CFBundleRef bundle);
#ifMAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWEDenum {
kCFBundleExecutableArchitectureI386 = 0x00000007,
kCFBundleExecutableArchitecturePPC = 0x00000012,
kCFBundleExecutableArchitectureX86_64 = 0x01000007,
kCFBundleExecutableArchitecturePPC64 = 0x01000012
};
#endif/* MAC_OS_X_VERSION_10_5 <= MAC_OS_X_VERSION_MAX_ALLOWED */
CF_EXPORT
CFArrayRef CFBundleCopyExecutableArchitectures(CFBundleRef bundle) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
/* If the bundle's executable exists and is a Mach-o file, this function will return an array *//* of CFNumbers whose values are integers representing the architectures the file provides. *//* The values currently in use are those listed in the enum above, but others may be added *//* in the future. If the executable is not a Mach-o file, this function returns NULL. */
CF_EXPORT
Boolean CFBundlePreflightExecutable(CFBundleRef bundle, CFErrorRef *error) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
/* This function will return true if the bundle is loaded, or if the bundle appears to be *//* loadable upon inspection. This does not mean that the bundle is definitively loadable, *//* since it may fail to load due to link errors or other problems not readily detectable. *//* If this function detects problems, it will return false, and return a CFError by reference. *//* It is the responsibility of the caller to release the CFError. */
CF_EXPORT
Boolean CFBundleLoadExecutableAndReturnError(CFBundleRef bundle, CFErrorRef *error) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
/* If the bundle is already loaded, this function will return true. Otherwise, it will attempt *//* to load the bundle, and it will return true if that attempt succeeds. If the bundle fails *//* to load, this function will return false, and it will return a CFError by reference. *//* It is the responsibility of the caller to release the CFError. */
CF_EXPORT
Boolean CFBundleLoadExecutable(CFBundleRef bundle);
CF_EXPORT
Boolean CFBundleIsExecutableLoaded(CFBundleRef bundle);
CF_EXPORT
voidCFBundleUnloadExecutable(CFBundleRef bundle);
CF_EXPORT
void *CFBundleGetFunctionPointerForName(CFBundleRef bundle, CFStringRef functionName);
CF_EXPORT
voidCFBundleGetFunctionPointersForNames(CFBundleRef bundle, CFArrayRef functionNames, void *ftbl[]);
CF_EXPORT
void *CFBundleGetDataPointerForName(CFBundleRef bundle, CFStringRef symbolName);
CF_EXPORT
voidCFBundleGetDataPointersForNames(CFBundleRef bundle, CFArrayRef symbolNames, void *stbl[]);
CF_EXPORT
CFURLRef CFBundleCopyAuxiliaryExecutableURL(CFBundleRef bundle, CFStringRef executableName);
/* This function can be used to find executables other than your main *//* executable. This is useful, for instance, for applications that have *//* some command line tool that is packaged with and used by the application. *//* The tool can be packaged in the various platform executable directories *//* in the bundle and can be located with this function. This allows an *//* app to ship versions of the tool for each platform as it does for the *//* main app executable. *//* ==================== Getting a bundle's plugIn ==================== */
CF_EXPORT
CFPlugInRef CFBundleGetPlugIn(CFBundleRef bundle);
/* ==================== Resource Manager-Related API ==================== */
#if__LP64__typedefint CFBundleRefNum;
#elsetypedef SInt16 CFBundleRefNum;
#endif
CF_EXPORT
CFBundleRefNum CFBundleOpenBundleResourceMap(CFBundleRef bundle);
/* This function opens the non-localized and the localized resource files *//* (if any) for the bundle, creates and makes current a single read-only *//* resource map combining both, and returns a reference number for it. *//* If it is called multiple times, it opens the files multiple times, *//* and returns distinct reference numbers. */
CF_EXPORT
SInt32 CFBundleOpenBundleResourceFiles(CFBundleRef bundle, CFBundleRefNum *refNum, CFBundleRefNum *localizedRefNum);
/* Similar to CFBundleOpenBundleResourceMap(), except that it creates two *//* separate resource maps and returns reference numbers for both. */
CF_EXPORT
voidCFBundleCloseBundleResourceMap(CFBundleRef bundle, CFBundleRefNum refNum);
CF_EXTERN_C_END
#endif/* ! __COREFOUNDATION_CFBUNDLE__ */