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/. */ 6 7 #ifndef _nsXULAppAPI_h__ 8 #define _nsXULAppAPI_h__ 9 10 #include "js/TypeDecls.h" 11 #include "mozilla/ArrayUtils.h" 12 #include "mozilla/TimeStamp.h" 13 #include "nscore.h" 14 #include "xrecore.h" 15 16 #if defined(MOZ_WIDGET_ANDROID) 17 # include <jni.h> 18 #endif 19 20 class JSString; 21 class MessageLoop; 22 class nsIDirectoryServiceProvider; 23 class nsIFile; 24 class nsISupports; 25 struct JSContext; 26 struct XREChildData; 27 struct XREShellData; 28 29 namespace mozilla { 30 class XREAppData; 31 struct BootstrapConfig; 32 struct Module; 33 } // namespace mozilla 34 35 /** 36 * A directory service key which provides the platform-correct "application 37 * data" directory as follows, where $name and $vendor are as defined above and 38 * $vendor is optional: 39 * 40 * Windows: 41 * HOME = Documents and Settings\$USER\Application Data 42 * UAppData = $HOME[\$vendor]\$name 43 * 44 * Unix: 45 * HOME = ~ 46 * UAppData = $HOME/.[$vendor/]$name 47 * 48 * Mac: 49 * HOME = ~ 50 * UAppData = $HOME/Library/Application Support/$name 51 * 52 * Note that the "profile" member above will change the value of UAppData as 53 * follows: 54 * 55 * Windows: 56 * UAppData = $HOME\$profile 57 * 58 * Unix: 59 * UAppData = $HOME/.$profile 60 * 61 * Mac: 62 * UAppData = $HOME/Library/Application Support/$profile 63 */ 64 #define XRE_USER_APP_DATA_DIR "UAppData" 65 66 /** 67 * A directory service key which provides the executable file used to 68 * launch the current process. This is the same value returned by the 69 * XRE_GetBinaryPath function defined below. 70 */ 71 #define XRE_EXECUTABLE_FILE "XREExeF" 72 73 /** 74 * A directory service key which specifies the profile 75 * directory. Unlike the NS_APP_USER_PROFILE_50_DIR key, this key may 76 * be available when the profile hasn't been "started", or after is 77 * has been shut down. If the application is running without a 78 * profile, such as when showing the profile manager UI, this key will 79 * not be available. This key is provided by the XUL apprunner or by 80 * the aAppDirProvider object passed to XRE_InitEmbedding. 81 */ 82 #define NS_APP_PROFILE_DIR_STARTUP "ProfDS" 83 84 /** 85 * A directory service key which specifies the profile 86 * directory. Unlike the NS_APP_USER_PROFILE_LOCAL_50_DIR key, this key may 87 * be available when the profile hasn't been "started", or after is 88 * has been shut down. If the application is running without a 89 * profile, such as when showing the profile manager UI, this key will 90 * not be available. This key is provided by the XUL apprunner or by 91 * the aAppDirProvider object passed to XRE_InitEmbedding. 92 */ 93 #define NS_APP_PROFILE_LOCAL_DIR_STARTUP "ProfLDS" 94 95 /** 96 * A directory service key which specifies the system extension 97 * parent directory containing platform-specific extensions. 98 * This key may not be available on all platforms. 99 */ 100 #define XRE_SYS_LOCAL_EXTENSION_PARENT_DIR "XRESysLExtPD" 101 102 /** 103 * A directory service key which specifies the system extension 104 * parent directory containing platform-independent extensions. 105 * This key may not be available on all platforms. 106 * Additionally, the directory may be equal to that returned by 107 * XRE_SYS_LOCAL_EXTENSION_PARENT_DIR on some platforms. 108 */ 109 #define XRE_SYS_SHARE_EXTENSION_PARENT_DIR "XRESysSExtPD" 110 111 #if defined(XP_UNIX) || defined(XP_MACOSX) 112 /** 113 * Directory service keys for the system-wide and user-specific 114 * directories where native manifests used by the WebExtensions 115 * native messaging and managed storage features are found. 116 */ 117 # define XRE_SYS_NATIVE_MANIFESTS "XRESysNativeManifests" 118 # define XRE_USER_NATIVE_MANIFESTS "XREUserNativeManifests" 119 #endif 120 121 /** 122 * A directory service key which specifies the user system extension 123 * parent directory. 124 */ 125 #define XRE_USER_SYS_EXTENSION_DIR "XREUSysExt" 126 127 /** 128 * A directory service key which specifies a directory where temporary 129 * system extensions can be loaded from during development. 130 */ 131 #define XRE_USER_SYS_EXTENSION_DEV_DIR "XRESysExtDev" 132 133 /** 134 * A directory service key which specifies the distribution specific files for 135 * the application. 136 */ 137 #define XRE_APP_DISTRIBUTION_DIR "XREAppDist" 138 139 /** 140 * A directory service key which specifies the location for system add-ons. 141 */ 142 #define XRE_APP_FEATURES_DIR "XREAppFeat" 143 144 /** 145 * A directory service key which specifies the location for app dir add-ons. 146 * Should be a synonym for XCurProcD everywhere except in tests. 147 */ 148 #define XRE_ADDON_APP_DIR "XREAddonAppDir" 149 150 /** 151 * A directory service key which specifies the distribution specific files for 152 * the application unique for each user. 153 * It's located at /run/user/$UID/<product name>/ 154 */ 155 #define XRE_USER_RUNTIME_DIR "XREUserRunTimeDir" 156 157 /** 158 * A directory service key which provides the update directory. Callers should 159 * fall back to appDir. 160 * Windows: If vendor name exists: 161 * ProgramData\<vendor name>\updates\ 162 * <hash of the path to XRE_EXECUTABLE_FILE's parent directory> 163 * 164 * If vendor name doesn't exist, but product name exists: 165 * ProgramData\<product name>\updates\ 166 * <hash of the path to XRE_EXECUTABLE_FILE's parent directory> 167 * 168 * If neither vendor nor product name exists: 169 * ProgramData\Mozilla\updates 170 * 171 * Mac: ~/Library/Caches/Mozilla/updates/<absolute path to app dir> 172 * 173 * All others: Parent directory of XRE_EXECUTABLE_FILE. 174 */ 175 #define XRE_UPDATE_ROOT_DIR "UpdRootD" 176 177 /** 178 * A directory service key which provides the *old* update directory. This 179 * path should only be used when data needs to be migrated from the old update 180 * directory. 181 * Windows: If vendor name exists: 182 * Documents and Settings\<User>\Local Settings\Application Data\ 183 * <vendor name>\updates\ 184 * <hash of the path to XRE_EXECUTABLE_FILE's parent directory> 185 * 186 * If vendor name doesn't exist, but product name exists: 187 * Documents and Settings\<User>\Local Settings\Application Data\ 188 * <product name>\updates\ 189 * <hash of the path to XRE_EXECUTABLE_FILE's parent directory> 190 * 191 * If neither vendor nor product name exists: 192 * Documents and Settings\<User>\Local Settings\Application Data\ 193 * Mozilla\updates 194 * 195 * This path does not exist on other operating systems 196 */ 197 #define XRE_OLD_UPDATE_ROOT_DIR "OldUpdRootD" 198 199 /** 200 * Begin an XUL application. Does not return until the user exits the 201 * application. 202 * 203 * @param argc/argv Command-line parameters to pass to the application. On 204 * Windows, these should be in UTF8. On unix-like platforms 205 * these are in the "native" character set. 206 * 207 * @param aConfig Information about the application to be run. 208 * 209 * @return A native result code suitable for returning from main(). 210 * 211 * @note If the binary is linked against the standalone XPCOM glue, 212 * XPCOMGlueStartup() should be called before this method. 213 */ 214 XRE_API(int, XRE_main, 215 (int argc, char* argv[], const mozilla::BootstrapConfig& aConfig)) 216 217 /** 218 * Given a path relative to the current working directory (or an absolute 219 * path), return an appropriate nsIFile object. 220 * 221 * @note Pass UTF8 strings on Windows... native charset on other platforms. 222 */ 223 XRE_API(nsresult, XRE_GetFileFromPath, (const char* aPath, nsIFile** aResult)) 224 225 /** 226 * Get the path of the running application binary and store it in aResult. 227 */ 228 XRE_API(nsresult, XRE_GetBinaryPath, (nsIFile * *aResult)) 229 230 /** 231 * Get the static module built in to libxul. 232 */ 233 XRE_API(const mozilla::Module*, XRE_GetStaticModule, ()) 234 235 /** 236 * Lock a profile directory using platform-specific semantics. 237 * 238 * @param aDirectory The profile directory to lock. 239 * @param aLockObject An opaque lock object. The directory will remain locked 240 * as long as the XPCOM reference is held. 241 */ 242 XRE_API(nsresult, XRE_LockProfileDirectory, 243 (nsIFile * aDirectory, nsISupports** aLockObject)) 244 245 /** 246 * Initialize libXUL for embedding purposes. 247 * 248 * @param aLibXULDirectory The directory in which the libXUL shared library 249 * was found. 250 * @param aAppDirectory The directory in which the application components 251 * and resources can be found. This will map to 252 * the NS_OS_CURRENT_PROCESS_DIR directory service 253 * key. 254 * @param aAppDirProvider A directory provider for the application. This 255 * provider will be aggregated by a libxul provider 256 * which will provide the base required GRE keys. 257 * 258 * @note This function must be called from the "main" thread. 259 * 260 * @note At the present time, this function may only be called once in 261 * a given process. Use XRE_TermEmbedding to clean up and free 262 * resources allocated by XRE_InitEmbedding. 263 */ 264 265 XRE_API(nsresult, XRE_InitEmbedding2, 266 (nsIFile * aLibXULDirectory, nsIFile* aAppDirectory, 267 nsIDirectoryServiceProvider* aAppDirProvider)) 268 269 /** 270 * Register static XPCOM component information. 271 * This method may be called at any time before or after XRE_main or 272 * XRE_InitEmbedding. 273 */ 274 XRE_API(nsresult, XRE_AddStaticComponent, (const mozilla::Module* aComponent)) 275 276 /** 277 * Register XPCOM components found in an array of files/directories. 278 * This method may be called at any time before or after XRE_main or 279 * XRE_InitEmbedding. 280 * 281 * @param aFiles An array of files or directories. 282 * @param aFileCount the number of items in the aFiles array. 283 * @note appdir/components is registered automatically. 284 * 285 * NS_APP_LOCATION specifies a location to search for binary XPCOM 286 * components as well as component/chrome manifest files. 287 * 288 * NS_EXTENSION_LOCATION excludes binary XPCOM components but allows other 289 * manifest instructions. 290 * 291 * NS_SKIN_LOCATION specifies a location to search for chrome manifest files 292 * which are only allowed to register skin packages. 293 */ 294 enum NSLocationType { 295 NS_APP_LOCATION, 296 NS_EXTENSION_LOCATION, 297 NS_SKIN_LOCATION, 298 NS_BOOTSTRAPPED_LOCATION 299 }; 300 301 XRE_API(nsresult, XRE_AddManifestLocation, 302 (NSLocationType aType, nsIFile* aLocation)) 303 304 /** 305 * Register XPCOM components found in a JAR. 306 * This is similar to XRE_AddManifestLocation except the file specified 307 * must be a zip archive with a manifest named chrome.manifest 308 * This method may be called at any time before or after XRE_main or 309 * XRE_InitEmbedding. 310 * 311 * @param aFiles An array of files or directories. 312 * @param aFileCount the number of items in the aFiles array. 313 * @note appdir/components is registered automatically. 314 * 315 * NS_COMPONENT_LOCATION specifies a location to search for binary XPCOM 316 * components as well as component/chrome manifest files. 317 * 318 * NS_SKIN_LOCATION specifies a location to search for chrome manifest files 319 * which are only allowed to register skin packages. 320 */ 321 XRE_API(nsresult, XRE_AddJarManifestLocation, 322 (NSLocationType aType, nsIFile* aLocation)) 323 324 /** 325 * Fire notifications to inform the toolkit about a new profile. This 326 * method should be called after XRE_InitEmbedding if the embedder 327 * wishes to run with a profile. Normally the embedder should call 328 * XRE_LockProfileDirectory to lock the directory before calling this 329 * method. 330 * 331 * @note There are two possibilities for selecting a profile: 332 * 333 * 1) Select the profile before calling XRE_InitEmbedding. The aAppDirProvider 334 * object passed to XRE_InitEmbedding should provide the 335 * NS_APP_USER_PROFILE_50_DIR key, and may also provide the following keys: 336 * - NS_APP_USER_PROFILE_LOCAL_50_DIR 337 * - NS_APP_PROFILE_DIR_STARTUP 338 * - NS_APP_PROFILE_LOCAL_DIR_STARTUP 339 * In this scenario XRE_NotifyProfile should be called immediately after 340 * XRE_InitEmbedding. Component registration information will be stored in 341 * the profile and JS components may be stored in the fastload cache. 342 * 343 * 2) Select a profile some time after calling XRE_InitEmbedding. In this case 344 * the embedder must install a directory service provider which provides 345 * NS_APP_USER_PROFILE_50_DIR and optionally 346 * NS_APP_USER_PROFILE_LOCAL_50_DIR. Component registration information 347 * will be stored in the application directory and JS components will not 348 * fastload. 349 */ 350 XRE_API(void, XRE_NotifyProfile, ()) 351 352 /** 353 * Terminate embedding started with XRE_InitEmbedding or XRE_InitEmbedding2 354 */ 355 XRE_API(void, XRE_TermEmbedding, ()) 356 357 /** 358 * Parse an INI file (application.ini or override.ini) into an existing 359 * nsXREAppData structure. 360 * 361 * @param aINIFile The INI file to parse 362 * @param aAppData The nsXREAppData structure to fill. 363 */ 364 XRE_API(nsresult, XRE_ParseAppData, 365 (nsIFile * aINIFile, mozilla::XREAppData& aAppData)) 366 367 // This enum is not dense. See GeckoProcessTypes.h for details. 368 enum GeckoProcessType { 369 #define GECKO_PROCESS_TYPE(enum_value, enum_name, string_name, xre_name, \ 370 bin_type) \ 371 GeckoProcessType_##enum_name = enum_value, 372 #include "mozilla/GeckoProcessTypes.h" 373 #undef GECKO_PROCESS_TYPE 374 GeckoProcessType_End, 375 GeckoProcessType_Invalid = GeckoProcessType_End 376 }; 377 378 XRE_API(const char*, XRE_GeckoProcessTypeToString, 379 (GeckoProcessType aProcessType)) 380 XRE_API(const char*, XRE_ChildProcessTypeToAnnotation, 381 (GeckoProcessType aProcessType)) 382 383 #if defined(MOZ_WIDGET_ANDROID) 384 struct XRE_AndroidChildFds { 385 int mPrefsFd; 386 int mPrefMapFd; 387 int mIpcFd; 388 int mCrashFd; 389 int mCrashAnnotationFd; 390 }; 391 392 XRE_API(void, XRE_SetAndroidChildFds, 393 (JNIEnv * env, const XRE_AndroidChildFds& fds)) 394 #endif // defined(MOZ_WIDGET_ANDROID) 395 396 XRE_API(void, XRE_SetProcessType, (const char* aProcessTypeString)) 397 398 XRE_API(nsresult, XRE_InitChildProcess, 399 (int aArgc, char* aArgv[], const XREChildData* aChildData)) 400 401 /** 402 * Return the GeckoProcessType of the current process. 403 */ 404 XRE_API(GeckoProcessType, XRE_GetProcessType, ()) 405 406 /** 407 * Return the string representation of the GeckoProcessType of the current 408 * process. 409 */ 410 XRE_API(const char*, XRE_GetProcessTypeString, ()) 411 412 /** 413 * Returns true when called in the e10s parent process. Does *NOT* return true 414 * when called in the main process if e10s is disabled. 415 */ 416 XRE_API(bool, XRE_IsE10sParentProcess, ()) 417 418 /** 419 * Defines XRE_IsParentProcess, XRE_IsContentProcess, etc. 420 * 421 * XRE_IsParentProcess is unique in that it returns true when called in 422 * the e10s parent process or called in the main process when e10s is 423 * disabled. 424 */ 425 #define GECKO_PROCESS_TYPE(enum_value, enum_name, string_name, xre_name, \ 426 bin_type) \ 427 XRE_API(bool, XRE_Is##xre_name##Process, ()) 428 #include "mozilla/GeckoProcessTypes.h" 429 #undef GECKO_PROCESS_TYPE 430 431 XRE_API(bool, XRE_IsSocketProcess, ()) 432 433 /** 434 * Returns true if the appshell should run its own native event loop. Returns 435 * false if we should rely solely on the Gecko event loop. 436 */ 437 XRE_API(bool, XRE_UseNativeEventProcessing, ()) 438 439 typedef void (*MainFunction)(void* aData); 440 441 XRE_API(nsresult, XRE_InitParentProcess, 442 (int aArgc, char* aArgv[], MainFunction aMainFunction, 443 void* aMainFunctionExtraData)) 444 445 XRE_API(int, XRE_RunIPDLTest, (int aArgc, char* aArgv[])) 446 447 XRE_API(nsresult, XRE_RunAppShell, ()) 448 449 XRE_API(nsresult, XRE_InitCommandLine, (int aArgc, char* aArgv[])) 450 451 XRE_API(nsresult, XRE_DeinitCommandLine, ()) 452 453 XRE_API(void, XRE_ShutdownChildProcess, ()) 454 455 XRE_API(MessageLoop*, XRE_GetIOMessageLoop, ()) 456 457 XRE_API(bool, XRE_SendTestShellCommand, 458 (JSContext * aCx, JSString* aCommand, JS::Value* aCallback)) 459 XRE_API(bool, XRE_ShutdownTestShell, ()) 460 461 XRE_API(void, XRE_InstallX11ErrorHandler, ()) 462 463 XRE_API(void, XRE_TelemetryAccumulate, (int aID, uint32_t aSample)) 464 465 XRE_API(void, XRE_StartupTimelineRecord, (int aEvent, mozilla::TimeStamp aWhen)) 466 467 XRE_API(void, XRE_InitOmnijar, (nsIFile * aGreOmni, nsIFile* aAppOmni)) 468 XRE_API(void, XRE_StopLateWriteChecks, (void)) 469 470 XRE_API(void, XRE_EnableSameExecutableForContentProc, ()) 471 472 namespace mozilla { 473 enum class BinPathType { Self, PluginContainer }; 474 } 475 XRE_API(mozilla::BinPathType, XRE_GetChildProcBinPathType, 476 (GeckoProcessType aProcessType)); 477 478 XRE_API(int, XRE_XPCShellMain, 479 (int argc, char** argv, char** envp, const XREShellData* aShellData)) 480 481 #ifdef LIBFUZZER 482 # include "FuzzerRegistry.h" 483 484 XRE_API(void, XRE_LibFuzzerSetDriver, (LibFuzzerDriver)) 485 486 #endif // LIBFUZZER 487 488 #ifdef MOZ_ENABLE_FORKSERVER 489 490 XRE_API(int, XRE_ForkServer, (int* aArgc, char*** aArgv)) 491 492 #endif // MOZ_ENABLE_FORKSERVER 493 494 #endif // _nsXULAppAPI_h__ 495