nf-objbase-cotreatasclass.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:objbase.CoTreatAsClass	CoTreatAsClass function (objbase.h)	Establishes or removes an emulation, in which objects of one class are treated as objects of a different class.	CoTreatAsClass CoTreatAsClass function [COM] _com_CoTreatAsClass com.cotreatasclass objbase/CoTreatAsClass	com\cotreatasclass.htm	com	d871879f-ec68-48e1-8ef6-364cf1447d0f	12/05/2018	CoTreatAsClass, CoTreatAsClass function [COM], _com_CoTreatAsClass, com.cotreatasclass, objbase/CoTreatAsClass	objbase.h		Windows	Windows 2000 Professional [desktop apps only]	Windows 2000 Server [desktop apps only]										Ole32.lib	Ole32.dll		Windows			19H1	CoTreatAsClass objbase/CoTreatAsClass	c++	APIRef kbSyntax	DllExport	Ole32.dll	CoTreatAsClass

CoTreatAsClass function

-description

Establishes or removes an emulation, in which objects of one class are treated as objects of a different class.

-parameters

-param clsidOld [in]

The CLSID of the object to be emulated.

-param clsidNew [in]

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.

-returns

This function can return the standard return values E_INVALIDARG, as well as the following values.

Return code	Description
S_OK	The emulation was successfully established or removed.
REGDB_E_CLASSNOTREG	The clsidOld parameter is not properly registered in the registration database.
REGDB_E_READREGDB	Error reading from registration database.
REGDB_E_WRITEREGDB	Error writing to registration database.

-remarks

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 first case is that an end user might wish to edit a spreadsheet created by one application using a different application that can read and write the spreadsheet format of the original application. For an application that supports emulation, CoTreatAsClass can be called to implement a Treat As option in a conversion dialog box.

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.

-see-also

CoGetTreatAsClass