SetConvertStg function

The SetConvertStg function sets the convert bit in a storage object to indicate that the object is to be converted to a new class when it is opened. The setting can be retrieved with a call to the GetConvertStg function.


WINOLEAPI SetConvertStg(
   IStorage *pStg,
   BOOL     fConvert



IStorage pointer to the storage object in which to set the conversion bit.


If TRUE, sets the conversion bit for the object to indicate the object is to be converted when opened. If FALSE, clears the conversion bit.

Return value


Indicates that the object's conversion bit was set successfully.


Access denied because the caller does not have enough permissions, or another caller has the file open and locked.


Access denied because another caller has the file open and locked.


Indicates that the conversion bit was not set due to a lack of memory.


Indicates that one or more arguments are not valid.


Indicates that an unexpected error occurred.

See the IStorage::CreateStream, IStorage::OpenStream, ISequentialStream::Read, and ISequentialStream::Write methods for possible storage and stream access errors.


The SetConvertStg function determines the status of the convert bit in a contained object. It is called by both the container application and the server in the process of converting an object from one class to another. When a user specifies through a Convert To dialog (which the container produces with a call to the OleUIConvert function) that an object is to be converted, the container must take the following steps:

  1. Unload the object if it is currently loaded.
  2. Call WriteClassStg to write the new CLSID to the object storage.
  3. Call WriteFmtUserTypeStg to write the new user-type name and the existing main format to the storage.
  4. Call SetConvertStg with the fConvert parameter set to TRUE to indicate that the object has been tagged for conversion to a new class the next time it is loaded.
  5. Just before the object is loaded, call OleDoAutoConvert to handle any needed object conversion, unless you call OleLoad, which calls it internally.

When an object is initialized from a storage object and the server is the destination of a convert-to operation, the object server should do the following:

  1. Call the GetConvertStg function to retrieve the value of the conversion bit.
  2. If the bit is set, the server reads the data out of the object according to the format associated with the new CLSID.
  3. When the object is asked to save itself, the object should call the WriteFmtUserTypeStg function using the normal native format and user type of the object.
  4. The object should then call SetConvertStg with the fConvert parameter set to FALSE to reset the object's conversion bit.


Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]







See also




Community Additions