1999-02-02 01:17:58 +03:00
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
< html >
< head >
< meta http-equiv = "Content-Type" content = "text/html; charset=iso-8859-1" >
< meta name = "Author" content = "Suresh Duddi" >
1999-04-12 16:47:30 +04:00
< meta name = "GENERATOR" content = "Mozilla/4.51 [en] (WinNT; U) [Netscape]" >
1999-02-02 01:17:58 +03:00
< title > XPCOM Dynamic Component Registration< / title >
< / head >
< body >
< center >
< h2 >
XPCOM Dynamic Component Registration< / h2 > < / center >
< center > Suresh Duddi < < a href = "mailto:dp@netscape.com" > dp@netscape.com< / a > >
< hr WIDTH = "100%" > < / center >
< p > Dynamic object registration in XPCOM is achieved by interaction of the
following components:
< ul >
< li >
The Registry< / li >
< li >
The Repository< / li >
< li >
The Service Manager< / li >
< li >
Component dll implementing < tt > NSRegisterSelf()< / tt > < / li >
< / ul >
The registration mechanism for XPCOM components is similar in many ways
to that of COM. The XPCOM component dlls will have the opportunity to register
themselves with the registry. The exact time of installation would be either
at install time or as a result of < b > autodetection< / b > by the Repository
Manager at runtime.
< br >
< h3 >
< a NAME = "The Registry: XPCOM Hierarchy" > < / a > The Registry: XPCOM Hierarchy< / h3 >
XPCOM uses the nsRegistry to store mappings between CLSIDs and their implementations.
The Registry provides persistent storage of hierarchical keys and name-value
pairs associated with each key. Each key also keeps a default value.
< p > XPCOM will use the following registry hierarchy:
< blockquote > < tt > ROOTKEY_COMMON< / tt >
1999-02-25 20:43:02 +03:00
< br > < tt > Common - Classes - CLSID< / tt >
< br > < tt > < b > < font color = "#CC0000" > {108d75a0-bab5-11d2-96c4-0060b0fb9956}< / font > < / b > < / tt >
1999-02-02 01:17:58 +03:00
< br > < tt >
1999-02-25 20:43:02 +03:00
InprocServer (S) = < font color = "#CC0000" > libnfs-protocol.so< / font > < / tt >
1999-02-24 23:24:27 +03:00
< br > < tt >
1999-02-25 20:43:02 +03:00
ProgID (S) = < b > < font color = "#CC0000" > component://netscape/network-protocol& type=nfs< / font > < / b > < / tt >
1999-02-24 23:24:27 +03:00
< br > < tt >
1999-02-25 20:43:02 +03:00
ClassName (S) = < b > < font color = "#CC0000" > NFS Protocol
Handler< / font > < / b > < / tt >
< p > < tt > < font color = "#CC0000" > component://netscape/network-protocol& type=nfs< / font > < / tt >
< br > < tt >
CLSID (S) = < font color = "#CC0000" > {108d75a0-bab5-11d2-96c4-0060b0fb9956}< / font > < / tt >
< p > < tt > < i > < / i > Software - Netscape - XPCOM< / tt >
< br > < tt > VersionString
(S) = < font color = "#CC0000" > alpha0.20< / font > < / tt >
< p > < tt > < font color = "#CC0000" > libnfs-protocol.so< / font > < / tt >
< br > < tt >
ComponentsCount (S) = < font color = "#CC0000" > 1< / font > < / tt >
< br > < tt >
FileSize (S)
= < font color = "#CC0000" > 78965< / font > < / tt >
< br > < tt >
LastModTimeStamp (S) = < font color = "#CC0000" > Wed Feb
24 11:24:06 PST 1999< / font > < / tt > < / blockquote >
1999-02-02 01:17:58 +03:00
< h3 >
< a NAME = "The Repository: Object instance creation" > < / a > The Repository:
Object instance creation< / h3 >
1999-02-25 20:43:02 +03:00
All object creation happens via The Repository. < tt > nsIRepository::CreateInstance()< / tt >
1999-02-02 01:17:58 +03:00
will be the primary way of creation of object instances. The steps in instantiation
of an object that implements the IID interface and of class CLSID is as
follows:
< ol >
< li >
The CLSID of the component that would need to create the object instance
is identified.< / li >
1999-02-25 20:43:02 +03:00
< ol > Callers use < tt > nsIRepository::ProgIDToCLSID()< / tt > to convert the
ProgID string to the CLSID.< / ol >
1999-02-02 01:17:58 +03:00
< li >
Load the dll associated with the CLSID after consulting the Registry< / li >
< li >
Instantiate the class factory by calling a globally exported dll function
< tt > NSGetFactory()< / tt > .
1999-02-24 23:24:27 +03:00
This returns an instance of the class factory that implements the < tt > nsIFactory< / tt >
1999-02-02 01:17:58 +03:00
interface.< / li >
< li >
The actual object creation is delegated to this < tt > nsIFactory< / tt > instance
with a call to < tt > nsIFactory::CreateInstance()< / tt > .< / li >
< / ol >
< h3 >
< a NAME = "The Service Manager" > < / a > The Service Manager< / h3 >
All globally created system services are available via the < tt > nsIServiceManager< / tt > ,
including the < tt > nsIRepository< / tt > and < tt > nsIRegistry< / tt > . Although
the < tt > nsIServiceManager< / tt > uses the Registry and Repository in the
creation and maintenance of other services, the circular dependency is
broken by not letting the < tt > nsIServiceManager< / tt > create the < tt > nsIRepository< / tt >
and < tt > nsIRegistry< / tt > instance and registering them specially with the
< tt > nsIServiceManager< / tt > .
The nsIServiceManager is passed into NSGetFactory() for assisting the DLL
in the Factory creation process.
< h3 >
< a NAME = "Component Registration" > < / a > Component Registration< / h3 >
Either at installation time of the Component or at times when the XPCOM
library autodetect new/changed dlls, component registration is activated.
The autodetection happens at startup time of the navigator or via a javascript
trigger < tt > navigator.repository.autodetect()< / tt > . The steps in component
registration would be:
< ol >
< li >
The dll is loaded< / li >
< li >
The component is allowed to self register by a call to a globally exported
dll function < tt > NSRegisterSelf()< / tt > . The < tt > nsIServiceManager< / tt >
and the fullpath of the dll are passed in to assist in the registration
process. The dll is expected to create/modify its entries in the Registry
according to the guidelines of the < a href = "#The Registry: XPCOM Hierarchy" > XPCOM
hierarchy< / a > in the registry. < tt > nsIRepository< / tt > , which can be queried
from the < tt > nsIServiceManager< / tt > , has useful registration functions
that would easen the process.< / li >
< li >
The dll is unloaded< / li >
< / ol >
< h3 >
< a NAME = "Autodetection of Components" > < / a > Autodetection of Components< / h3 >
Autodetection of changed dlls happened by storing the dll's last modified
time and its size in the Registry automatically. If either the last modified
time stamp or the filesize differs from that stored in the Registry for
the dll, re-registration takes place. Before re-registration, the existing
instances of the objects created by the classes in the dll are not freed
because the < tt > nsIRepository< / tt > has no list of them. The < tt > NSCanUnload()< / tt >
will be called with input parameter < i > force< / i > set to < tt > true< / tt > .
The dll has to prepare for getting unloaded. After this call returns, the
dll < b > will< / b > be unloaded if the return value is < tt > true< / tt > . If the
dll detects that it cannot properly prepare for unloading, then it can
return < tt > false< / tt > . XPCOM will not let the re-registration of the modified
dll proceed in this case. There is nothing much that XPCOM library can
do to salvage this situation other than warning the user of possible instability
and advice a restart upon which the re-registration will happen.
1999-02-25 20:43:02 +03:00
< h3 >
< a NAME = "ProgID Spec" > < / a > ProgID Spec< / h3 >
1999-04-12 16:47:30 +04:00
The general format of ProgIDs is < i > < b > < font color = "#990000" > component://< / font > < / b > netscape< b > < font color = "#990000" > /< / font > < / b > compname< b > < font color = "#990000" > ?< / font > < / b > var< b > < font color = "#990000" > =< / font > < / b > value< b > < font color = "#990000" > ;< / font > < / b > var< b > < font color = "#990000" > =< / font > < / b > value< b > < font color = "#990000" > ;< / font > < / b > var< b > < font color = "#990000" > =< / font > < / b > value...< / i >
1999-04-03 01:43:54 +04:00
< p > Let us consider some more examples:
1999-02-25 20:43:02 +03:00
< ol >
< li >
A pluggable protocol that implementes the nfs protocol< / li >
< li >
A converter that can handle application/x-zip< / li >
< li >
A plugin that can handle image/gif< / li >
< li >
A widget that can do a toolbar< / li >
< li >
A datasource that can handle mail< / li >
< li >
A helperapp that deals with application/postscript< / li >
< / ol >
All the above have what type they are and one or more arguments on what
they particularly do.
< p > The ProgID for these would look like
< ol >
< li >
1999-04-03 01:43:54 +04:00
< tt > component://netscape/network-protocol?type=nfs< / tt > < / li >
1999-02-25 20:43:02 +03:00
< li >
1999-04-03 01:43:54 +04:00
< tt > component://netscape/data-converter?type=application/x-zip< / tt > < / li >
1999-02-25 20:43:02 +03:00
< li >
1999-04-12 16:47:30 +04:00
< tt > component://netscape/plugin?type=image/gif;name=ImageMedia%20Gif%20Image%20Plugin;Description=Renders%20GIF%20Images....< / tt > < / li >
1999-02-25 20:43:02 +03:00
< li >
1999-04-03 01:43:54 +04:00
< tt > component://netscape/widget?type=toolbar< / tt > < / li >
1999-02-25 20:43:02 +03:00
< li >
1999-04-03 01:43:54 +04:00
< tt > component://netscape/rdf/datsource?type=mail< / tt > < / li >
1999-02-25 20:43:02 +03:00
< li >
1999-04-03 01:43:54 +04:00
< tt > component://netscape/helperapp?type=application/postscript< / tt > < / li >
1999-02-25 20:43:02 +03:00
< / ol >
{Assume proper escaping of all above URI}
< p > The above semantics would let ProgID be an extensible mechanism that
could be searched on multiple ways. And
< br > query on a progid should match only whatever was passed in. So a query
for
1999-04-03 01:43:54 +04:00
< br > component://netscape/plugin?type=image/gif should pass for the progid
specified above. We could extend this
1999-02-25 20:43:02 +03:00
< br > mechanism with wildcards, but I dont want to go there yet... :-)
1999-02-02 01:17:58 +03:00
< br >
< h3 >
1999-04-12 16:47:30 +04:00
< a NAME = "Startup Components" > < / a > Components created on events< / h3 >
Some dlls have components that want to be created on certain events namely
Startup, Shutdown (for now). Example is xpinstall.
< blockquote > RegisterComponentForEvent(..., RegisterationTime when, ...)
< br > RegisterFactoryForEvent(..., RegistrationTime when,...)< / blockquote >
exists for this purpose. When an application wants to Fire the particular
event, it calls
< blockquote > nsComponentManager::FireEvent(RegistrationTime when)< / blockquote >
ComponentManager will look for components that are registered to be created
on these events and do the following for each of the components:
< ol >
< li >
CreateInstance(...,CID, knsIStartupComponentIID, & obj);< / li >
< br > For a shutdown event, knsIShutdownComponentIID would be used.
< br >
< li >
obj->Release();< / li >
< br > The component needs to take adequate measures to keep itself alive
and figure out how it would delete the object, since a Release() happens
immediately after a CreateInstace()< / ol >
< b > < i > Warning: < / i > < / b > Order of creation of multiple components registered
on the same event is not defined. Component dependencies aren't thought
of yet.
< br >
< h3 >
1999-02-25 20:43:02 +03:00
< a NAME = "How will all this help me" > < / a > How will all this help me< / h3 >
1999-02-02 01:17:58 +03:00
For Component Developers:
< ul >
< li >
Component dlls developed could be dropped into a directory, a JS function
called after which your component is in business without even a restart
of the browser. Of course, there needs to be someone accessing it.< / li >
< li >
No need to export you CLSID or run around finding where to advertise your
CLSID< / li >
< / ul >
For Component Users:
< blockquote >
< li >
No more hacking in calls to < tt > nsIRepository::RegisterFactory()< / tt > < / li >
< li >
No need to know the CLSID of components that you want to instantiate. Component
creation can happen like this< / li >
1999-02-25 20:43:02 +03:00
< br > < tt > nsIRepository::CreateInstance(< b > "< font color = "#CC0000" > component://netscape/network-protocol& type=nfs< / font > "< / b > ,
NULL, kProtocolIID, & result);< / tt >
1999-02-02 01:17:58 +03:00
< br > instead of
1999-02-25 20:43:02 +03:00
< br > < strike > nsIRepository::CreateInstance(NFS_PROTOCOL_CID, NULL, domIID,
& result);< / strike > < / blockquote >
< h3 >
< a NAME = "What has happened so far" > < / a > What has happened so far< / h3 >
< ul >
< li >
Autoregistration implemented to grovel for components from the current
directory< / li >
< li >
nsRepository is a global object. Not nsIRepository exists.< / li >
< li >
nsRepository::ProgIDToCLSID() implemented< / li >
< / ul >
1999-02-24 23:24:27 +03:00
< h3 >
1999-02-25 20:43:02 +03:00
< a NAME = "Changes to XPCOM happening" > < / a > Changes to XPCOM happening< / h3 >
< ul >
< li >
API changes to get ProgID in entire registration process for factories
and components< / li >
< li >
ProgID cache to improve performance of ProgID queries< / li >
< li >
Notion of Component dlls living in a < b > Components directory < / b > and autoregistration
will load/manage only these components. Other components that are linked
in to the app need to call < tt > nsRepository::RegisterFactory()< / tt > from
1999-02-25 21:11:58 +03:00
the app. < b > To make this happen we need a list of these.< / b > < / li >
1999-02-25 20:43:02 +03:00
< li >
< b > nsRegistry:< / b > Enabling the new nsRegistry developed by Bill Law < law@netscape.com>< / li >
< li >
Service Manager and Repository: Merge them< / li >
< li >
Convenience function to createIntance(progid)< / li >
< li >
1999-02-25 21:11:58 +03:00
Base ProgID in the interface ID header file< / li >
1999-02-25 20:43:02 +03:00
< / ul >
< h3 >
< a NAME = "What should I do" > < / a > What should I do< / h3 >
< ul > < b > < font color = "#CC0000" > Component Developers< / font > < / b >
< ul >
< li >
< font color = "#000000" > Implement < tt > NSRegisterSelf()< / tt > for your component
dlls. Sample implementation that perf< / font > < a href = "http://cvs-mirror.mozilla.org/webtools/lxr/source/modules/libpref/src/nsPref.cpp#608" > http://cvs-mirror.mozilla.org/webtools/lxr/source/modules/libpref/src/nsPref.cpp#608< / a > < / li >
< li >
Use < tt > nsRepository::RegisterComponent()< / tt > instead of < tt > nsRepository::RegisterFactory()< / tt >
if your component lives in a DLL< / li >
< li >
< b > Dont use static constructors in loadable components< / b > < / li >
< / ul >
< p > < br > < b > < font color = "#CC0000" > Component Users< / font > < / b >
< ul >
< li >
Create all your components using ProgID rather than CID< / li >
< li >
If you were thinking of managing creation of components yourself, think
again. The repository may be already doing that.< / li >
< / ul >
< / ul >
< h3 >
< a NAME = "Issues" > < / a > Issues< / h3 >
1999-02-02 01:17:58 +03:00
< ul >
< li >
Need support for questions like:< / li >
< ol >
< li >
Enumerate all CLSIDs that implement a particular interface.< / li >
< li >
1999-02-03 09:58:44 +03:00
Let a particular CLSID be the preferable implementation for an interface.< / li >
1999-02-02 01:17:58 +03:00
1999-02-03 09:58:44 +03:00
< br > I dont know how this a XPCOM component user could use it unless there
could be a call like:
< br > < tt > nsIRepository::CreateInstance(< b > NULL< / b > , NULL, nsWidgetIID, & result);< / tt >
1999-02-02 01:17:58 +03:00
< li >
Enumerate all interfaces supported by a CLSID< / li >
< / ol >
< li >
Resolving naming conflicts between ProgID< / li >
< li >
Store component specific name-values under < tt > ROOTKEY_COMMON\\< i > component.class.version\\< / i > < / tt > < / li >
< li >
1999-02-03 09:58:44 +03:00
Add a registry entry under < tt > ROOTKEY_COMMON\\< i > component.class.version\\< / i > < / tt > to
indicate the willingness for a CLSID to behave as a Service.< / li >
1999-02-02 01:17:58 +03:00
< li >
Add quick registration support functions in < tt > nsIRepository< / tt > for
components to use.< / li >
< li >
Is the hierarchy < tt > ROOTKEY_COMMON\\< b > Classes< / b > \\CLSID < / tt > acceptable.< / li >
1999-02-25 20:43:02 +03:00
< li >
1999-02-25 21:11:58 +03:00
Should we have a nsIRepository. JS needs it so that they can reflect it
in javascript. Remove & 's in the API.< / li >
1999-02-02 01:17:58 +03:00
< / ul >
< hr WIDTH = "100%" >
1999-02-25 20:43:02 +03:00
< br > < i > < font size = -1 > Last Modified: 28 Jan 1998< / font > < / i >
1999-02-02 01:17:58 +03:00
< br > < font size = -1 > < i > Feedback to: < / i > < a href = "news:netscape.public.mozilla.xpcom" > netscape.public.mozilla.xpcom< / a > < / font >
< / body >
< / html >
