mozilla

Revision 96765 of Overview of Mozilla embedding APIs

  • Revision slug: Mozilla_embedding_APIs_overview
  • Revision title: Mozilla embedding APIs overview
  • Revision id: 96765
  • Created:
  • Creator: Dosido
  • Is current revision? No
  • Comment

Revision Content

Introduction

The Mozilla Public API consists of a collection of services and components which are accessed via XPCOM interfaces. Mozilla's XPCOM layer consists of a component model (called XPCOM) and the infrastructure necessary to support dynamic registration, instantiation and manipulation of XPCOM components.

At the heart of XPCOM's implementation is the Service Manager and the Component Manager. Together, these two services provide a centralized point for gaining access to all of the public Mozilla interfaces.

The Service Manager exposes all of the available XPCOM services - each service represents a global object which provides some piece of functionality. The Component Manager allows new instances of registered XPCOM components to be instantiated.

Image:public-apis-image2.gif

The embedding layer consists of several components built on top of XPCOM and its services. Much of the Gecko functionality is exposed through a component called the nsWebBrowser. Embedding applications can leverage this component to easily access many of Gecko's features. Each WebBrowser instance represents the "client-area" of a typical browser window. The WebBrowser exposes a set of interfaces which allow the embedding application to control activity and respond to changes within this client area. Using these interfaces an embedding application can build up its own user interface around a WebBrowser instance.

Image:public-apis-image1.gif

Public Classes

The following utility classes are available from the XPCOM DLL. They provide some basic functionality which should be leveraged when building new XPCOM components.

  • nsCOMPtr<interface-type>

These are templatized smart pointers which transparently deal with XPCOM reference counting issues. See the nsCOMPtr User's Manual for more information.

  • nsString

There are a collection of string classes which support both unicode and ASCII strings. These classes provide a variety of string operations as well as dealing with the memory management issues of storing the underlying data. See the String Guide for more details.

  • nsWeakPtr

This is an nsCOMPtr which encapsulates XPCOM weak reference support. See the nsIWeakReference document for more information.

Public Return Codes

   * NS_SUCCEEDED
   * NS_ERROR_FAILURE
   * NS_ERROR_NOT_IMPLEMENTED

Public Functions

The following functions are available from the XPCOM DLL.

  • NS_InitEmbedding

This function initializes the Gecko embedding support. This must be the first function call made into Gecko.

  • NS_TermEmbedding

This function shuts down Gecko and cleans up any remaining resources... Currently, once Gecko has been shutdown, it cannot be restarted in the same process space... This should change in the future.

  • nsMemory
    • nsMemory::Alloc
    • nsMemory::Realloc
    • nsMemory::Free

This helper class provides static accessors to the global nsMemory Service.

  • NS_GetGlobalComponentManager

This function returns an instance of the Component Manager service.

  • NS_ConvertASCIItoUCS2

This is a helper class which converts an ASCII string into a UCS2 string. Typically, instances of this class are stack allocated, and wrap ASCII arguments which must be converted into UCS2.

  • do_QueryInterface

This is a helper class which works in conjunction with nsCOMPtr to perform a simplified call to nsISupports::QueryInterface(...) with a typesafe assignment.

  • do_GetInterface

This function simplfies retrieving interfaces via the nsIInterfaceRequestor::GetInterface(...) method. Using this function, one can use nsISupports instances and still easily access other interfaces via nsIInterfaceRequestor.

Internally, this function tries to convert the nsISupports argument into an nsIInterfaceRequestor and then calls GetInterface(...) to retrieve the requested interface.

  • do_QueryReferent

This function is the equivilent of do_QueryInterface except that it performs the QI through a weak reference.http://www.mozilla.org/projects/embedding/PublicAPIs.html Mozilla Embedding APIs

  • do_GetService

This function simplifies accessing services from the Service Manager.

  • do_CreateInstance

This function simplifies creating new component instances.

  • nsCOMTypeInfo<interface-type>::GetIID()

This template helper class allows easy access to an interface's nsIID. Typically the NS_GET_IID(...) macro is used instead of using the nsCOMTypeInfo template directly.

  • NS_GetWeakReference

This function creates a weak reference to a component which implements the nsIWeakReference interface.

Global Services

nsServiceManager

     The Service Manager is the central repository for accessing instances of the various XPCOM services.  Each service is represented by a singleton object which is instantiated the first time it is requested and remains alive until the Service Manager is shut down, or the service is explicitly unloaded.
     Through the Service Manager, individual services can be loaded, unloaded and accessed.
     Implemented Interfaces:
         * nsIServiceManager
         Related Interfaces:
         * nsIShutdownListener

nsMemory

     The nsMemory service provides the global memory manager implementation for XPCOM.  In addition to memory allocation and release, this service provides low memory notifications, called a memory pressure observers, which are notified when memory is low - thus allowing cached resources to be freed.
     All heap access should be done via the nsMemory service.  To facilitate this, a set of global functions are available to access the nsMemory methods without requiring an instance of the nsMemory service (see nsMemory.h).
     Contract-id:
           NS_MEMORY_CONTRACTID
             Implemented Interfaces:
         * nsIMemory
             Related Interfaces:
         * nsIObserver


nsComponentManager

     The nsComponentManager service is responsible for creating new instances of XPCOM components.  The Component Manager is also responsible for registering and managing the class factories used for component creation...
     Contract-id:
           NS_COMPONENTMANAGER_CONTRACTID
             Implemented Interfaces:
         o nsIComponentManager
         o nsIInterfaceRequestor
             Requestor Interfaces:
         o nsIServiceManager
             Related Interfaces:
         o nsIFactory


nsURILoader

     The nsURILoader service is responsible for targeting a URI at an appropriate content handler.  A content handler may be an existing or new window, a helper application or the Unknown Content Handler - if no other handler can be found for the content-type.
     Contract-id:
           NS_URI_LOADER_CONTRACTID
             Implemented Interfaces:
         o nsIURILoader
      
     Related Interfaces:
         o nsIURIContentListener


nsUnknownContentTypeHandler

      The UnknownContentTypeHandler service is the last resort of the URILoader when no other content handler can be located.  If no registered content handlers are available, the UnknownContentTypeHandler is notified.
     The default implementation of this service displays a dialog box asking the user if the content should be saved to disk...
     Contract-id:
           NS_IUNKNOWNCONTENTTYPEHANDLER_CONTRACTID
             Implemented Interfaces:
         o nsIUnknownContentTypeHandler


HelperApp Launch Dialog

     Contract-id:
           NS_EXTERNALHELPERAPPSERVICE_CONTRACTID
             Implemented Interfaces:
         o nsIExternalHelperAppService


Preferences Service

     The Preferences service provides access to persistent data stored within a user's profile directory.
     Contract-id:
           NS_PREF_CONTRACTID
             Implemented Interfaces:
         o nsIPrefService
         o nsIPrefBranch
      
     Related Interfaces:
         o nsIPrefListener


Profile Manager Service

     Contract-id:
     Implemented Interfaces:
      

Document Loader Service (WebProgress)

     Eventually, this service will be replaced by theWebProgress service...
     Contract-id:
           NS_DOCUMENT_LOADER_SERVICE_CONTRACTID
             Implemented Interfaces:
         o nsIWebProgress
         o nsIDocumentLoader
     Related Interfaces:
         o nsIWebProgressListener



Original Document Information

  • Author(s): rpotts, alecf, oeschger at netscape.com
  • Last Updated Date: March 5, 2003
  • Copyright Information: Creative Commons

Revision Source

<h2 name="Introduction"> Introduction </h2>
<p>The Mozilla Public API consists of a collection of services and components which are accessed via XPCOM interfaces.  Mozilla's XPCOM layer consists of a component model (called XPCOM) and the infrastructure necessary to support dynamic registration, instantiation and manipulation of XPCOM components.
</p><p>At the heart of XPCOM's implementation is the Service Manager and the Component Manager.  Together, these two services provide a centralized point for gaining access to all of the public Mozilla interfaces.
</p><p>The Service Manager exposes all of the available XPCOM services - each service represents a global object which provides some piece of functionality.  The Component Manager allows new instances of registered XPCOM components to be instantiated.
</p><p><img alt="Image:public-apis-image2.gif" src="File:en/Media_Gallery/Public-apis-image2.gif">
</p><p>The embedding layer consists of several components built on top of XPCOM and its services.  Much of the Gecko functionality is exposed through a component called the nsWebBrowser.  Embedding applications can leverage this component to easily access many of Gecko's features.  Each WebBrowser instance represents the "client-area" of a typical browser window.  The WebBrowser exposes a set of interfaces which allow the embedding application to control activity and respond to changes within this client area.  Using these interfaces an embedding application can build up its own user interface around a WebBrowser instance. 
</p><p><img alt="Image:public-apis-image1.gif" src="File:en/Media_Gallery/Public-apis-image1.gif">
</p>
<h2 name="Public_Classes"> Public Classes </h2>
<p>The following utility classes are available from the XPCOM DLL.  They provide some basic functionality which should be leveraged when building new XPCOM components.
</p>
<ul><li> nsCOMPtr&lt;interface-type&gt;
</li></ul>
<p>These are templatized smart pointers which transparently deal with XPCOM reference counting issues.  See the nsCOMPtr User's Manual for more information.
</p>
<ul><li> nsString
</li></ul>
<p>There are a collection of string classes which support both unicode and ASCII strings.  These classes provide a variety of string operations as well as dealing with the memory management issues of storing the underlying data. See the String Guide for more details. 
</p>
<ul><li> nsWeakPtr
</li></ul>
<p>This is an nsCOMPtr which encapsulates XPCOM weak reference support.  See the nsIWeakReference document for more information.
</p>
<h3 name="Public_Return_Codes"> Public Return Codes </h3>
<pre class="eval">   * NS_SUCCEEDED
   * NS_ERROR_FAILURE
   * NS_ERROR_NOT_IMPLEMENTED
</pre>
<h3 name="Public_Functions"> Public Functions </h3>
<p>The following functions are available from the XPCOM DLL.
</p>
<ul><li> NS_InitEmbedding
</li></ul>
<p>This function initializes the Gecko embedding support.  This must be the first function call made into Gecko.
</p>
<ul><li> NS_TermEmbedding
</li></ul>
<p>This function shuts down Gecko and cleans up any remaining resources...  Currently, once Gecko has been shutdown, it cannot be restarted in the same process space...  This should change in the future.
</p>
<ul><li> nsMemory
<ul><li> nsMemory::Alloc
</li><li> nsMemory::Realloc
</li><li> nsMemory::Free
</li></ul>
</li></ul>
<p>This helper class provides static accessors to the global nsMemory Service.
</p>
<ul><li> NS_GetGlobalComponentManager
</li></ul>
<p>This function returns an instance of the Component Manager service.
</p>
<ul><li> NS_ConvertASCIItoUCS2
</li></ul>
<p>This is a helper class which converts an ASCII string into a UCS2 string.  Typically, instances of this class are stack allocated, and wrap ASCII arguments which must be converted into UCS2.
</p>
<ul><li> do_QueryInterface
</li></ul>
<p>This is a helper class which works in conjunction with nsCOMPtr to perform a simplified call to nsISupports::QueryInterface(...) with a typesafe assignment.
</p>
<ul><li> do_GetInterface
</li></ul>
<p>This function simplfies retrieving interfaces via the nsIInterfaceRequestor::GetInterface(...) method.  Using this function, one can use nsISupports instances and still easily access other interfaces via nsIInterfaceRequestor.
</p><p>Internally, this function tries to convert the nsISupports argument into an nsIInterfaceRequestor and then calls GetInterface(...) to retrieve the requested interface.
</p>
<ul><li> do_QueryReferent
</li></ul>
<p>This function is the equivilent of do_QueryInterface except that it performs the QI through a weak reference.http://www.mozilla.org/projects/embedding/PublicAPIs.html
Mozilla Embedding APIs
</p>
<ul><li> do_GetService
</li></ul>
<p>This function simplifies accessing services from the Service Manager.
</p>
<ul><li> do_CreateInstance
</li></ul>
<p>This function simplifies creating new component instances.
</p>
<ul><li>   nsCOMTypeInfo&lt;interface-type&gt;::GetIID()
</li></ul>
<p>This template helper class allows easy access to an interface's nsIID.  Typically the NS_GET_IID(...) macro is used instead of using the nsCOMTypeInfo template directly.
</p>
<ul><li> NS_GetWeakReference
</li></ul>
<p>This function creates a weak reference to a component which implements the nsIWeakReference interface.
</p>
<h3 name="Global_Services"> Global Services </h3>
<h4 name="nsServiceManager"> nsServiceManager </h4>
<pre class="eval">     The Service Manager is the central repository for accessing instances of the various XPCOM services.  Each service is represented by a singleton object which is instantiated the first time it is requested and remains alive until the Service Manager is shut down, or the service is explicitly unloaded.
</pre>
<pre class="eval">     Through the Service Manager, individual services can be loaded, unloaded and accessed.
</pre>
<pre class="eval">     Implemented Interfaces:
         * nsIServiceManager
</pre>
<pre class="eval">         Related Interfaces:
         * nsIShutdownListener
</pre>
<h4 name="nsMemory"> nsMemory </h4>
<pre class="eval">     The nsMemory service provides the global memory manager implementation for XPCOM.  In addition to memory allocation and release, this service provides low memory notifications, called a memory pressure observers, which are notified when memory is low - thus allowing cached resources to be freed.
</pre>
<pre class="eval">     All heap access should be done via the nsMemory service.  To facilitate this, a set of global functions are available to access the nsMemory methods without requiring an instance of the nsMemory service (see nsMemory.h).
</pre>
<pre class="eval">     Contract-id:
           NS_MEMORY_CONTRACTID
             Implemented Interfaces:
         * nsIMemory
</pre>
<pre class="eval">             Related Interfaces:
         * nsIObserver
</pre>
<p><br>              
</p>
<h4 name="nsComponentManager"> nsComponentManager </h4>
<pre class="eval">     The nsComponentManager service is responsible for creating new instances of XPCOM components.  The Component Manager is also responsible for registering and managing the class factories used for component creation...
</pre>
<pre class="eval">     Contract-id:
           NS_COMPONENTMANAGER_CONTRACTID
             Implemented Interfaces:
         o nsIComponentManager
         o nsIInterfaceRequestor
</pre>
<pre class="eval">             Requestor Interfaces:
         o nsIServiceManager
</pre>
<pre class="eval">             Related Interfaces:
         o nsIFactory
</pre>
<p><br>              
</p>
<h4 name="nsURILoader"> nsURILoader </h4>
<pre class="eval">     The nsURILoader service is responsible for targeting a URI at an appropriate content handler.  A content handler may be an existing or new window, a helper application or the Unknown Content Handler - if no other handler can be found for the content-type.
</pre>
<pre class="eval">     Contract-id:
           NS_URI_LOADER_CONTRACTID
             Implemented Interfaces:
         o nsIURILoader
      
     Related Interfaces:
         o nsIURIContentListener
</pre>
<p><br>              
</p>
<h4 name="nsUnknownContentTypeHandler"> nsUnknownContentTypeHandler </h4>
<pre class="eval">      The UnknownContentTypeHandler service is the last resort of the URILoader when no other content handler can be located.  If no registered content handlers are available, the UnknownContentTypeHandler is notified.
</pre>
<pre class="eval">     The default implementation of this service displays a dialog box asking the user if the content should be saved to disk...
</pre>
<pre class="eval">     Contract-id:
           NS_IUNKNOWNCONTENTTYPEHANDLER_CONTRACTID
             Implemented Interfaces:
         o nsIUnknownContentTypeHandler
</pre>
<p><br>              
</p><p>HelperApp Launch Dialog
</p>
<pre class="eval">     Contract-id:
           NS_EXTERNALHELPERAPPSERVICE_CONTRACTID
             Implemented Interfaces:
         o nsIExternalHelperAppService
</pre>
<p><br>              
</p>
<h4 name="Preferences_Service"> Preferences Service </h4>
<pre class="eval">     The Preferences service provides access to persistent data stored within a user's profile directory.
</pre>
<pre class="eval">     Contract-id:
           NS_PREF_CONTRACTID
             Implemented Interfaces:
         o nsIPrefService
         o nsIPrefBranch
      
     Related Interfaces:
         o nsIPrefListener
</pre>
<p><br>              
</p>
<h4 name="Profile_Manager_Service"> Profile Manager Service </h4>
<pre class="eval">     Contract-id:
</pre>
<pre class="eval">     Implemented Interfaces:
      
</pre>
<h4 name="Document_Loader_Service_.28WebProgress.29"> Document Loader Service (WebProgress) </h4>
<pre class="eval">     Eventually, this service will be replaced by theWebProgress service...
     Contract-id:
           NS_DOCUMENT_LOADER_SERVICE_CONTRACTID
             Implemented Interfaces:
         o nsIWebProgress
         o nsIDocumentLoader
</pre>
<pre class="eval">     Related Interfaces:
         o nsIWebProgressListener
</pre>
<p><br>
</p><p><br>
</p>
<div class="originaldocinfo">
<h2 name="Original_Document_Information"> Original Document Information </h2>
<ul><li> Author(s): rpotts, alecf, oeschger at netscape.com
</li><li> Last Updated Date: March 5, 2003
</li><li> Copyright Information: Creative Commons
</li></ul>
</div>
Revert to this revision