/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is mozilla.org code. * * The Initial Developer of the Original Code is * Netscape Communications Corporation. * Portions created by the Initial Developer are Copyright (C) 2002 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Brian Ryner * Benjamin Smedberg * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #ifndef _nsXULAppAPI_h__ #define _nsXULAppAPI_h__ #include "prtypes.h" #include "nsID.h" #include "xrecore.h" #include "nsXPCOM.h" #include "nsISupports.h" /** * Application-specific data needed to start the apprunner. * * @status FROZEN - This API is stable. Additional fields may be added to the * end of the structure in the future. Runtime detection * of the version of nsXREAppData can be determined by * examining the "size" field. * * @note When this structure is allocated and manipulated by XRE_CreateAppData, * string fields will be allocated with NS_Alloc, and interface pointers * are strong references. */ struct nsXREAppData { /** * This should be set to sizeof(nsXREAppData). This structure may be * extended in future releases, and this ensures that binary compatibility * is maintained. */ PRUint32 size; /** * The directory of the application to be run. May be null if the * xulrunner and the app are installed into the same directory. */ nsILocalFile* directory; /** * The name of the application vendor. This must be ASCII, and is normally * mixed-case, e.g. "Mozilla". Optional (may be null), but highly * recommended. Must not be the empty string. */ const char *vendor; /** * The name of the application. This must be ASCII, and is normally * mixed-case, e.g. "Firefox". Required (must not be null or an empty * string). */ const char *name; /** * The major version, e.g. "0.8.0+". Optional (may be null), but * required for advanced application features such as the extension * manager and update service. Must not be the empty string. */ const char *version; /** * The application's build identifier, e.g. "2004051604" */ const char *buildID; /** * The application's UUID. Used by the extension manager to determine * compatible extensions. Optional, but required for advanced application * features such as the extension manager and update service. * * This has traditionally been in the form * "{AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE}" but for new applications * a more readable form is encouraged: "appname@vendor.tld". Only * the following characters are allowed: a-z A-Z 0-9 - . @ _ { } * */ const char *ID; /** * The copyright information to print for the -h commandline flag, * e.g. "Copyright (c) 2003 mozilla.org". */ const char *copyright; /** * Combination of NS_XRE_ prefixed flags (defined below). */ PRUint32 flags; /** * The location of the XRE. XRE_main may not be able to figure this out * programatically. */ nsILocalFile* xreDirectory; /** * The minimum/maximum compatible XRE version. */ const char *minVersion; const char *maxVersion; /** * The server URL to send crash reports to. */ const char *crashReporterURL; /** * The profile directory that will be used. Optional (may be null). Must not * be the empty string, must be ASCII. The path is split into components * along the path separator characters '/' and '\'. * * The application data directory ("UAppData", see below) is normally * composed as follows, where $HOME is platform-specific: * * UAppData = $HOME[/$vendor]/$name * * If present, the 'profile' string will be used instead of the combination of * vendor and name as follows: * * UAppData = $HOME/$profile */ const char *profile; }; /** * Indicates whether or not the profile migrator service may be * invoked at startup when creating a profile. */ #define NS_XRE_ENABLE_PROFILE_MIGRATOR (1 << 1) /** * Indicates whether or not the extension manager service should be * initialized at startup. */ #define NS_XRE_ENABLE_EXTENSION_MANAGER (1 << 2) /** * Indicates whether or not to use Breakpad crash reporting. */ #define NS_XRE_ENABLE_CRASH_REPORTER (1 << 3) /** * A directory service key which provides the platform-correct "application * data" directory as follows, where $name and $vendor are as defined above and * $vendor is optional: * * Windows: * HOME = Documents and Settings\$USER\Application Data * UAppData = $HOME[\$vendor]\$name * * Unix: * HOME = ~ * UAppData = $HOME/.[$vendor/]$name * * Mac: * HOME = ~ * UAppData = $HOME/Library/Application Support/$name * * Note that the "profile" member above will change the value of UAppData as * follows: * * Windows: * UAppData = $HOME\$profile * * Unix: * UAppData = $HOME/.$profile * * Mac: * UAppData = $HOME/Library/Application Support/$profile */ #define XRE_USER_APP_DATA_DIR "UAppData" /** * A directory service key which provides a list of all enabled extension * directories. The list includes compatible platform-specific extension * subdirectories. * * @note The directory list will have no members when the application is * launched in safe mode. */ #define XRE_EXTENSIONS_DIR_LIST "XREExtDL" /** * A directory service key which provides the executable file used to * launch the current process. This is the same value returned by the * XRE_GetBinaryPath function defined below. */ #define XRE_EXECUTABLE_FILE "XREExeF" /** * A directory service key which specifies the profile * directory. Unlike the NS_APP_USER_PROFILE_50_DIR key, this key may * be available when the profile hasn't been "started", or after is * has been shut down. If the application is running without a * profile, such as when showing the profile manager UI, this key will * not be available. This key is provided by the XUL apprunner or by * the aAppDirProvider object passed to XRE_InitEmbedding. */ #define NS_APP_PROFILE_DIR_STARTUP "ProfDS" /** * A directory service key which specifies the profile * directory. Unlike the NS_APP_USER_PROFILE_LOCAL_50_DIR key, this key may * be available when the profile hasn't been "started", or after is * has been shut down. If the application is running without a * profile, such as when showing the profile manager UI, this key will * not be available. This key is provided by the XUL apprunner or by * the aAppDirProvider object passed to XRE_InitEmbedding. */ #define NS_APP_PROFILE_LOCAL_DIR_STARTUP "ProfLDS" /** * A directory service key which specifies the system extension * parent directory containing platform-specific extensions. * This key may not be available on all platforms. */ #define XRE_SYS_LOCAL_EXTENSION_PARENT_DIR "XRESysLExtPD" /** * A directory service key which specifies the system extension * parent directory containing platform-independent extensions. * This key may not be available on all platforms. * Additionally, the directory may be equal to that returned by * XRE_SYS_LOCAL_EXTENSION_PARENT_DIR on some platforms. */ #define XRE_SYS_SHARE_EXTENSION_PARENT_DIR "XRESysSExtPD" /** * A directory service key which specifies the user system extension * parent directory. */ #define XRE_USER_SYS_EXTENSION_DIR "XREUSysExt" /** * Begin an XUL application. Does not return until the user exits the * application. * * @param argc/argv Command-line parameters to pass to the application. On * Windows, these should be in UTF8. On unix-like platforms * these are in the "native" character set. * * @param aAppData Information about the application to be run. * * @return A native result code suitable for returning from main(). * * @note If the binary is linked against the standalone XPCOM glue, * XPCOMGlueStartup() should be called before this method. * */ XRE_API(int, XRE_main, (int argc, char* argv[], const nsXREAppData* sAppData)) /** * Given a path relative to the current working directory (or an absolute * path), return an appropriate nsILocalFile object. * * @note Pass UTF8 strings on Windows... native charset on other platforms. */ XRE_API(nsresult, XRE_GetFileFromPath, (const char *aPath, nsILocalFile* *aResult)) /** * Get the path of the running application binary and store it in aResult. * @param argv0 The value passed as argv[0] of main(). This value is only * used on *nix, and only when other methods of determining * the binary path have failed. */ XRE_API(nsresult, XRE_GetBinaryPath, (const char *argv0, nsILocalFile* *aResult)) /** * Get the static components built in to libxul. */ XRE_API(void, XRE_GetStaticComponents, (nsStaticModuleInfo const **aStaticComponents, PRUint32 *aComponentCount)) /** * Lock a profile directory using platform-specific semantics. * * @param aDirectory The profile directory to lock. * @param aLockObject An opaque lock object. The directory will remain locked * as long as the XPCOM reference is held. */ XRE_API(nsresult, XRE_LockProfileDirectory, (nsILocalFile* aDirectory, nsISupports* *aLockObject)) /** * Initialize libXUL for embedding purposes. * * @param aLibXULDirectory The directory in which the libXUL shared library * was found. * @param aAppDirectory The directory in which the application components * and resources can be found. This will map to * the NS_OS_CURRENT_PROCESS_DIR directory service * key. * @param aAppDirProvider A directory provider for the application. This * provider will be aggregated by a libxul provider * which will provide the base required GRE keys. * @param aStaticComponents Static components provided by the embedding * application. This should *not* include the * components from XRE_GetStaticComponents. May be * null if there are no static components. * @param aStaticComponentCount the number of static components in * aStaticComponents * * @note This function must be called from the "main" thread. * * @note At the present time, this function may only be called once in * a given process. Use XRE_TermEmbedding to clean up and free * resources allocated by XRE_InitEmbedding. */ XRE_API(nsresult, XRE_InitEmbedding, (nsILocalFile *aLibXULDirectory, nsILocalFile *aAppDirectory, nsIDirectoryServiceProvider *aAppDirProvider, nsStaticModuleInfo const *aStaticComponents, PRUint32 aStaticComponentCount)) /** * Fire notifications to inform the toolkit about a new profile. This * method should be called after XRE_InitEmbedding if the embedder * wishes to run with a profile. Normally the embedder should call * XRE_LockProfileDirectory to lock the directory before calling this * method. * * @note There are two possibilities for selecting a profile: * * 1) Select the profile before calling XRE_InitEmbedding. The aAppDirProvider * object passed to XRE_InitEmbedding should provide the * NS_APP_USER_PROFILE_50_DIR key, and may also provide the following keys: * - NS_APP_USER_PROFILE_LOCAL_50_DIR * - NS_APP_PROFILE_DIR_STARTUP * - NS_APP_PROFILE_LOCAL_DIR_STARTUP * In this scenario XRE_NotifyProfile should be called immediately after * XRE_InitEmbedding. Component registration information will be stored in * the profile and JS components may be stored in the fastload cache. * * 2) Select a profile some time after calling XRE_InitEmbedding. In this case * the embedder must install a directory service provider which provides * NS_APP_USER_PROFILE_50_DIR and optionally * NS_APP_USER_PROFILE_LOCAL_50_DIR. Component registration information * will be stored in the application directory and JS components will not * fastload. */ XRE_API(void, XRE_NotifyProfile, ()) /** * Terminate embedding started with XRE_InitEmbedding or XRE_InitEmbedding2 */ XRE_API(void, XRE_TermEmbedding, ()) /** * Create a new nsXREAppData structure from an application.ini file. * * @param aINIFile The application.ini file to parse. * @param aAppData A newly-allocated nsXREAppData structure. The caller is * responsible for freeing this structure using * XRE_FreeAppData. */ XRE_API(nsresult, XRE_CreateAppData, (nsILocalFile* aINIFile, nsXREAppData **aAppData)) /** * Parse an INI file (application.ini or override.ini) into an existing * nsXREAppData structure. * * @param aINIFile The INI file to parse * @param aAppData The nsXREAppData structure to fill. */ XRE_API(nsresult, XRE_ParseAppData, (nsILocalFile* aINIFile, nsXREAppData *aAppData)) /** * Free a nsXREAppData structure that was allocated with XRE_CreateAppData. */ XRE_API(void, XRE_FreeAppData, (nsXREAppData *aAppData)) enum GeckoChildProcessType { GeckoChildProcess_Default, GeckoChildProcess_Plugin, GeckoChildProcess_Tab, GeckoChildProcess_TestShell, GeckoChildProcess_End, GeckoChildProcess_Invalid = GeckoChildProcess_End }; static const char* const kGeckoChildProcessTypeString[] = { "default", "plugin", "tab", "testshell" }; XRE_API(const char*, XRE_ChildProcessTypeToString, (GeckoChildProcessType aProcessType)) XRE_API(GeckoChildProcessType, XRE_StringToChildProcessType, (const char* aProcessTypeString)) XRE_API(nsresult, XRE_InitChildProcess, (int aArgc, char* aArgv[], GeckoChildProcessType aProcess=GeckoChildProcess_Default)) typedef void (*MainFunction)(void* aData); XRE_API(nsresult, XRE_InitParentProcess, (int aArgc, char* aArgv[], MainFunction aMainFunction, void* aMainFunctionExtraData)) XRE_API(int, XRE_RunTestShell, (int aArgc, char* aArgv[])) #endif // _nsXULAppAPI_h__