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