Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2025-03-02 14:30:43 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

progid spec added

Browse Source
This commit is contained in:
dp%netscape.com 1999-04-02 21:43:54 +00:00
parent 411d290d04
commit b8b63c3378
2 changed files with 126 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
xpcom/doc/xpcom-code-faq.html
View File

@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.51 [en] (WinNT; U) [Netscape]">
<meta name="GENERATOR" content="Mozilla/4.51 [en] (X11; U; Linux 2.0.36 i686) [Netscape]">
<meta name="Author" content="Suresh Duddi">
<title>XPCOM Code FAQ</title>
</head>
@ -11,25 +11,64 @@
<h2>
XPCOM Code FAQ</h2>
Suresh Duddi &lt;<a href="mailto:dp@netscape.com">dp@netscape.com</a>>
<br>Last Modified: March 22 1999
<br>Last Modified: April 2 1999
<br>
<hr WIDTH="100%">
<br>I am documenting things randomly as I am replying to people's questions.
So this might look more like an FAQ.
So this looks more like an FAQ.
<h3>
Table of Contents</h3>
<ol>
<li>
<a href="#What are the Global Objects that XPCOM maintains">What are the
Global Objects that XPCOM maintains</a></li>
<li>
<a href="#What are the static classes that XPCOM maintains">What are the
static classes that XPCOM maintains</a></li>
<li>
<a href="#Is there any restriction on which static class I should call fi">Is
there any restriction on which static class I should call first</a></li>
<li>
<a href="#What is the order of creation of the ServiceManager, ComponentM">What
is the order of creation of the ServiceManager, ComponentManager and Registry</a></li>
<li>
<a href="#Is there a global Registry being maintained">Is there a global
Registry being maintained</a></li>
<li>
<font color="#000000"><a href="#ComponentManager Vs ServiceManager">ComponentManager
Vs ServiceManager</a></font></li>
<li>
<a href="#ProgID Vs CLSID">ProgID Vs CLSID</a></li>
<li>
<a href="#How to debug components ?">How to debug components ?</a></li>
</ol>
<hr WIDTH="100%">
<h4>
What are the Global Objects that XPCOM maintains</h4>
<a NAME="What are the Global Objects that XPCOM maintains"></a>What are
the Global Objects that XPCOM maintains</h4>
<ul>mGlobalServiceManager
<br>mGlobalComponentManager</ul>
<h4>
What are the static classes that XPCOM maintains</h4>
<a NAME="What are the static classes that XPCOM maintains"></a>What are
the static classes that XPCOM maintains</h4>
<blockquote>nsComponentManager
<br>nsServiceManager</blockquote>
<h4>
Is there any restriction on which static class I should call first</h4>
<a NAME="Is there any restriction on which static class I should call fi"></a>Is
there any restriction on which static class I should call first</h4>
<blockquote>No restrictions. You can call any function from the static
classes nsComponentManager and nsServiceManager. XPCOM will do the right
@ -40,8 +79,8 @@ it is only in Init_XPCOM() do we create register the RegistryFactory()
with the ComponentManager.</blockquote>
<h4>
What is the order of creation of the ServiceManager, ComponentManager and
Registry</h4>
<a NAME="What is the order of creation of the ServiceManager, ComponentM"></a>What
is the order of creation of the ServiceManager, ComponentManager and Registry</h4>
<blockquote>Init_XPCOM()
<blockquote>
@ -67,7 +106,8 @@ from both NS_GetGlobalComponentManager() and NS_GetGlobalServiceManager()
we will be safe.</blockquote>
<h4>
Is there a global Registry being maintained</h4>
<a NAME="Is there a global Registry being maintained"></a>Is there a global
Registry being maintained</h4>
<blockquote>No. The nsIRegistry is designed to be lightweight access to
the registry. Consumers who need to access the registry should use the
@ -79,7 +119,8 @@ is going to be a major headach.
<br>&nbsp;</blockquote>
<h4>
<font color="#000000">ComponentManager Vs ServiceManager</font></h4>
<a NAME="ComponentManager Vs ServiceManager"></a><font color="#000000">ComponentManager
Vs ServiceManager</font></h4>
<blockquote><font color="#000000">ComponentManager is the only way for
component creation. ComponentManager always uses the component's factory
@ -95,36 +136,42 @@ to exist. Hence the notion of getting a service not creating one. (as opposed
to the notion of Creating instances with the componentManager). ServiceManager
is a convenience because components can technically force singletonism
by making their factory return the same instance if one was created already.
The other big use of ServiceManager is the (still unimplemented) notion
of Shutting down a service.</font>
The
other big use of ServiceManager is the (still unimplemented) notion of
Shutting down a service.</font>
<p><b><i><font color="#000000">Client</font></i></b>
<ul>
<li>
<i><font color="#000000">When does a client use the service manager vs
component manager</font></i></li>
<p><br><font color="#000000">When a client knows that the component that
they are trying to instantiate is a singleton, they need to call service
manager instead of component manager. Clients dont have to worry about
calling the ComponentManager at all in this case. The ServiceManager will
take care of creating the instance if the first one doesn't exist already.</font>
<br>&nbsp;
<p>&nbsp;
<p><font color="#000000">When a client knows that the component that they
are trying to instantiate is a singleton, they need to call service manager
instead of component manager. Clients dont have to worry about calling
the ComponentManager at all in this case. The ServiceManager will take
care of creating the instance if the first one doesn't exist already.</font>
<br><font color="#000000">-</font>
<li>
<i><font color="#000000">When does a client use the Component Manager as
opposed to Service Manager</font></i></li>
<p><br><font color="#000000">When a client wants a private instance of
a component, they call the Component Manager. From the Clients point of
view, a new xpcom object creation happens everytime they call CreateInstance()
Anything else is an implementation detail that the Client need not worry
about.</font>
<br>&nbsp;
<p>&nbsp;
<p><font color="#000000">When a client wants a private instance of a component,
they call the Component Manager. From the Clients point of view, a new
xpcom object creation happens everytime they call CreateInstance() Anything
else is an implementation detail that the Client need not worry about.</font>
<br><font color="#000000">-</font>
<li>
<i><font color="#000000">How does a Client know that they have to instantiate
a singleton</font></i></li>
<p><br><font color="#000000">For now, the Client just has to know. There
is no way of telling which component is a Service and which isn't. In fact,
<br>&nbsp;
<p>&nbsp;
<p><font color="#000000">For now, the Client just has to know. There is
no way of telling which component is a Service and which isn't. In fact,
in todays xpcom (Mar 1999) any component can be accessed as a Service.
Use your judgement until there is a proper method or service manager is
eliminated. There is nothing even in the code that detects Services from
@ -138,7 +185,9 @@ dp@netscape.com</a></font></b>
<li>
<i><font color="#000000">Can a component enforce use only as a Service</font></i></li>
<p><br><font color="#000000">No. The notion of the ServiceManager is available
<br>&nbsp;
<p>&nbsp;
<p><font color="#000000">No. The notion of the ServiceManager is available
only to Clients.</font>
<p><font color="#000000">Note that at some points when a component wants
another component, it actually behaves as a client and hence follows the
@ -164,26 +213,30 @@ the same object will be returned hence guaranteeing singletonism.</ul>
<i><font color="#000000">Should a component do anything at creation to
become a Service</font></i></li>
<p><br><font color="#000000">No. Again, the notion of a ServiceManager
is available only to Clients.</font>
<br>&nbsp;
<p>&nbsp;
<p><font color="#000000">No. Again, the notion of a ServiceManager is available
only to Clients.</font>
<br><font color="#000000">-</font>
<li>
<i><font color="#000000">Can a component advertise that it is a service
so clients can use it as one</font></i></li>
<p><br>No. There isn't a way other than a comment in the interface of the
header file.</ul>
<br>&nbsp;
<p>&nbsp;
<p>No. There isn't a way other than a comment in the interface of the header
file.</ul>
</blockquote>
<h4>
ProgID Vs CLSID</h4>
<a NAME="ProgID Vs CLSID"></a>ProgID Vs CLSID</h4>
<blockquote>ClassID or CLSID is the unique indentification of a component.
It is a structure of huge numbers generated by using uuidgen on a windows
box. It is represented as a string in documentation as {108d75a0-bab5-11d2-96c4-0060b0fb9956}
<p>ProgID is the string identification of an implementation of a component
the client is looking for. The representation takes a URI syntax. Eg. component://netscape/network/protocol&amp;name=http
Some simplify this to, ProgID is a more readable string form of a CLSID.
the client is looking for. The representation takes a URI syntax. Eg. <i>component://netscape/network/protocol?name=http;description=Http%20Protocol%20Handler</i>
<br>Some simplify this to, ProgID is a more readable string form of a CLSID.
That is acceptable on the periphery. The ProgID is a Client thing. Components
register with component manager to claim that they are the implementation
for a ProgID. A component can register to be the implementation for multiple
@ -191,23 +244,42 @@ ProgIDs (not implemented yet).
<p><b><i>Client</i></b>
<ul>
<li>
<i>Should CreateInstance() calls use ProgID or CLSID<br>
&nbsp;&nbsp;<br>
</i>ProgID is what Clients should use to CreateInstances. Clients should
<i>Should CreateInstance() calls use ProgID or CLSID</i></li>
<p><br>ProgID is what Clients should use to CreateInstances. Clients should
not even know about the CLSID unless they are hell bent on creating a particular
implementation of a component.<br>
-</li>
</ul>
implementation of a component.
<br>-</ul>
<b><i>Component</i></b>
<ul>
<li>
<i>Should Components register with both a CID and ProgID<br>
<br>
</i>Absolutely.</li>
</ul>
<i>Should Components register with both a CID and ProgID</i></li>
<br>&nbsp;
<p><br>Absolutely.</ul>
</blockquote>
<h4>
<a NAME="How to debug components ?"></a>How to debug components ?</h4>
<blockquote>Since components are dynamically loaded only on demand, debugging
them could be a hard. Here are some tips to debugging components.
<p><b><i>Windows:&nbsp;VC5.0 VC6.0</i></b>
<ul>Include your component library in the Project->Settings, Additional
Dll. drop down. After that breakpoints can be enabled.
<br>&nbsp;</ul>
<b><i>Unix: gdb</i></b>
<blockquote>Let the program run until you are sure that your component
is loaded. Type Control-C. Now all symbols from your component will be
available in gdb. Put your breakpoints and restart the app. Gdb will complain
that it cannot set the breakpoint, and that it is temporarily disabling
it, but when the *.so is loaded, the breakpoint is enabled automatically.
- &lt;<a href="erik@netscape.com">Eric Van Der Poel</a>>
<br>&nbsp;</blockquote>
<b><i>Mac:&nbsp;Codewarrior</i></b>
<blockquote>Just open the appropriate .xSYM file in the debugger; the debugger
will target the library when the application is run. - &lt;<a href="sfraser@netscape.com">Simon
Fraser</a>></blockquote>
</blockquote>
<hr WIDTH="100%">
</body>

21
xpcom/doc/xpcom-component-registration.html
View File

@ -151,7 +151,8 @@ do to salvage this situation other than warning the user of possible instability
and advice a restart upon which the re-registration will happen.
<h3>
<a NAME="ProgID Spec"></a>ProgID Spec</h3>
Let us consider some more examples:
The general format of ProgIDs is <i><font color="#990000">component://</font>netscape<font color="#990000">/</font>compname<font color="#990000">?</font>var<font color="#990000">=</font>value<font color="#990000">;</font>var<font color="#990000">=</font>value<font color="#990000">;</font>var<font color="#990000">=</font>value...</i><i></i>
<p>Let us consider some more examples:
<ol>
<li>
A pluggable protocol that implementes the nfs protocol</li>
@ -176,31 +177,31 @@ they particularly do.
<p>The ProgID for these would look like
<ol>
<li>
<tt>component://netscape/network-protocol&amp;type=nfs</tt></li>
<tt>component://netscape/network-protocol?type=nfs</tt></li>
<li>
<tt>component://netscape/data-converter&amp;type=application/x-zip</tt></li>
<tt>component://netscape/data-converter?type=application/x-zip</tt></li>
<li>
<tt>component://netscape/plugin&amp;type=image/gif&amp;name=ImageMedia's
Gif Image Plugin&amp;Description=Reders GIF Images....</tt></li>
<tt>component://netscape/plugin?type=image/gif;name=ImageMedia Gif Image
Plugin;Description=Reders GIF Images....</tt></li>
<li>
<tt>component://netscape/widget&amp;type=toolbar</tt></li>
<tt>component://netscape/widget?type=toolbar</tt></li>
<li>
<tt>component://netscape/rdf/datsource&amp;type=mail</tt></li>
<tt>component://netscape/rdf/datsource?type=mail</tt></li>
<li>
<tt>component://netscape/helperapp&amp;type=application/postscript</tt></li>
<tt>component://netscape/helperapp?type=application/postscript</tt></li>
</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
<br>component://netscape/plugin&amp;type=image/gif should pass for the
progid specified above. We could extend this
<br>component://netscape/plugin?type=image/gif should pass for the progid
specified above. We could extend this
<br>mechanism with wildcards, but I dont want to go there yet... :-)
<br>&nbsp;
<h3>