Back to index

lightning-sunbird  0.9+nobinonly
Functions
nsEmbedAPI.h File Reference

The Gecko embedding API functions, structures and definitions. More...

#include "nscore.h"
#include "nsXPCOM.h"
#include "nsILocalFile.h"
#include "nsIDirectoryService.h"
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

NS_HIDDEN NS_METHOD NS_InitEmbedding (nsILocalFile *aMozBinDirectory, nsIDirectoryServiceProvider *aAppFileLocProvider, nsStaticModuleInfo const *aStaticComponents=nsnull, PRUint32 aStaticComponentCount=0)
 Initialises the Gecko embedding layer.
NS_HIDDEN NS_METHOD NS_TermEmbedding ()
 Terminates the Gecko embedding layer.

Detailed Description

The Gecko embedding API functions, structures and definitions.

Definition in file nsEmbedAPI.h.


Function Documentation

NS_HIDDEN NS_METHOD NS_InitEmbedding ( nsILocalFile aMozBinDirectory,
nsIDirectoryServiceProvider aAppFileLocProvider,
nsStaticModuleInfo const aStaticComponents = nsnull,
PRUint32  aStaticComponentCount = 0 
)

Initialises the Gecko embedding layer.

You must call this method before proceeding to use Gecko. This function ensures XPCOM is started, creates the component registry if necessary and starts global services.

FROZEN

Note:
Use NS_NewLocalFile to create the file object you supply as the bin directory path in this call. The function may be safely called before the rest of XPCOM or embedding has been initialised.
Parameters:
aMozBinDirectoryThe Gecko directory containing the component registry and runtime libraries; or use nsnull to use the working directory.
aAppFileLocProviderThe object to be used by Gecko that specifies to Gecko where to find profiles, the component registry preferences and so on; or use nsnull for the default behaviour.
aStaticComponentsAn array of static components (see NS_InitXPCOM3). may be null.
aStaticComponentCountNumber of static components in the aStaticComponents array.
See also:
NS_NewLocalFile
nsILocalFile
nsIDirectoryServiceProvider
Returns:
NS_OK for success; other error codes indicate a failure during initialisation.

Definition at line 86 of file nsEmbedAPI.cpp.

{
    nsresult rv;

    // Reentrant calls to this method do nothing except increment a counter
    sInitCounter++;
    if (sInitCounter > 1)
        return NS_OK;

    // Initialise XPCOM
#ifdef HACK_AROUND_NONREENTRANT_INITXPCOM
    // Can't call NS_InitXPCom more than once or things go boom!
    if (!sXPCOMInitializedFlag)
#endif
    {
        // Initialise XPCOM
        rv = NS_InitXPCOM3(&sServiceManager, mozBinDirectory, appFileLocProvider,
                           aStaticComponents, aStaticComponentCount);
        NS_ENSURE_SUCCESS(rv, rv);
                
#ifdef HACK_AROUND_NONREENTRANT_INITXPCOM
        sXPCOMInitializedFlag = PR_TRUE;
        sXPCOMCleanupHack.mCleanOnExit = PR_TRUE;
#endif
    }
    // Register components
    if (!sRegistryInitializedFlag)
    {
#ifdef DEBUG
        nsIComponentRegistrar *registrar;
        rv = sServiceManager->QueryInterface(NS_GET_IID(nsIComponentRegistrar),
                                             (void **) &registrar);
        if (NS_FAILED(rv))
        {
            NS_WARNING("Could not QI to registrar");
            return rv;
        }
        rv = registrar->AutoRegister(nsnull);
        if (NS_FAILED(rv))
        {
            NS_WARNING("Could not AutoRegister");
        }
        else
        {
            // If the application is using an GRE, then, auto register components
            // in the GRE directory as well.
            //
            // The application indicates that it's using an GRE by returning a
            // valid nsIFile when queried (via appFileLocProvider) for the
            // NS_GRE_DIR atom as shown below

            if (appFileLocProvider)
            {
                nsIFile *greDir = nsnull;
                PRBool persistent = PR_TRUE;

                appFileLocProvider->GetFile(NS_GRE_DIR, &persistent,
                                            &greDir);
                if (greDir)
                {
                    rv = registrar->AutoRegister(greDir);
                    if (NS_FAILED(rv))
                        NS_WARNING("Could not AutoRegister GRE components");
                    NS_RELEASE(greDir);
                }
            }
        }
        NS_RELEASE(registrar);
        if (NS_FAILED(rv))
            return rv;
#endif
        sRegistryInitializedFlag = PR_TRUE;
    }

    nsIComponentManager *compMgr;
    rv = sServiceManager->QueryInterface(NS_GET_IID(nsIComponentManager),
                                         (void **) &compMgr);
    if (NS_FAILED(rv))
        return rv;

    nsIObserver *startupNotifier;
    rv = compMgr->CreateInstanceByContractID(NS_APPSTARTUPNOTIFIER_CONTRACTID,
                                             NULL,
                                             NS_GET_IID(nsIObserver),
                                             (void **) &startupNotifier);
    NS_RELEASE(compMgr);
    if (NS_FAILED(rv))
        return rv;

         startupNotifier->Observe(nsnull, APPSTARTUP_TOPIC, nsnull);
    NS_RELEASE(startupNotifier);

#ifdef HACK_AROUND_THREADING_ISSUES
    // XXX force certain objects to be created on the main thread
    nsIStringBundleService *bundleService;
    rv = sServiceManager->GetServiceByContractID(NS_STRINGBUNDLE_CONTRACTID,
                                                 NS_GET_IID(nsIStringBundleService),
                                                 (void **) &bundleService);
    if (NS_SUCCEEDED(rv))
    {
        nsIStringBundle *stringBundle;
        const char propertyURL[] = "chrome://necko/locale/necko.properties";
        rv = bundleService->CreateBundle(propertyURL, &stringBundle);
        NS_RELEASE(stringBundle);
        NS_RELEASE(bundleService);
    }
#endif

    return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Terminates the Gecko embedding layer.

Call this function during shutdown to ensure that global services are unloaded, files are closed and XPCOM is shutdown.

FROZEN

Note:
Release any XPCOM objects within Gecko that you may be holding a reference to before calling this function.
Returns:
NS_OK

Definition at line 201 of file nsEmbedAPI.cpp.

{
    // Reentrant calls to this method do nothing except decrement a counter
    if (sInitCounter > 1)
    {
        sInitCounter--;
        return NS_OK;
    }
    sInitCounter = 0;

    NS_IF_RELEASE(sServiceManager);

    // Terminate XPCOM & cleanup
#ifndef HACK_AROUND_NONREENTRANT_INITXPCOM
    nsresult rv = NS_ShutdownXPCOM(sServiceManager);
    NS_ENSURE_SUCCESS(rv, rv);
#endif

    return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function: