Establishes or removes an emulation, in which objects of one class are treated as objects of a different class.
HRESULT CoTreatAsClass( REFCLSID clsidOld, REFCLSID clsidNew );
The CLSID of the object to be emulated.
The CLSID of the object that should emulate the original object. This replaces any existing emulation for clsidOld. This parameter can be CLSID_NULL, in which case any existing emulation for clsidOld is removed.
This function can return the standard return values E_INVALIDARG, as well as the following values.
||The emulation was successfully established or removed.|
||The clsidOld parameter is not properly registered in the registration database.|
||Error reading from registration database.|
||Error writing to registration database.|
This function sets the TreatAs entry in the registry for the specified object, allowing the object to be emulated by another application. Emulation allows an application to open and edit an object of a different format, while retaining the original format of the object. After this entry is set, whenever any function such as CoGetClassObject specifies the object's original CLSID (clsidOld), it is transparently forwarded to the new CLSID (clsidNew), thus launching the application associated with the TreatAs CLSID. When the object is saved, it can be saved in its native format, which may result in loss of edits not supported by the original format.
If your application supports emulation, call CoTreatAsClass in the following situations:
- In response to an end-user request (through a conversion dialog box) that a specified object be treated as an object of a different class (an object created under one application be run under another application, while retaining the original format information).
- In a setup program, to register that one class of objects be treated as objects of a different class.
An example of the use of CoTreatAsClass in a setup program would be in an updated version of an application. When the application is updated, the objects created with the earlier version can be activated and treated as objects of the new version, while retaining the previous format information. This would allow you to give the user the option to convert when they save, or to save it in the previous format, possibly losing format information not available in the older version.
One result of setting an emulation is that when you enumerate verbs, as in the IOleObject::EnumVerbs method implementation in the default handler, this would enumerate the verbs from clsidNew instead of clsidOld.
To ensure that existing emulation information is removed when you install an application, your setup programs should call CoTreatAsClass, setting the clsidNew parameter to CLSID_NULL to remove any existing emulation for the classes they install.
If there is no CLSID assigned to the AutoTreatAs key in the registry, setting clsidNew and clsidOld to the same value removes the TreatAs entry, so there is no emulation. If there is a CLSID assigned to the AutoTreatAs key, that CLSID is assigned to the TreatAs key.
CoTreatAsClass does not validate whether an appropriate registry entry for clsidNew currently exists.
|Minimum supported client||Windows 2000 Professional [desktop apps only]|
|Minimum supported server||Windows 2000 Server [desktop apps only]|