xpcom/build/nsXULAppAPI.h

   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/ProcessType.h"
  13 #include "mozilla/TimeStamp.h"
  14 #include "nscore.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 }  // namespace mozilla
  33
  34 /**
  35  * A directory service key which provides the platform-correct "application
  36  * data" directory as follows, where $name and $vendor are as defined above and
  37  * $vendor is optional:
  38  *
  39  * Windows:
  40  *   HOME = Documents and Settings\$USER\Application Data
  41  *   UAppData = $HOME[\$vendor]\$name
  42  *
  43  * Unix:
  44  *   HOME = ~
  45  *   UAppData = $HOME/.[$vendor/]$name
  46  *
  47  * Mac:
  48  *   HOME = ~
  49  *   UAppData = $HOME/Library/Application Support/$name
  50  *
  51  * Note that the "profile" member above will change the value of UAppData as
  52  * follows:
  53  *
  54  * Windows:
  55  *   UAppData = $HOME\$profile
  56  *
  57  * Unix:
  58  *   UAppData = $HOME/.$profile
  59  *
  60  * Mac:
  61  *   UAppData = $HOME/Library/Application Support/$profile
  62  */
  63 #define XRE_USER_APP_DATA_DIR "UAppData"
  64
  65 /**
  66  * A directory service key which provides the executable file used to
  67  * launch the current process.  This is the same value returned by the
  68  * XRE_GetBinaryPath function defined below.
  69  */
  70 #define XRE_EXECUTABLE_FILE "XREExeF"
  71
  72 /**
  73  * A directory service key which specifies the profile
  74  * directory. Unlike the NS_APP_USER_PROFILE_50_DIR key, this key may
  75  * be available when the profile hasn't been "started", or after is
  76  * has been shut down. If the application is running without a
  77  * profile, such as when showing the profile manager UI, this key will
  78  * not be available. This key is provided by the XUL apprunner or by
  79  * the aAppDirProvider object passed to XRE_InitEmbedding.
  80  */
  81 #define NS_APP_PROFILE_DIR_STARTUP "ProfDS"
  82
  83 /**
  84  * A directory service key which specifies the profile
  85  * directory. Unlike the NS_APP_USER_PROFILE_LOCAL_50_DIR key, this key may
  86  * be available when the profile hasn't been "started", or after is
  87  * has been shut down. If the application is running without a
  88  * profile, such as when showing the profile manager UI, this key will
  89  * not be available. This key is provided by the XUL apprunner or by
  90  * the aAppDirProvider object passed to XRE_InitEmbedding.
  91  */
  92 #define NS_APP_PROFILE_LOCAL_DIR_STARTUP "ProfLDS"
  93
  94 /**
  95  * A directory service key which specifies the system extension
  96  * parent directory containing platform-specific extensions.
  97  * This key may not be available on all platforms.
  98  */
  99 #define XRE_SYS_LOCAL_EXTENSION_PARENT_DIR "XRESysLExtPD"
 100
 101 /**
 102  * A directory service key which specifies the system extension
 103  * parent directory containing platform-independent extensions.
 104  * This key may not be available on all platforms.
 105  * Additionally, the directory may be equal to that returned by
 106  * XRE_SYS_LOCAL_EXTENSION_PARENT_DIR on some platforms.
 107  */
 108 #define XRE_SYS_SHARE_EXTENSION_PARENT_DIR "XRESysSExtPD"
 109
 110 #if defined(XP_UNIX) || defined(XP_MACOSX)
 111 /**
 112  * Directory service keys for the system-wide and user-specific
 113  * directories where native manifests used by the WebExtensions
 114  * native messaging and managed storage features are found.
 115  */
 116 #  define XRE_SYS_NATIVE_MANIFESTS "XRESysNativeManifests"
 117 #  define XRE_USER_NATIVE_MANIFESTS "XREUserNativeManifests"
 118 #endif
 119
 120 /**
 121  * A directory service key which specifies the user system extension
 122  * parent directory.
 123  */
 124 #define XRE_USER_SYS_EXTENSION_DIR "XREUSysExt"
 125
 126 /**
 127  * A directory service key which specifies the distribution specific files for
 128  * the application.
 129  */
 130 #define XRE_APP_DISTRIBUTION_DIR "XREAppDist"
 131
 132 /**
 133  * A directory service key which specifies the location for system add-ons.
 134  */
 135 #define XRE_APP_FEATURES_DIR "XREAppFeat"
 136
 137 /**
 138  * A directory service key which specifies the location for app dir add-ons.
 139  * Should be a synonym for XCurProcD everywhere except in tests.
 140  */
 141 #define XRE_ADDON_APP_DIR "XREAddonAppDir"
 142
 143 /**
 144  * A directory service key which specifies the distribution specific files for
 145  * the application unique for each user.
 146  * It's located at /run/user/$UID/<product name>/
 147  */
 148 #define XRE_USER_RUNTIME_DIR "XREUserRunTimeDir"
 149
 150 /**
 151  * A directory service key which provides the update directory. Callers should
 152  * fall back to appDir.
 153  * Windows:    If vendor name exists:
 154  *             ProgramData\<vendor name>\updates\
 155  *             <hash of the path to XRE_EXECUTABLE_FILE's parent directory>
 156  *
 157  *             If vendor name doesn't exist, but product name exists:
 158  *             ProgramData\<product name>\updates\
 159  *             <hash of the path to XRE_EXECUTABLE_FILE's parent directory>
 160  *
 161  *             If neither vendor nor product name exists:
 162  *             ProgramData\Mozilla\updates
 163  *
 164  * Mac:        ~/Library/Caches/Mozilla/updates/<absolute path to app dir>
 165  *
 166  * All others: Parent directory of XRE_EXECUTABLE_FILE.
 167  */
 168 #define XRE_UPDATE_ROOT_DIR "UpdRootD"
 169
 170 /**
 171  * A directory service key which provides the *old* update directory. This
 172  * path should only be used when data needs to be migrated from the old update
 173  * directory.
 174  * Windows:    If vendor name exists:
 175  *             Documents and Settings\<User>\Local Settings\Application Data\
 176  *             <vendor name>\updates\
 177  *             <hash of the path to XRE_EXECUTABLE_FILE's parent directory>
 178  *
 179  *             If vendor name doesn't exist, but product name exists:
 180  *             Documents and Settings\<User>\Local Settings\Application Data\
 181  *             <product name>\updates\
 182  *             <hash of the path to XRE_EXECUTABLE_FILE's parent directory>
 183  *
 184  *             If neither vendor nor product name exists:
 185  *             Documents and Settings\<User>\Local Settings\Application Data\
 186  *             Mozilla\updates
 187  *
 188  * This path does not exist on other operating systems
 189  */
 190 #define XRE_OLD_UPDATE_ROOT_DIR "OldUpdRootD"
 191
 192 /**
 193  * Begin an XUL application. Does not return until the user exits the
 194  * application.
 195  *
 196  * @param argc/argv Command-line parameters to pass to the application. On
 197  *                  Windows, these should be in UTF8. On unix-like platforms
 198  *                  these are in the "native" character set.
 199  *
 200  * @param aConfig  Information about the application to be run.
 201  *
 202  * @return         A native result code suitable for returning from main().
 203  *
 204  * @note           If the binary is linked against the standalone XPCOM glue,
 205  *                 XPCOMGlueStartup() should be called before this method.
 206  */
 207 int XRE_main(int argc, char* argv[], const mozilla::BootstrapConfig& aConfig);
 208
 209 /**
 210  * Given a path relative to the current working directory (or an absolute
 211  * path), return an appropriate nsIFile object.
 212  *
 213  * @note Pass UTF8 strings on Windows... native charset on other platforms.
 214  */
 215 nsresult XRE_GetFileFromPath(const char* aPath, nsIFile** aResult);
 216
 217 /**
 218  * Get the path of the running application binary and store it in aResult.
 219  */
 220 nsresult XRE_GetBinaryPath(nsIFile** aResult);
 221
 222 /**
 223  * Register XPCOM components found in an array of files/directories.
 224  * This method may be called at any time before or after XRE_main or
 225  * XRE_InitEmbedding.
 226  *
 227  * @param aFiles An array of files or directories.
 228  * @param aFileCount the number of items in the aFiles array.
 229  * @note appdir/components is registered automatically.
 230  *
 231  * NS_APP_LOCATION specifies a location to search for binary XPCOM
 232  * components as well as component/chrome manifest files.
 233  *
 234  * NS_EXTENSION_LOCATION excludes binary XPCOM components but allows other
 235  * manifest instructions.
 236  *
 237  * NS_SKIN_LOCATION specifies a location to search for chrome manifest files
 238  * which are only allowed to register skin packages.
 239  */
 240 enum NSLocationType {
 241   NS_APP_LOCATION,
 242   NS_EXTENSION_LOCATION,
 243   NS_SKIN_LOCATION,
 244   NS_BOOTSTRAPPED_LOCATION
 245 };
 246
 247 nsresult XRE_AddManifestLocation(NSLocationType aType, nsIFile* aLocation);
 248
 249 /**
 250  * Register XPCOM components found in a JAR.
 251  * This is similar to XRE_AddManifestLocation except the file specified
 252  * must be a zip archive with a manifest named chrome.manifest
 253  * This method may be called at any time before or after XRE_main or
 254  * XRE_InitEmbedding.
 255  *
 256  * @param aFiles An array of files or directories.
 257  * @param aFileCount the number of items in the aFiles array.
 258  * @note appdir/components is registered automatically.
 259  *
 260  * NS_COMPONENT_LOCATION specifies a location to search for binary XPCOM
 261  * components as well as component/chrome manifest files.
 262  *
 263  * NS_SKIN_LOCATION specifies a location to search for chrome manifest files
 264  * which are only allowed to register skin packages.
 265  */
 266 nsresult XRE_AddJarManifestLocation(NSLocationType aType, nsIFile* aLocation);
 267
 268 /**
 269  * Parse an INI file (application.ini or override.ini) into an existing
 270  * nsXREAppData structure.
 271  *
 272  * @param aINIFile The INI file to parse
 273  * @param aAppData The nsXREAppData structure to fill.
 274  */
 275 nsresult XRE_ParseAppData(nsIFile* aINIFile, mozilla::XREAppData& aAppData);
 276
 277 const char* XRE_GeckoProcessTypeToString(GeckoProcessType aProcessType);
 278 const char* XRE_ChildProcessTypeToAnnotation(GeckoProcessType aProcessType);
 279
 280 #if defined(MOZ_WIDGET_ANDROID)
 281 struct XRE_AndroidChildFds {
 282   int mPrefsFd;
 283   int mPrefMapFd;
 284   int mIpcFd;
 285   int mCrashFd;
 286 };
 287
 288 void XRE_SetAndroidChildFds(JNIEnv* env, const XRE_AndroidChildFds& fds);
 289 #endif  // defined(MOZ_WIDGET_ANDROID)
 290
 291 void XRE_SetProcessType(const char* aProcessTypeString);
 292
 293 nsresult XRE_InitChildProcess(int aArgc, char* aArgv[],
 294                               const XREChildData* aChildData);
 295
 296 /**
 297  * Return the GeckoProcessType of the current process.
 298  */
 299 GeckoProcessType XRE_GetProcessType();
 300
 301 /**
 302  * Return the string representation of the GeckoProcessType of the current
 303  * process.
 304  */
 305 const char* XRE_GetProcessTypeString();
 306
 307 /**
 308  * Returns true when called in the e10s parent process.  Does *NOT* return true
 309  * when called in the main process if e10s is disabled.
 310  */
 311 bool XRE_IsE10sParentProcess();
 312
 313 /**
 314  * Defines XRE_IsParentProcess, XRE_IsContentProcess, etc.
 315  *
 316  * XRE_IsParentProcess is unique in that it returns true when called in
 317  * the e10s parent process or called in the main process when e10s is
 318  * disabled.
 319  */
 320 #define GECKO_PROCESS_TYPE(enum_value, enum_name, string_name, proc_typename, \
 321                            process_bin_type, procinfo_typename,               \
 322                            webidl_typename, allcaps_name)                     \
 323   bool XRE_Is##proc_typename##Process();
 324 #include "mozilla/GeckoProcessTypes.h"
 325 #undef GECKO_PROCESS_TYPE
 326
 327 bool XRE_IsSocketProcess();
 328
 329 /**
 330  * Returns true if the appshell should run its own native event loop. Returns
 331  * false if we should rely solely on the Gecko event loop.
 332  */
 333 bool XRE_UseNativeEventProcessing();
 334
 335 typedef void (*MainFunction)(void* aData);
 336
 337 int XRE_RunIPDLTest(int aArgc, char* aArgv[]);
 338
 339 nsresult XRE_RunAppShell();
 340
 341 nsresult XRE_InitCommandLine(int aArgc, char* aArgv[]);
 342
 343 nsresult XRE_DeinitCommandLine();
 344
 345 void XRE_ShutdownChildProcess();
 346
 347 MessageLoop* XRE_GetIOMessageLoop();
 348
 349 bool XRE_SendTestShellCommand(JSContext* aCx, JSString* aCommand,
 350                               JS::Value* aCallback);
 351 bool XRE_ShutdownTestShell();
 352
 353 void XRE_InstallX11ErrorHandler();
 354 void XRE_CleanupX11ErrorHandler();
 355
 356 void XRE_TelemetryAccumulate(int aID, uint32_t aSample);
 357
 358 void XRE_StartupTimelineRecord(int aEvent, mozilla::TimeStamp aWhen);
 359
 360 void XRE_InitOmnijar(nsIFile* aGreOmni, nsIFile* aAppOmni);
 361 void XRE_StopLateWriteChecks(void);
 362
 363 void XRE_EnableSameExecutableForContentProc();
 364
 365 namespace mozilla {
 366 enum class BinPathType { Self, PluginContainer };
 367 }
 368 mozilla::BinPathType XRE_GetChildProcBinPathType(GeckoProcessType aProcessType);
 369
 370 int XRE_XPCShellMain(int argc, char** argv, char** envp,
 371                      const XREShellData* aShellData);
 372
 373 #ifdef LIBFUZZER
 374 #  include "FuzzerRegistry.h"
 375
 376 void XRE_LibFuzzerSetDriver(LibFuzzerDriver);
 377
 378 #endif  // LIBFUZZER
 379
 380 #ifdef MOZ_ENABLE_FORKSERVER
 381
 382 int XRE_ForkServer(int* aArgc, char*** aArgv);
 383
 384 #endif  // MOZ_ENABLE_FORKSERVER
 385
 386 #endif  // _nsXULAppAPI_h__