1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #ifndef _nsXULAppAPI_h__
8 #define _nsXULAppAPI_h__
13 #include "nsISupports.h"
14 #include "mozilla/Logging.h"
15 #include "mozilla/XREAppData.h"
16 #include "js/TypeDecls.h"
18 #include "mozilla/ArrayUtils.h"
19 #include "mozilla/Assertions.h"
20 #include "mozilla/Vector.h"
21 #include "mozilla/TimeStamp.h"
22 #include "XREChildData.h"
23 #include "XREShellData.h"
25 #if defined(MOZ_WIDGET_ANDROID)
30 * A directory service key which provides the platform-correct "application
31 * data" directory as follows, where $name and $vendor are as defined above and
32 * $vendor is optional:
35 * HOME = Documents and Settings\$USER\Application Data
36 * UAppData = $HOME[\$vendor]\$name
40 * UAppData = $HOME/.[$vendor/]$name
44 * UAppData = $HOME/Library/Application Support/$name
46 * Note that the "profile" member above will change the value of UAppData as
50 * UAppData = $HOME\$profile
53 * UAppData = $HOME/.$profile
56 * UAppData = $HOME/Library/Application Support/$profile
58 #define XRE_USER_APP_DATA_DIR "UAppData"
61 * A directory service key which provides a list of all enabled extension
62 * directories and files (packed XPIs). The list includes compatible
63 * platform-specific extension subdirectories.
65 * @note The directory list will have no members when the application is
66 * launched in safe mode.
68 #define XRE_EXTENSIONS_DIR_LIST "XREExtDL"
71 * A directory service key which provides the executable file used to
72 * launch the current process. This is the same value returned by the
73 * XRE_GetBinaryPath function defined below.
75 #define XRE_EXECUTABLE_FILE "XREExeF"
78 * A directory service key which specifies the profile
79 * directory. Unlike the NS_APP_USER_PROFILE_50_DIR key, this key may
80 * be available when the profile hasn't been "started", or after is
81 * has been shut down. If the application is running without a
82 * profile, such as when showing the profile manager UI, this key will
83 * not be available. This key is provided by the XUL apprunner or by
84 * the aAppDirProvider object passed to XRE_InitEmbedding.
86 #define NS_APP_PROFILE_DIR_STARTUP "ProfDS"
89 * A directory service key which specifies the profile
90 * directory. Unlike the NS_APP_USER_PROFILE_LOCAL_50_DIR key, this key may
91 * be available when the profile hasn't been "started", or after is
92 * has been shut down. If the application is running without a
93 * profile, such as when showing the profile manager UI, this key will
94 * not be available. This key is provided by the XUL apprunner or by
95 * the aAppDirProvider object passed to XRE_InitEmbedding.
97 #define NS_APP_PROFILE_LOCAL_DIR_STARTUP "ProfLDS"
100 * A directory service key which specifies the system extension
101 * parent directory containing platform-specific extensions.
102 * This key may not be available on all platforms.
104 #define XRE_SYS_LOCAL_EXTENSION_PARENT_DIR "XRESysLExtPD"
107 * A directory service key which specifies the system extension
108 * parent directory containing platform-independent extensions.
109 * This key may not be available on all platforms.
110 * Additionally, the directory may be equal to that returned by
111 * XRE_SYS_LOCAL_EXTENSION_PARENT_DIR on some platforms.
113 #define XRE_SYS_SHARE_EXTENSION_PARENT_DIR "XRESysSExtPD"
115 #if defined(XP_UNIX) || defined(XP_MACOSX)
117 * Directory service keys for the system-wide and user-specific
118 * directories where native manifests used by the WebExtensions
119 * native messaging and managed storage features are found.
121 #define XRE_SYS_NATIVE_MANIFESTS "XRESysNativeManifests"
122 #define XRE_USER_NATIVE_MANIFESTS "XREUserNativeManifests"
126 * A directory service key which specifies the user system extension
129 #define XRE_USER_SYS_EXTENSION_DIR "XREUSysExt"
132 * A directory service key which specifies the distribution specific files for
135 #define XRE_APP_DISTRIBUTION_DIR "XREAppDist"
138 * A directory service key which specifies the location for system add-ons.
140 #define XRE_APP_FEATURES_DIR "XREAppFeat"
143 * A directory service key which specifies the location for app dir add-ons.
144 * Should be a synonym for XCurProcD everywhere except in tests.
146 #define XRE_ADDON_APP_DIR "XREAddonAppDir"
149 * A directory service key which provides the update directory. Callers should
150 * fall back to appDir.
151 * Windows: If vendor name exists:
152 * Documents and Settings\<User>\Local Settings\Application Data\
153 * <vendor name>\updates\
154 * <hash of the path to XRE_EXECUTABLE_FILE’s parent directory>
156 * If vendor name doesn't exist, but product name exists:
157 * Documents and Settings\<User>\Local Settings\Application Data\
158 * <product name>\updates\
159 * <hash of the path to XRE_EXECUTABLE_FILE’s parent directory>
161 * If neither vendor nor product name exists:
162 * If app dir is under Program Files:
163 * Documents and Settings\<User>\Local Settings\Application Data\
164 * <relative path to app dir from Program Files>
166 * If app dir isn’t under Program Files:
167 * Documents and Settings\<User>\Local Settings\Application Data\
170 * Mac: ~/Library/Caches/Mozilla/updates/<absolute path to app dir>
172 * All others: Parent directory of XRE_EXECUTABLE_FILE.
174 #define XRE_UPDATE_ROOT_DIR "UpdRootD"
177 * Begin an XUL application. Does not return until the user exits the
180 * @param argc/argv Command-line parameters to pass to the application. On
181 * Windows, these should be in UTF8. On unix-like platforms
182 * these are in the "native" character set.
184 * @param aConfig Information about the application to be run.
186 * @return A native result code suitable for returning from main().
188 * @note If the binary is linked against the standalone XPCOM glue,
189 * XPCOMGlueStartup() should be called before this method.
192 struct BootstrapConfig
;
195 XRE_main
, (int argc
, char* argv
[], const mozilla::BootstrapConfig
& aConfig
))
198 * Given a path relative to the current working directory (or an absolute
199 * path), return an appropriate nsIFile object.
201 * @note Pass UTF8 strings on Windows... native charset on other platforms.
204 XRE_GetFileFromPath
, (const char* aPath
, nsIFile
** aResult
))
207 * Get the path of the running application binary and store it in aResult.
208 * @param aArgv0 The value passed as argv[0] of main(). This value is only
209 * used on *nix, and only when other methods of determining
210 * the binary path have failed.
213 XRE_GetBinaryPath
, (const char* aArgv0
, nsIFile
** aResult
))
216 * Get the static module built in to libxul.
218 XRE_API(const mozilla::Module
*,
219 XRE_GetStaticModule
, ())
222 * Lock a profile directory using platform-specific semantics.
224 * @param aDirectory The profile directory to lock.
225 * @param aLockObject An opaque lock object. The directory will remain locked
226 * as long as the XPCOM reference is held.
229 XRE_LockProfileDirectory
, (nsIFile
* aDirectory
,
230 nsISupports
** aLockObject
))
233 * Initialize libXUL for embedding purposes.
235 * @param aLibXULDirectory The directory in which the libXUL shared library
237 * @param aAppDirectory The directory in which the application components
238 * and resources can be found. This will map to
239 * the NS_OS_CURRENT_PROCESS_DIR directory service
241 * @param aAppDirProvider A directory provider for the application. This
242 * provider will be aggregated by a libxul provider
243 * which will provide the base required GRE keys.
245 * @note This function must be called from the "main" thread.
247 * @note At the present time, this function may only be called once in
248 * a given process. Use XRE_TermEmbedding to clean up and free
249 * resources allocated by XRE_InitEmbedding.
253 XRE_InitEmbedding2
, (nsIFile
* aLibXULDirectory
,
254 nsIFile
* aAppDirectory
,
255 nsIDirectoryServiceProvider
* aAppDirProvider
))
258 * Register static XPCOM component information.
259 * This method may be called at any time before or after XRE_main or
263 XRE_AddStaticComponent
, (const mozilla::Module
* aComponent
))
266 * Register XPCOM components found in an array of files/directories.
267 * This method may be called at any time before or after XRE_main or
270 * @param aFiles An array of files or directories.
271 * @param aFileCount the number of items in the aFiles array.
272 * @note appdir/components is registered automatically.
274 * NS_APP_LOCATION specifies a location to search for binary XPCOM
275 * components as well as component/chrome manifest files.
277 * NS_EXTENSION_LOCATION excludes binary XPCOM components but allows other
278 * manifest instructions.
280 * NS_SKIN_LOCATION specifies a location to search for chrome manifest files
281 * which are only allowed to register only skin packages and style overlays.
286 NS_EXTENSION_LOCATION
,
288 NS_BOOTSTRAPPED_LOCATION
292 XRE_AddManifestLocation
, (NSLocationType aType
,
296 * Register XPCOM components found in a JAR.
297 * This is similar to XRE_AddManifestLocation except the file specified
298 * must be a zip archive with a manifest named chrome.manifest
299 * This method may be called at any time before or after XRE_main or
302 * @param aFiles An array of files or directories.
303 * @param aFileCount the number of items in the aFiles array.
304 * @note appdir/components is registered automatically.
306 * NS_COMPONENT_LOCATION specifies a location to search for binary XPCOM
307 * components as well as component/chrome manifest files.
309 * NS_SKIN_LOCATION specifies a location to search for chrome manifest files
310 * which are only allowed to register only skin packages and style overlays.
313 XRE_AddJarManifestLocation
, (NSLocationType aType
,
317 * Fire notifications to inform the toolkit about a new profile. This
318 * method should be called after XRE_InitEmbedding if the embedder
319 * wishes to run with a profile. Normally the embedder should call
320 * XRE_LockProfileDirectory to lock the directory before calling this
323 * @note There are two possibilities for selecting a profile:
325 * 1) Select the profile before calling XRE_InitEmbedding. The aAppDirProvider
326 * object passed to XRE_InitEmbedding should provide the
327 * NS_APP_USER_PROFILE_50_DIR key, and may also provide the following keys:
328 * - NS_APP_USER_PROFILE_LOCAL_50_DIR
329 * - NS_APP_PROFILE_DIR_STARTUP
330 * - NS_APP_PROFILE_LOCAL_DIR_STARTUP
331 * In this scenario XRE_NotifyProfile should be called immediately after
332 * XRE_InitEmbedding. Component registration information will be stored in
333 * the profile and JS components may be stored in the fastload cache.
335 * 2) Select a profile some time after calling XRE_InitEmbedding. In this case
336 * the embedder must install a directory service provider which provides
337 * NS_APP_USER_PROFILE_50_DIR and optionally
338 * NS_APP_USER_PROFILE_LOCAL_50_DIR. Component registration information
339 * will be stored in the application directory and JS components will not
343 XRE_NotifyProfile
, ())
346 * Terminate embedding started with XRE_InitEmbedding or XRE_InitEmbedding2
349 XRE_TermEmbedding
, ())
352 * Parse an INI file (application.ini or override.ini) into an existing
353 * nsXREAppData structure.
355 * @param aINIFile The INI file to parse
356 * @param aAppData The nsXREAppData structure to fill.
359 XRE_ParseAppData
, (nsIFile
* aINIFile
,
360 mozilla::XREAppData
& aAppData
))
362 enum GeckoProcessType
364 GeckoProcessType_Default
= 0,
366 GeckoProcessType_Plugin
,
367 GeckoProcessType_Content
,
369 GeckoProcessType_IPDLUnitTest
,
371 GeckoProcessType_GMPlugin
, // Gecko Media Plugin
373 GeckoProcessType_GPU
, // GPU and compositor process
375 GeckoProcessType_End
,
376 GeckoProcessType_Invalid
= GeckoProcessType_End
379 static const char* const kGeckoProcessTypeString
[] = {
388 static_assert(MOZ_ARRAY_LENGTH(kGeckoProcessTypeString
) ==
389 GeckoProcessType_End
,
390 "Array length mismatch");
393 XRE_ChildProcessTypeToString
, (GeckoProcessType aProcessType
))
395 #if defined(MOZ_WIDGET_ANDROID)
397 XRE_SetAndroidChildFds
, (JNIEnv
* env
, int crashFd
, int ipcFd
))
398 #endif // defined(MOZ_WIDGET_ANDROID)
401 XRE_SetProcessType
, (const char* aProcessTypeString
))
403 #if defined(MOZ_CRASHREPORTER)
404 // Used in the "master" parent process hosting the crash server
406 XRE_TakeMinidumpForChild
, (uint32_t aChildPid
, nsIFile
** aDump
,
407 uint32_t* aSequence
))
409 // Used in child processes.
411 XRE_SetRemoteExceptionHandler
, (const char* aPipe
))
418 } // namespace mozilla
421 XRE_InitChildProcess
, (int aArgc
,
423 const XREChildData
* aChildData
))
425 XRE_API(GeckoProcessType
,
426 XRE_GetProcessType
, ())
429 * Returns true when called in the e10s parent process. Does *NOT* return true
430 * when called in the main process if e10s is disabled.
433 XRE_IsE10sParentProcess
, ())
436 * Returns true when called in the e10s parent process or called in the main
437 * process when e10s is disabled.
440 XRE_IsParentProcess
, ())
443 XRE_IsContentProcess
, ())
446 XRE_IsGPUProcess
, ())
449 * Returns true if the appshell should run its own native event loop. Returns
450 * false if we should rely solely on the Gecko event loop.
453 XRE_UseNativeEventProcessing
, ())
455 typedef void (*MainFunction
)(void* aData
);
458 XRE_InitParentProcess
, (int aArgc
,
460 MainFunction aMainFunction
,
461 void* aMainFunctionExtraData
))
464 XRE_RunIPDLTest
, (int aArgc
,
471 XRE_InitCommandLine
, (int aArgc
, char* aArgv
[]))
474 XRE_DeinitCommandLine
, ())
479 XRE_ShutdownChildProcess
, ())
481 XRE_API(MessageLoop
*,
482 XRE_GetIOMessageLoop
, ())
485 XRE_SendTestShellCommand
, (JSContext
* aCx
,
489 XRE_ShutdownTestShell
, ())
492 XRE_InstallX11ErrorHandler
, ())
495 XRE_TelemetryAccumulate
, (int aID
, uint32_t aSample
))
498 XRE_StartupTimelineRecord
, (int aEvent
, mozilla::TimeStamp aWhen
))
501 XRE_InitOmnijar
, (nsIFile
* aGreOmni
,
504 XRE_StopLateWriteChecks
, (void))
507 XRE_EnableSameExecutableForContentProc
, ())
510 XRE_XPCShellMain
, (int argc
, char** argv
, char** envp
,
511 const XREShellData
* aShellData
))
513 #if MOZ_WIDGET_GTK == 2
520 #include "LibFuzzerRegistry.h"
523 XRE_LibFuzzerSetDriver
, (LibFuzzerDriver
))
527 #endif // _nsXULAppAPI_h__