1/* 2 * Copyright (c) 2014 Apple Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24/* CFBundle.h 25 Copyright (c) 1999-2013, Apple Inc. All rights reserved. 26*/ 27 28#if !defined(__COREFOUNDATION_CFBUNDLE__) 29#define __COREFOUNDATION_CFBUNDLE__ 1 30 31#include <CoreFoundation/CFBase.h> 32#include <CoreFoundation/CFArray.h> 33#include <CoreFoundation/CFDictionary.h> 34#include <CoreFoundation/CFError.h> 35#include <CoreFoundation/CFString.h> 36#include <CoreFoundation/CFURL.h> 37 38CF_EXTERN_C_BEGIN 39 40typedef struct __CFBundle *CFBundleRef; 41typedef struct __CFBundle *CFPlugInRef; 42 43/* ===================== Standard Info.plist keys ===================== */ 44CF_EXPORT 45const CFStringRef kCFBundleInfoDictionaryVersionKey; 46 /* The version of the Info.plist format */ 47CF_EXPORT 48const CFStringRef kCFBundleExecutableKey; 49 /* The name of the executable in this bundle, if any */ 50CF_EXPORT 51const CFStringRef kCFBundleIdentifierKey; 52 /* The bundle identifier (for CFBundleGetBundleWithIdentifier()) */ 53CF_EXPORT 54const CFStringRef kCFBundleVersionKey; 55 /* The version number of the bundle. For Mac OS 9 style version numbers (for example "2.5.3d5"), */ 56 /* clients can use CFBundleGetVersionNumber() instead of accessing this key directly since that */ 57 /* function will properly convert the version string into its compact integer representation. */ 58CF_EXPORT 59const CFStringRef kCFBundleDevelopmentRegionKey; 60 /* The name of the development language of the bundle. */ 61CF_EXPORT 62const CFStringRef kCFBundleNameKey; 63 /* The human-readable name of the bundle. This key is often found in the InfoPlist.strings since it is usually localized. */ 64CF_EXPORT 65const CFStringRef kCFBundleLocalizationsKey; 66 /* Allows an unbundled application that handles localization itself to specify which localizations it has available. */ 67 68/* ===================== Finding Bundles ===================== */ 69 70CF_EXPORT 71CFBundleRef CFBundleGetMainBundle(void); 72 73CF_EXPORT 74CFBundleRef CFBundleGetBundleWithIdentifier(CFStringRef bundleID); 75 /* A bundle can name itself by providing a key in the info dictionary. */ 76 /* This facility is meant to allow bundle-writers to get hold of their */ 77 /* bundle from their code without having to know where it was on the disk. */ 78 /* This is meant to be a replacement mechanism for +bundleForClass: users. */ 79 /* Note that this does not search for bundles on the disk; it will locate */ 80 /* only bundles already loaded or otherwise known to the current process. */ 81 82CF_EXPORT 83CFArrayRef CFBundleGetAllBundles(void); 84 /* This is potentially expensive, and not thread-safe. Use with care. */ 85 /* Best used for debuggging or other diagnostic purposes. */ 86 87/* ===================== Creating Bundles ===================== */ 88 89CF_EXPORT 90CFTypeID CFBundleGetTypeID(void); 91 92CF_EXPORT 93CFBundleRef CFBundleCreate(CFAllocatorRef allocator, CFURLRef bundleURL); 94 /* Might return an existing instance with the ref-count bumped. */ 95 96CF_EXPORT 97CFArrayRef CFBundleCreateBundlesFromDirectory(CFAllocatorRef allocator, CFURLRef directoryURL, CFStringRef bundleType); 98 /* Create instances for all bundles in the given directory matching the given type */ 99 /* (or all of them if bundleType is NULL). Instances are created using CFBundleCreate() and are not released. */ 100 101/* ==================== Basic Bundle Info ==================== */ 102 103CF_EXPORT 104CFURLRef CFBundleCopyBundleURL(CFBundleRef bundle); 105 106CF_EXPORT 107CFTypeRef CFBundleGetValueForInfoDictionaryKey(CFBundleRef bundle, CFStringRef key); 108 /* Returns a localized value if available, otherwise the global value. */ 109 /* This is the recommended function for examining the info dictionary. */ 110 111CF_EXPORT 112CFDictionaryRef CFBundleGetInfoDictionary(CFBundleRef bundle); 113 /* This is the global info dictionary. Note that CFBundle may add */ 114 /* extra keys to the dictionary for its own use. */ 115 116CF_EXPORT 117CFDictionaryRef CFBundleGetLocalInfoDictionary(CFBundleRef bundle); 118 /* This is the localized info dictionary. */ 119 120CF_EXPORT 121void CFBundleGetPackageInfo(CFBundleRef bundle, UInt32 *packageType, UInt32 *packageCreator); 122 123CF_EXPORT 124CFStringRef CFBundleGetIdentifier(CFBundleRef bundle); 125 126CF_EXPORT 127UInt32 CFBundleGetVersionNumber(CFBundleRef bundle); 128 129CF_EXPORT 130CFStringRef CFBundleGetDevelopmentRegion(CFBundleRef bundle); 131 132CF_EXPORT 133CFURLRef CFBundleCopySupportFilesDirectoryURL(CFBundleRef bundle); 134 135CF_EXPORT 136CFURLRef CFBundleCopyResourcesDirectoryURL(CFBundleRef bundle); 137 138CF_EXPORT 139CFURLRef CFBundleCopyPrivateFrameworksURL(CFBundleRef bundle); 140 141CF_EXPORT 142CFURLRef CFBundleCopySharedFrameworksURL(CFBundleRef bundle); 143 144CF_EXPORT 145CFURLRef CFBundleCopySharedSupportURL(CFBundleRef bundle); 146 147CF_EXPORT 148CFURLRef CFBundleCopyBuiltInPlugInsURL(CFBundleRef bundle); 149 150/* ------------- Basic Bundle Info without a CFBundle instance ------------- */ 151/* This API is provided to enable developers to retrieve basic information */ 152/* about a bundle without having to create an instance of CFBundle. */ 153/* Because of caching behavior when a CFBundle instance exists, it will be faster */ 154/* to actually create a CFBundle if you need to retrieve multiple pieces of info. */ 155CF_EXPORT 156CFDictionaryRef CFBundleCopyInfoDictionaryInDirectory(CFURLRef bundleURL); 157 158CF_EXPORT 159Boolean CFBundleGetPackageInfoInDirectory(CFURLRef url, UInt32 *packageType, UInt32 *packageCreator); 160 161/* ==================== Resource Handling API ==================== */ 162 163CF_EXPORT 164CFURLRef CFBundleCopyResourceURL(CFBundleRef bundle, CFStringRef resourceName, CFStringRef resourceType, CFStringRef subDirName); 165 166CF_EXPORT 167CFArrayRef CFBundleCopyResourceURLsOfType(CFBundleRef bundle, CFStringRef resourceType, CFStringRef subDirName); 168 169CF_EXPORT 170CFStringRef CFBundleCopyLocalizedString(CFBundleRef bundle, CFStringRef key, CFStringRef value, CFStringRef tableName) CF_FORMAT_ARGUMENT(2); 171 172#define CFCopyLocalizedString(key, comment) \ 173 CFBundleCopyLocalizedString(CFBundleGetMainBundle(), (key), (key), NULL) 174#define CFCopyLocalizedStringFromTable(key, tbl, comment) \ 175 CFBundleCopyLocalizedString(CFBundleGetMainBundle(), (key), (key), (tbl)) 176#define CFCopyLocalizedStringFromTableInBundle(key, tbl, bundle, comment) \ 177 CFBundleCopyLocalizedString((bundle), (key), (key), (tbl)) 178#define CFCopyLocalizedStringWithDefaultValue(key, tbl, bundle, value, comment) \ 179 CFBundleCopyLocalizedString((bundle), (key), (value), (tbl)) 180 181/* ------------- Resource Handling without a CFBundle instance ------------- */ 182/* This API is provided to enable developers to use the CFBundle resource */ 183/* searching policy without having to create an instance of CFBundle. */ 184/* Because of caching behavior when a CFBundle instance exists, it will be faster */ 185/* to actually create a CFBundle if you need to access several resources. */ 186 187CF_EXPORT 188CFURLRef CFBundleCopyResourceURLInDirectory(CFURLRef bundleURL, CFStringRef resourceName, CFStringRef resourceType, CFStringRef subDirName); 189 190CF_EXPORT 191CFArrayRef CFBundleCopyResourceURLsOfTypeInDirectory(CFURLRef bundleURL, CFStringRef resourceType, CFStringRef subDirName); 192 193/* =========== Localization-specific Resource Handling API =========== */ 194/* This API allows finer-grained control over specific localizations, */ 195/* as distinguished from the above API, which always uses the user's */ 196/* preferred localizations for the bundle in the current app context. */ 197 198CF_EXPORT 199CFArrayRef CFBundleCopyBundleLocalizations(CFBundleRef bundle); 200 /* Lists the localizations that a bundle contains. */ 201 202CF_EXPORT 203CFArrayRef CFBundleCopyPreferredLocalizationsFromArray(CFArrayRef locArray); 204 /* Given an array of possible localizations, returns the one or more */ 205 /* of them that CFBundle would use in the current application context. */ 206 /* To determine the localizations that would be used for a particular */ 207 /* bundle in the current application context, apply this function to the */ 208 /* result of CFBundleCopyBundleLocalizations(). */ 209 210CF_EXPORT 211CFArrayRef CFBundleCopyLocalizationsForPreferences(CFArrayRef locArray, CFArrayRef prefArray); 212 /* Given an array of possible localizations, returns the one or more of */ 213 /* them that CFBundle would use, without reference to the current application */ 214 /* context, if the user's preferred localizations were given by prefArray. */ 215 /* If prefArray is NULL, the current user's actual preferred localizations will */ 216 /* be used. This is not the same as CFBundleCopyPreferredLocalizationsFromArray(), */ 217 /* because that function takes the current application context into account. */ 218 /* To determine the localizations that another application would use, apply */ 219 /* this function to the result of CFBundleCopyBundleLocalizations(). */ 220 221CF_EXPORT 222CFURLRef CFBundleCopyResourceURLForLocalization(CFBundleRef bundle, CFStringRef resourceName, CFStringRef resourceType, CFStringRef subDirName, CFStringRef localizationName); 223 224CF_EXPORT 225CFArrayRef CFBundleCopyResourceURLsOfTypeForLocalization(CFBundleRef bundle, CFStringRef resourceType, CFStringRef subDirName, CFStringRef localizationName); 226 /* The localizationName argument to CFBundleCopyResourceURLForLocalization() or */ 227 /* CFBundleCopyResourceURLsOfTypeForLocalization() must be identical to one of the */ 228 /* localizations in the bundle, as returned by CFBundleCopyBundleLocalizations(). */ 229 /* It is recommended that either CFBundleCopyPreferredLocalizationsFromArray() or */ 230 /* CFBundleCopyLocalizationsForPreferences() be used to select the localization. */ 231 232/* =================== Unbundled application info ===================== */ 233/* This API is provided to enable developers to retrieve bundle-related */ 234/* information about an application that may be bundled or unbundled. */ 235CF_EXPORT 236CFDictionaryRef CFBundleCopyInfoDictionaryForURL(CFURLRef url); 237 /* For a directory URL, this is equivalent to CFBundleCopyInfoDictionaryInDirectory(). */ 238 /* For a plain file URL representing an unbundled executable, this will attempt to read */ 239 /* an info dictionary from the (__TEXT, __info_plist) section, if it is a Mach-o file, */ 240 /* or from a 'plst' resource. */ 241 242CF_EXPORT 243CFArrayRef CFBundleCopyLocalizationsForURL(CFURLRef url); 244 /* For a directory URL, this is equivalent to calling CFBundleCopyBundleLocalizations() */ 245 /* on the corresponding bundle. For a plain file URL representing an unbundled executable, */ 246 /* this will attempt to determine its localizations using the CFBundleLocalizations and */ 247 /* CFBundleDevelopmentRegion keys in the dictionary returned by CFBundleCopyInfoDictionaryForURL,*/ 248 /* or from a 'vers' resource if those are not present. */ 249 250CF_EXPORT 251CFArrayRef CFBundleCopyExecutableArchitecturesForURL(CFURLRef url) CF_AVAILABLE(10_5, 2_0); 252 /* For a directory URL, this is equivalent to calling CFBundleCopyExecutableArchitectures() */ 253 /* on the corresponding bundle. For a plain file URL representing an unbundled executable, */ 254 /* this will return the architectures it provides, if it is a Mach-o file, or NULL otherwise. */ 255 256/* ==================== Primitive Code Loading API ==================== */ 257/* This API abstracts the various different executable formats supported on */ 258/* various platforms. It can load DYLD, CFM, or DLL shared libraries (on their */ 259/* appropriate platforms) and gives a uniform API for looking up functions. */ 260 261CF_EXPORT 262CFURLRef CFBundleCopyExecutableURL(CFBundleRef bundle); 263 264enum { 265 kCFBundleExecutableArchitectureI386 = 0x00000007, 266 kCFBundleExecutableArchitecturePPC = 0x00000012, 267 kCFBundleExecutableArchitectureX86_64 = 0x01000007, 268 kCFBundleExecutableArchitecturePPC64 = 0x01000012 269} CF_ENUM_AVAILABLE(10_5, 2_0); 270 271CF_EXPORT 272CFArrayRef CFBundleCopyExecutableArchitectures(CFBundleRef bundle) CF_AVAILABLE(10_5, 2_0); 273 /* If the bundle's executable exists and is a Mach-o file, this function will return an array */ 274 /* of CFNumbers whose values are integers representing the architectures the file provides. */ 275 /* The values currently in use are those listed in the enum above, but others may be added */ 276 /* in the future. If the executable is not a Mach-o file, this function returns NULL. */ 277 278CF_EXPORT 279Boolean CFBundlePreflightExecutable(CFBundleRef bundle, CFErrorRef *error) CF_AVAILABLE(10_5, 2_0); 280 /* This function will return true if the bundle is loaded, or if the bundle appears to be */ 281 /* loadable upon inspection. This does not mean that the bundle is definitively loadable, */ 282 /* since it may fail to load due to link errors or other problems not readily detectable. */ 283 /* If this function detects problems, it will return false, and return a CFError by reference. */ 284 /* It is the responsibility of the caller to release the CFError. */ 285 286CF_EXPORT 287Boolean CFBundleLoadExecutableAndReturnError(CFBundleRef bundle, CFErrorRef *error) CF_AVAILABLE(10_5, 2_0); 288 /* If the bundle is already loaded, this function will return true. Otherwise, it will attempt */ 289 /* to load the bundle, and it will return true if that attempt succeeds. If the bundle fails */ 290 /* to load, this function will return false, and it will return a CFError by reference. */ 291 /* It is the responsibility of the caller to release the CFError. */ 292 293CF_EXPORT 294Boolean CFBundleLoadExecutable(CFBundleRef bundle); 295 296CF_EXPORT 297Boolean CFBundleIsExecutableLoaded(CFBundleRef bundle); 298 299CF_EXPORT 300void CFBundleUnloadExecutable(CFBundleRef bundle); 301 302CF_EXPORT 303void *CFBundleGetFunctionPointerForName(CFBundleRef bundle, CFStringRef functionName); 304 305CF_EXPORT 306void CFBundleGetFunctionPointersForNames(CFBundleRef bundle, CFArrayRef functionNames, void *ftbl[]); 307 308CF_EXPORT 309void *CFBundleGetDataPointerForName(CFBundleRef bundle, CFStringRef symbolName); 310 311CF_EXPORT 312void CFBundleGetDataPointersForNames(CFBundleRef bundle, CFArrayRef symbolNames, void *stbl[]); 313 314CF_EXPORT 315CFURLRef CFBundleCopyAuxiliaryExecutableURL(CFBundleRef bundle, CFStringRef executableName); 316 /* This function can be used to find executables other than your main */ 317 /* executable. This is useful, for instance, for applications that have */ 318 /* some command line tool that is packaged with and used by the application. */ 319 /* The tool can be packaged in the various platform executable directories */ 320 /* in the bundle and can be located with this function. This allows an */ 321 /* app to ship versions of the tool for each platform as it does for the */ 322 /* main app executable. */ 323 324/* ==================== Getting a bundle's plugIn ==================== */ 325 326CF_EXPORT 327CFPlugInRef CFBundleGetPlugIn(CFBundleRef bundle); 328 329/* ==================== Resource Manager-Related API ==================== */ 330 331#if __LP64__ 332typedef int CFBundleRefNum; 333#else 334typedef SInt16 CFBundleRefNum; 335#endif 336 337CF_EXPORT 338CFBundleRefNum CFBundleOpenBundleResourceMap(CFBundleRef bundle); 339 /* This function opens the non-localized and the localized resource files */ 340 /* (if any) for the bundle, creates and makes current a single read-only */ 341 /* resource map combining both, and returns a reference number for it. */ 342 /* If it is called multiple times, it opens the files multiple times, */ 343 /* and returns distinct reference numbers. */ 344 345CF_EXPORT 346SInt32 CFBundleOpenBundleResourceFiles(CFBundleRef bundle, CFBundleRefNum *refNum, CFBundleRefNum *localizedRefNum); 347 /* Similar to CFBundleOpenBundleResourceMap(), except that it creates two */ 348 /* separate resource maps and returns reference numbers for both. */ 349 350CF_EXPORT 351void CFBundleCloseBundleResourceMap(CFBundleRef bundle, CFBundleRefNum refNum); 352 353CF_EXTERN_C_END 354 355#endif /* ! __COREFOUNDATION_CFBUNDLE__ */ 356 357