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