OleSetAutoConvert

Specifies a CLSID for automatic conversion to a different class when an object of that class is loaded.

WINOLEAPI OleSetAutoConvert(
  REFCLSID clsidOld, //CLSID to be converted
  REFCLSID clsidNew  //New CLSID after conversion
);
 

Parameters

clsidOld

[in] CLSID of the object class to be converted.

clsidNew

[in] CLSID of the object class that should replace clsidOld. This new CLSID replaces any existing auto-conversion information in the registry for clsidOld. If this value is CLSID_NULL, any existing auto-conversion information for clsidOld is removed from the registry.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK

The object was tagged successfully.

REGDB_E_CLASSNOTREG

The CLSID is not properly registered in the registry.

REGDB_E_READREGDB

Error reading from the registry.

REGDB_E_WRITEREGDB

Error writing to the registry.

REGDB_E_KEYMISSING

Cannot read a key from the registry.

Remarks

The OleSetAutoConvert function goes to the system registry, finds the AutoConvertTo subkey under the CLSID specified by clsidOld, and sets it to clsidNew. This function does not validate whether an appropriate registry entry for clsidNew currently exists. These entries appear in the registry as subkeys of the CLSID key:

CLSID\{clsid}=MainUserTypeName\AutoConvertTo = clsid 
 

Object conversion means that the object's data is permanently associated with a new CLSID. Automatic conversion is typically specified in the setup program of a new version of an object application, so objects created by its older versions can be automatically updated to the new version.

For example, it may be necessary to convert spreadsheets that were created with earlier versions of a spreadsheet application to the new version. The spreadsheet objects from earlier versions have different CLSIDs than the new version. For each earlier version that you want automatically updated, you would call OleSetAutoConvert in the setup program, specifying the CLSID of the old version, and that of the new one. Then, whenever a user loads an object from a previous version, it would be automatically updated. To support automatic conversion of obects, a server that supports conversion must be prepared to manually convert objects that have the format of an earlier version of the server. Automatic conversion relies internally on this manual-conversion support.

Before setting the desired AutoConvertTo value, setup programs should also call OleSetAutoConvert to remove any existing conversion for the new class, by specifying the new class as the clsidOld parameter, and setting the clsidNew parameter to CLSID_NULL.

QuickInfo

  Windows NT: Use version 3.1 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in ole2.h.
  Import Library: Included as a resource in ole32.dll.

See Also

OleDoAutoConvert