The Tor Browser / file comparison

comparison: xpcom/build/nsXULAppAPI.h

xpcom/build/nsXULAppAPI.h

branch
TOR_BUG_3246
changeset 7
129ffea94266
equal deleted inserted replaced
-1:000000000000 0:5d011c8f0276
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6 #ifndef _nsXULAppAPI_h__
7 #define _nsXULAppAPI_h__
8
9 #include "nsID.h"
10 #include "xrecore.h"
11 #include "nsXPCOM.h"
12 #include "nsISupports.h"
13 #include "prlog.h"
14 #include "nsXREAppData.h"
15 #include "js/TypeDecls.h"
16
17 #include "mozilla/ArrayUtils.h"
18 #include "mozilla/Assertions.h"
19
20 /**
21 * A directory service key which provides the platform-correct "application
22 * data" directory as follows, where $name and $vendor are as defined above and
23 * $vendor is optional:
24 *
25 * Windows:
26 * HOME = Documents and Settings\$USER\Application Data
27 * UAppData = $HOME[\$vendor]\$name
28 *
29 * Unix:
30 * HOME = ~
31 * UAppData = $HOME/.[$vendor/]$name
32 *
33 * Mac:
34 * HOME = ~
35 * UAppData = $HOME/Library/Application Support/$name
36 *
37 * Note that the "profile" member above will change the value of UAppData as
38 * follows:
39 *
40 * Windows:
41 * UAppData = $HOME\$profile
42 *
43 * Unix:
44 * UAppData = $HOME/.$profile
45 *
46 * Mac:
47 * UAppData = $HOME/Library/Application Support/$profile
48 */
49 #define XRE_USER_APP_DATA_DIR "UAppData"
50
51 /**
52 * A directory service key which provides a list of all enabled extension
53 * directories and files (packed XPIs). The list includes compatible
54 * platform-specific extension subdirectories.
55 *
56 * @note The directory list will have no members when the application is
57 * launched in safe mode.
58 */
59 #define XRE_EXTENSIONS_DIR_LIST "XREExtDL"
60
61 /**
62 * A directory service key which provides the executable file used to
63 * launch the current process. This is the same value returned by the
64 * XRE_GetBinaryPath function defined below.
65 */
66 #define XRE_EXECUTABLE_FILE "XREExeF"
67
68 /**
69 * A directory service key which specifies the profile
70 * directory. Unlike the NS_APP_USER_PROFILE_50_DIR key, this key may
71 * be available when the profile hasn't been "started", or after is
72 * has been shut down. If the application is running without a
73 * profile, such as when showing the profile manager UI, this key will
74 * not be available. This key is provided by the XUL apprunner or by
75 * the aAppDirProvider object passed to XRE_InitEmbedding.
76 */
77 #define NS_APP_PROFILE_DIR_STARTUP "ProfDS"
78
79 /**
80 * A directory service key which specifies the profile
81 * directory. Unlike the NS_APP_USER_PROFILE_LOCAL_50_DIR key, this key may
82 * be available when the profile hasn't been "started", or after is
83 * has been shut down. If the application is running without a
84 * profile, such as when showing the profile manager UI, this key will
85 * not be available. This key is provided by the XUL apprunner or by
86 * the aAppDirProvider object passed to XRE_InitEmbedding.
87 */
88 #define NS_APP_PROFILE_LOCAL_DIR_STARTUP "ProfLDS"
89
90 /**
91 * A directory service key which specifies the system extension
92 * parent directory containing platform-specific extensions.
93 * This key may not be available on all platforms.
94 */
95 #define XRE_SYS_LOCAL_EXTENSION_PARENT_DIR "XRESysLExtPD"
96
97 /**
98 * A directory service key which specifies the system extension
99 * parent directory containing platform-independent extensions.
100 * This key may not be available on all platforms.
101 * Additionally, the directory may be equal to that returned by
102 * XRE_SYS_LOCAL_EXTENSION_PARENT_DIR on some platforms.
103 */
104 #define XRE_SYS_SHARE_EXTENSION_PARENT_DIR "XRESysSExtPD"
105
106 /**
107 * A directory service key which specifies the user system extension
108 * parent directory.
109 */
110 #define XRE_USER_SYS_EXTENSION_DIR "XREUSysExt"
111
112 /**
113 * A directory service key which specifies the distribution specific files for
114 * the application.
115 */
116 #define XRE_APP_DISTRIBUTION_DIR "XREAppDist"
117
118 /**
119 * A directory service key which provides the update directory.
120 * At present this is supported only on Windows.
121 * Windows: Documents and Settings\<User>\Local Settings\Application Data\
122 * <Vendor>\<Application>\<relative path to app dir from Program Files>
123 * If appDir is not under the Program Files, directory service will fail.
124 * Callers should fallback to appDir.
125 */
126 #define XRE_UPDATE_ROOT_DIR "UpdRootD"
127
128 /**
129 * A directory service key which provides an alternate location
130 * to UpdRootD to to store large files. This key is currently
131 * only implemented in the Gonk directory service provider.
132 */
133
134 #define XRE_UPDATE_ARCHIVE_DIR "UpdArchD"
135
136 /**
137 * A directory service key which provides the directory where an OS update is
138 * applied.
139 * At present this is supported only in Gonk.
140 */
141 #define XRE_OS_UPDATE_APPLY_TO_DIR "OSUpdApplyToD"
142
143 /**
144 * Platform flag values for XRE_main.
145 *
146 * XRE_MAIN_FLAG_USE_METRO - On Windows, use the winrt backend. Defaults
147 * to win32 backend.
148 */
149 #define XRE_MAIN_FLAG_USE_METRO 0x01
150
151 /**
152 * Begin an XUL application. Does not return until the user exits the
153 * application.
154 *
155 * @param argc/argv Command-line parameters to pass to the application. On
156 * Windows, these should be in UTF8. On unix-like platforms
157 * these are in the "native" character set.
158 *
159 * @param aAppData Information about the application to be run.
160 *
161 * @param aFlags Platform specific flags.
162 *
163 * @return A native result code suitable for returning from main().
164 *
165 * @note If the binary is linked against the standalone XPCOM glue,
166 * XPCOMGlueStartup() should be called before this method.
167 */
168 XRE_API(int,
169 XRE_main, (int argc, char* argv[], const nsXREAppData* aAppData,
170 uint32_t aFlags))
171
172 /**
173 * Given a path relative to the current working directory (or an absolute
174 * path), return an appropriate nsIFile object.
175 *
176 * @note Pass UTF8 strings on Windows... native charset on other platforms.
177 */
178 XRE_API(nsresult,
179 XRE_GetFileFromPath, (const char *aPath, nsIFile* *aResult))
180
181 /**
182 * Get the path of the running application binary and store it in aResult.
183 * @param argv0 The value passed as argv[0] of main(). This value is only
184 * used on *nix, and only when other methods of determining
185 * the binary path have failed.
186 */
187 XRE_API(nsresult,
188 XRE_GetBinaryPath, (const char *argv0, nsIFile* *aResult))
189
190 /**
191 * Get the static module built in to libxul.
192 */
193 XRE_API(const mozilla::Module*,
194 XRE_GetStaticModule, ())
195
196 /**
197 * Lock a profile directory using platform-specific semantics.
198 *
199 * @param aDirectory The profile directory to lock.
200 * @param aLockObject An opaque lock object. The directory will remain locked
201 * as long as the XPCOM reference is held.
202 */
203 XRE_API(nsresult,
204 XRE_LockProfileDirectory, (nsIFile* aDirectory,
205 nsISupports* *aLockObject))
206
207 /**
208 * Initialize libXUL for embedding purposes.
209 *
210 * @param aLibXULDirectory The directory in which the libXUL shared library
211 * was found.
212 * @param aAppDirectory The directory in which the application components
213 * and resources can be found. This will map to
214 * the NS_OS_CURRENT_PROCESS_DIR directory service
215 * key.
216 * @param aAppDirProvider A directory provider for the application. This
217 * provider will be aggregated by a libxul provider
218 * which will provide the base required GRE keys.
219 *
220 * @note This function must be called from the "main" thread.
221 *
222 * @note At the present time, this function may only be called once in
223 * a given process. Use XRE_TermEmbedding to clean up and free
224 * resources allocated by XRE_InitEmbedding.
225 */
226
227 XRE_API(nsresult,
228 XRE_InitEmbedding2, (nsIFile *aLibXULDirectory,
229 nsIFile *aAppDirectory,
230 nsIDirectoryServiceProvider *aAppDirProvider))
231
232 /**
233 * Register static XPCOM component information.
234 * This method may be called at any time before or after XRE_main or
235 * XRE_InitEmbedding.
236 */
237 XRE_API(nsresult,
238 XRE_AddStaticComponent, (const mozilla::Module* aComponent))
239
240 /**
241 * Register XPCOM components found in an array of files/directories.
242 * This method may be called at any time before or after XRE_main or
243 * XRE_InitEmbedding.
244 *
245 * @param aFiles An array of files or directories.
246 * @param aFileCount the number of items in the aFiles array.
247 * @note appdir/components is registered automatically.
248 *
249 * NS_COMPONENT_LOCATION specifies a location to search for binary XPCOM
250 * components as well as component/chrome manifest files.
251 *
252 * NS_SKIN_LOCATION specifies a location to search for chrome manifest files
253 * which are only allowed to register only skin packages and style overlays.
254 */
255 enum NSLocationType
256 {
257 NS_COMPONENT_LOCATION,
258 NS_SKIN_LOCATION,
259 NS_BOOTSTRAPPED_LOCATION
260 };
261
262 XRE_API(nsresult,
263 XRE_AddManifestLocation, (NSLocationType aType,
264 nsIFile* aLocation))
265
266 /**
267 * Register XPCOM components found in a JAR.
268 * This is similar to XRE_AddManifestLocation except the file specified
269 * must be a zip archive with a manifest named chrome.manifest
270 * This method may be called at any time before or after XRE_main or
271 * XRE_InitEmbedding.
272 *
273 * @param aFiles An array of files or directories.
274 * @param aFileCount the number of items in the aFiles array.
275 * @note appdir/components is registered automatically.
276 *
277 * NS_COMPONENT_LOCATION specifies a location to search for binary XPCOM
278 * components as well as component/chrome manifest files.
279 *
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.
282 */
283 XRE_API(nsresult,
284 XRE_AddJarManifestLocation, (NSLocationType aType,
285 nsIFile* aLocation))
286
287 /**
288 * Fire notifications to inform the toolkit about a new profile. This
289 * method should be called after XRE_InitEmbedding if the embedder
290 * wishes to run with a profile. Normally the embedder should call
291 * XRE_LockProfileDirectory to lock the directory before calling this
292 * method.
293 *
294 * @note There are two possibilities for selecting a profile:
295 *
296 * 1) Select the profile before calling XRE_InitEmbedding. The aAppDirProvider
297 * object passed to XRE_InitEmbedding should provide the
298 * NS_APP_USER_PROFILE_50_DIR key, and may also provide the following keys:
299 * - NS_APP_USER_PROFILE_LOCAL_50_DIR
300 * - NS_APP_PROFILE_DIR_STARTUP
301 * - NS_APP_PROFILE_LOCAL_DIR_STARTUP
302 * In this scenario XRE_NotifyProfile should be called immediately after
303 * XRE_InitEmbedding. Component registration information will be stored in
304 * the profile and JS components may be stored in the fastload cache.
305 *
306 * 2) Select a profile some time after calling XRE_InitEmbedding. In this case
307 * the embedder must install a directory service provider which provides
308 * NS_APP_USER_PROFILE_50_DIR and optionally
309 * NS_APP_USER_PROFILE_LOCAL_50_DIR. Component registration information
310 * will be stored in the application directory and JS components will not
311 * fastload.
312 */
313 XRE_API(void,
314 XRE_NotifyProfile, ())
315
316 /**
317 * Terminate embedding started with XRE_InitEmbedding or XRE_InitEmbedding2
318 */
319 XRE_API(void,
320 XRE_TermEmbedding, ())
321
322 /**
323 * Create a new nsXREAppData structure from an application.ini file.
324 *
325 * @param aINIFile The application.ini file to parse.
326 * @param aAppData A newly-allocated nsXREAppData structure. The caller is
327 * responsible for freeing this structure using
328 * XRE_FreeAppData.
329 */
330 XRE_API(nsresult,
331 XRE_CreateAppData, (nsIFile* aINIFile,
332 nsXREAppData **aAppData))
333
334 /**
335 * Parse an INI file (application.ini or override.ini) into an existing
336 * nsXREAppData structure.
337 *
338 * @param aINIFile The INI file to parse
339 * @param aAppData The nsXREAppData structure to fill.
340 */
341 XRE_API(nsresult,
342 XRE_ParseAppData, (nsIFile* aINIFile,
343 nsXREAppData *aAppData))
344
345 /**
346 * Free a nsXREAppData structure that was allocated with XRE_CreateAppData.
347 */
348 XRE_API(void,
349 XRE_FreeAppData, (nsXREAppData *aAppData))
350
351 enum GeckoProcessType {
352 GeckoProcessType_Default = 0,
353
354 GeckoProcessType_Plugin,
355 GeckoProcessType_Content,
356
357 GeckoProcessType_IPDLUnitTest,
358
359 GeckoProcessType_End,
360 GeckoProcessType_Invalid = GeckoProcessType_End
361 };
362
363 static const char* const kGeckoProcessTypeString[] = {
364 "default",
365 "plugin",
366 "tab",
367 "ipdlunittest"
368 };
369
370 static_assert(MOZ_ARRAY_LENGTH(kGeckoProcessTypeString) ==
371 GeckoProcessType_End,
372 "Array length mismatch");
373
374 XRE_API(const char*,
375 XRE_ChildProcessTypeToString, (GeckoProcessType aProcessType))
376
377 XRE_API(GeckoProcessType,
378 XRE_StringToChildProcessType, (const char* aProcessTypeString))
379
380 #if defined(MOZ_CRASHREPORTER)
381 // Used in the "master" parent process hosting the crash server
382 XRE_API(bool,
383 XRE_TakeMinidumpForChild, (uint32_t aChildPid, nsIFile** aDump,
384 uint32_t* aSequence))
385
386 // Used in child processes.
387 XRE_API(bool,
388 XRE_SetRemoteExceptionHandler, (const char* aPipe))
389 #endif
390
391 XRE_API(nsresult,
392 XRE_InitChildProcess, (int aArgc,
393 char* aArgv[],
394 GeckoProcessType aProcess))
395
396 XRE_API(GeckoProcessType,
397 XRE_GetProcessType, ())
398
399 typedef void (*MainFunction)(void* aData);
400
401 XRE_API(nsresult,
402 XRE_InitParentProcess, (int aArgc,
403 char* aArgv[],
404 MainFunction aMainFunction,
405 void* aMainFunctionExtraData))
406
407 XRE_API(int,
408 XRE_RunIPDLTest, (int aArgc,
409 char* aArgv[]))
410
411 XRE_API(nsresult,
412 XRE_RunAppShell, ())
413
414 XRE_API(nsresult,
415 XRE_InitCommandLine, (int aArgc, char* aArgv[]))
416
417 XRE_API(nsresult,
418 XRE_DeinitCommandLine, ())
419
420 class MessageLoop;
421
422 XRE_API(void,
423 XRE_ShutdownChildProcess, ())
424
425 XRE_API(MessageLoop*,
426 XRE_GetIOMessageLoop, ())
427
428 XRE_API(bool,
429 XRE_SendTestShellCommand, (JSContext* aCx,
430 JSString* aCommand,
431 void* aCallback))
432 XRE_API(bool,
433 XRE_ShutdownTestShell, ())
434
435 XRE_API(void,
436 XRE_InstallX11ErrorHandler, ())
437
438 XRE_API(void,
439 XRE_TelemetryAccumulate, (int aID, uint32_t aSample))
440
441 XRE_API(void,
442 XRE_StartupTimelineRecord, (int aEvent, PRTime aWhen))
443
444 XRE_API(void,
445 XRE_InitOmnijar, (nsIFile* greOmni,
446 nsIFile* appOmni))
447 XRE_API(void,
448 XRE_StopLateWriteChecks, (void))
449
450 #ifdef XP_WIN
451 /**
452 * Valid environment types for XRE_GetWindowsEnvironment.
453 */
454 enum WindowsEnvironmentType {
455 WindowsEnvironmentType_Desktop = 0,
456 WindowsEnvironmentType_Metro = 1
457 };
458
459 /**
460 * Retrieve the Windows desktop environment libXUL is running
461 * under. Valid after a call to XRE_main.
462 */
463 XRE_API(WindowsEnvironmentType,
464 XRE_GetWindowsEnvironment, ())
465 #endif // XP_WIN
466
467 XRE_API(int,
468 XRE_XPCShellMain, (int argc, char** argv, char** envp))
469
470 #endif // _nsXULAppAPI_h__

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial