NS_InitXPCOM3

Summary

The NS_InitXPCOM3 function initiates use of XPCOM in the calling process with support for statically defined XPCOM modules.

#include "nsXPCOM.h"
 
nsresult NS_InitXPCOM3(
  nsIServiceManager** aResult,
  nsIFile* aBinDirectory,
  nsIDirectoryServiceProvider* aAppFileLocationProvider,
  nsStaticModuleInfo const* aStaticModules,
  PRUint32 aStaticModuleCount
);

Parameters

aResult: [out] The resulting XPCOM service manager. You may pass null if you are not interested in this return value. The service manager may alternatively be accessed by calling NS_GetServiceManager. The resulting interface pointer is AddRef'd upon return and must either be Release'd explicitly or passed to NS_ShutdownXPCOM when the application is finished with XPCOM.

aBinDirectory: [in] The directory containing the component registry and runtime libraries. Pass null to specify that the current working directory should be used.

aAppFileLocationProvider: [in] The object to be used by XPCOM to locate application specific directories and files (e.g., the user profile, the component registry, etc.). This parameter may be nsnull.

aStaticModules: [in] An array of nsStaticModuleInfo objects. Passing null causes the default (built-in) static modules to be registered, if present.

aStaticModuleCount: [in] The number of elements in aStaticModules.

Return Values

The NS_InitXPCOM3 function returns NS_OK if successful. Otherwise, it returns an error code. Some of the possible errors are documented below:

NS_ERROR_NOT_INITIALIZED: Indicates that static globals were not yet initialized, which may happen if this method is called before XPCOM's static initialization code executes. This error may also occur if XPCOM is being initialized after NS_ShutdownXPCOM has been called.

Remarks

You must call NS_InitXPCOM3 (or NS_InitXPCOM2) before proceeding to use XPCOM in a process. The one exception is that you may call NS_NewLocalFile or NS_NewNativeLocalFile to create a nsIFile needed for the aBinDirectory parameter to NS_InitXPCOM3. Many of the XPCOM glue functions and classes are also available prior to XPCOM initialization, including for example nsEmbedCString and nsCOMPtr.

Initializing XPCOM with static modules allows the application to easily define modules that are linked into the application's executable. This can be a performance improvement over dynamically loaded XPCOM modules.

History

This function was finalized for Mozilla 1.8. See bug 296561 for details.