windows-xp/Source/XPSP1/NT/shell/docs/instid.txt

COM 'Instance's (and explorer band categories)
980305
andyp

WARNING WARNING WARNING -- v. early draft of doc in progress, likely to
have many errors/omissions.

- abstract
...

- contents
...

- overview
COM has a (core!) notion of a CLSID for the code that implements an object
but no similar notion for a particular instance of that object.  thus every
client must write custom code for each instance.

we provide a generalization which makes creation and initialization of such
instances easy and consistent.

- motivation
an e.g. of usage might be a browser band implementation.  the code for
such a band is identical no matter what URL one happens to initialize
it to.  however it is quite useful to be able to install many different
browser bands, each pointing to a different URL, by writing only
registry 'goo' (vs.  writing custom code, however simple it may be,
to do the same thing).

- instance = code + data
an 'INSTID' is a GUID that identifies two things:
    - the CLSID for the code for an object
    - data for an IPersistXxx iface to initialize an instance of the object

- creation
INSTID's are fully hidden from the client.  that is, there is no special
API to create an instance.  one simply does a CoCreateInstance, and if the
CLSID happens to actually be an INSTID, we quietly do everything that is
necessary to create and initialize the instance.

- code
the code for an 'instance' is exactly a CLSID.

- initialization
initialization is done from an IPersistXxx iface.  we try to load 1st from
an IPropertyBag, next from an IPersistStream, and finally from ???

all of these ifaces are created using our various registry-based
implementations.  e.g. CRegStrPropertyBag (IPropertyBag on top of
a registry key), OpenRegStream (IPersistStream on top of a registry
key), etc.

NYI: only IPersistPropertyBag is implemented.  this makes (some) sense,
since we're trying to provide a registry-goo-only method for 'coding',
and a property bag is the main string-based COM IPersistXxx mechanism.

- installation
for convenience, we also provide code to create the registry goo (why?).

CRegStrPropBag *InstallInstAndBag(LPTSTR pszInst, LPTSTR pszName, LPTSTR pszClass)

...

- registry goo
the key looks as follows:
    subkey                              value(s)
    ------                              --------
    HKCR/CLSID/
        {instid}/                       @=...description...
            InProcServer
                                        @=...path...
                                        ThreadingModel=...etc....
            Instance
                                        CLSID={clsid}
                InitPropertyBag
                                        name1=value1
                                        ...

the InProcServer should point to browseui.dll, which is where we've
implemented the generic support code for InstIDs.  (if the idea proves
useful enough, perhaps COM will pick it up as a standard part of the
CoCreateInstance API).

- implementation
here's how it works...

the INSTID points to our DLL which implements inst.cpp.  DllGetClassObject
goes thru its usual loop.  if it fails, it tries to create a
CInstClassFactory for the given CLSID (INSTID).  creation looks for and
caches the magic 'Instance' subkey (and fails if it's not found).  then
when the ::CI method is called it gets the appropriate keys/values, does
the CCI, creates the IPropertyBag (etc.), and does the ::Load.

- perf
from the implementation details, it should be clear that a 'normal'
CCI goes thru exactly the same code path as before.  we intentionally
keep this code path exactly the same cost.

the only time our INSTID code is hit at all is if the vanilla CCI
fails (due to it not being in our sccls.c table).  when that happens,
we look for the 'Instance' subkey.  if that fails, we fail the entire
CCI (w/ the only added cost for that failure case being the 1 extra
RegOpenKey call).  we intentionally keep this code path as close to
0 extra cost as possible.

if that succeeds, we open/read several other keys, do the 'real' CCI,
and do the initialization.  again, the only extra cost (vs. the equivalent
custom code) is the extra registry operations, which we try to keep
cheap.

to keep the extra registry operations cheap we do 'relative' opens
as we work our way down the registry.

BUGBUG what about cost of CInstClassFactory?


- example
to continue w/ our browser band e.g., here's the registry 'goo' for
such a band:
    HKCR/CLSID/
        {77777777-7777-7777-7777-777777777777}
            InProcServer
                                            @="%systemdir%/browseui.dll"
                                            ThreadingModel="Apartment"
            Instance
                                            CLSID=Clsid_BrowserBand
                InitPropertyBag
                                            Url="http://www.nytimes.com"
                                            ... other properties ...

a CCI(7777, ...) will do:
    - create an uninitialized instance of the object by doing
    CCI(Clsid_BrowserBand, ...);
    - create an IPropertyBag for the 'InitPropertyBag' registry data (using
    our CRegStrPropertyBag implementation)
    - call punk->IPB::Load to load the IPropertyBag into the punk
    - we now have an initialized instance of the object (we're done!)

- gotcha's and subtleties

- gotcha: GetCLSID et. al.
while each INSTID is unique and will create a separate instance initialized
w/ the appropriate data, once the object has been created there is no
(standard) way to distinguish it from any other instance of the same class
(code).

e.g. two browsers, one pointing at www.nytimes.com and the other at
www.wsj.com, actually just look like two generic browsers.

thus (e.g.)
    - IPS::GetCLSID gives the same CLSID (not different INSTID!) for both
    of them,
    - OleSaveToStream saves out the same CLSID and the (different) URL's
    - a subsequent OleLoadFromStream will use the same CLSID and the
    (different URL's)

while at 1st this might seem odd, it actually makes a lot of sense.  INSTID's
are just a convenient standard 'packaging' of existing COM mechanisms.
if one does a 'classic' CCI of two CLSID_BrowserBand's, initializes them
to point to two different URLs, saves each w/ OleSaveToStream (presumably
to two different streams), and later reloads each w/ OleLoadFromStream
(again from the different streams), one will get *exactly* the same
behavior as w/ the above INSTID e.g.

in fact doing anything else (e.g. saving the object out w/ its INSTID)
would be wrong (or at least inefficient).  consider: the user may have
changed various properties (e.g. navigated to a new URL).  when we save
it, the object saves the properties that exactly represent its current
state.  but if we create it by INSTID, we'd init it to a *different* set
of properties (which we'd then blast w/ the IPB::Load call).

moreover doing so would be impossible, since neither the object nor the
system even know what the INSTID is once the CCI is complete.

that said, one does need to be a bit careful.

- gotcha: find
the fact that IPS::GetCLSID returns the code CLSID rather than the
object INSTID also complicates uniquely identifying the object in
one's code.  e.g. in our explorer bar implementation, each menu
item has a unique CLSID or INSTID.  the 1st time one clicks on a menu
item, we just call CCI, add the band to the bar, show the band, and
hide all other bands.  so far so good.

but now consider what happens steady-state when one re-clicks on a
previously created menu item.  while the menu item still knows they
have different INSTID's, we have no way to ask the each object (when
enumerating our list of bands) if it came from the INSTID.

to solve this we use IE's Get/PutProperty mechanism to store a
<name,value> pair, in this case <instIdBand,punkBand>.

- gotcha: client dependencies
since we're providing inst.cpp (vs. ole32.dll), the InProcServer for each
INSTID must point to our implementation (ie4:shdocvw, ie5:browseui).

however while the code 'belongs' to us, the INSTIDs in question 'belong'
to the client app.  that is, 3rd-party apps will point *their* INSTIDs at
*our* DLL.  this means that their selfreg.inx will contain knowledge of
where we implement our support routines.

this in turn means that we can't move our implementation (or rather when
we do, we need to somehow forward it so that old code continues to work).

use a treat-as or somesuch so that old code continues to work).

BUGBUG we need to do this for ie5 since we've moved stuff!

- links
docs/inst.txt               this document
browseui/inst.cpp           CCI support code
browseui/stream.cpp         CRegStrPropertyBag

- appendix: 777a.reg
here's the exact registry 'goo'
    #include 777a.reg