diff --git a/xpcom/doc/nsIClassInfo-overview.html b/xpcom/doc/nsIClassInfo-overview.html new file mode 100644 index 00000000000..20e2199060e --- /dev/null +++ b/xpcom/doc/nsIClassInfo-overview.html @@ -0,0 +1,150 @@ + + + + + + nsIClassInfo Overview + + + + + + + + +

nsIClassInfo Overview

+ Mike Shaver <shaver@mozilla.org + >
+ Last Modified: March 7, 2001
+
+

Table of Contents

+ +
+

What is nsIClassInfo?

+

+ nsIClassInfo is an interface that provides information about + a specific implementation class, to wit:

+ +

How do I use it?

+

To get the nsIClassInfo object for the implementation behind + a given interface, simply QueryInterface for the nsIClassInfo + interface:

+
C++:
+ nsCOMPtr<nsIClassInfo> info = do_QueryInterface(ifacePtr);
+
+ JavaScript:
+ var info = ifacePtr.QueryInterface(Components.interfaces.nsIClassInfo);
+

It's important to note that this will usually return a singleton + object: there often exists only one nsIClassInfo implementation for all + implementations of a given class. This is very important, because it means + that you can't QueryInterface back to the original object, +no matter how hard you try.

+

Doesn't that break the COM + QueryInterface rules?

+

Quite. As discussed in + bug 67699, though, it's a reasonable concession to make in order to +avoid an additional vtbl entry on every class that wants to export + nsIClassInfo data.
+

+

That sounds useful. + How do I make it work with my code?

+

Why, yes, it is useful. To provide nsIClassInfo + data for your class, you need to ensure that it returns an nsIClassInfo + -implementing object when it is QueryInterfaced for +nsIClassInfo . Simple enough, but it can be even simpler through +the use of a handful of helper macros/functions. Choose your own adventure:

+

I'm writing C++ code, + and I use the generic factory and nsModuleComponentInfo.

+

First, make sure that your class has the nsIClassInfo helpers, + by changing the NS_IMPL_ISUPPORTS line:

+
NS_IMPL_ISUPPORTS2(nsSampleImpl, nsISample, nsIOther)
+
+

becomes

+
NS_IMPL_ISUPPORTS2_CI(nsSampleImpl, nsISample, nsIOther)
+
+

This will provide an implementation of a helper function, named + nsSampleImpl_GetInterfacesHelper, which handles the processing + of nsIClassInfo::getInterfaces.

+

Next, in your module code, use NS_DECL_CLASSINFO to + provide the rest of the per-class infrastructure (a global pointer into +which to stash the nsIClassInfo object, and an extern declaration +of the interfaces-helper, in case it's defined in another file):

+
NS_DECL_CLASSINFO(nsSampleImpl)
+
+

You'll need one of these lines for each nsIClassInfo + -supporting class represented in your nsModuleComponentInfo + array.

+

Lastly, fill in the appropriate members of nsModuleComponentInfo + to wire everything up:

+
static nsModuleComponentInfo components[] =
+ {
+   {
+     "Sample Component", NS_SAMPLE_CID, NS_SAMPLE_CONTRACTID, +          
+     nsSampleImplConstructor,
+     nsSampleRegistrationProc,
+     nsSampleUnregistrationProc,
+     nsnull /* no factory destructor */,
+     NS_CI_INTERFACE_GETTER_NAME(nsSampleImpl),  +/* interface getter */
+     nsnull /* no language helper */,
+     &NS_CLASSINFO_NAME(nsSampleImpl),  +/* global class-info pointer */
+     0 /* no class flags */
+   }
+ };
+
+

If you want to add a callback which provides language-helper + objects, replace the last nsnull with your callback. See the + + nsIClassInfo IDL file for details on language helpers and other + esoterica.

+

I'm writing + C++ code, and I use a custom factory or a singleton service object.

+

You need some utility macros, don't ya? We're working on it.

+

I'm writing JS code.

+ You poor thing. You suffer without even a GenericModule helper. We're +working on that, too. +

What's "interface +flattening"?

+

You'd think that you might find an explanation of interface +flattening in + bug 13422 , but you'd be wrong. I'll need to write one here.
+
+

+
+
+
+ +