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 pair, in this case . - 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