SetConvertStg

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, 
                 //Points to storage object where the conversion bit 
                 // is to be set
  BOOL fConvert  //Indicates whether an object is to be converted
);
 

Parameters

pStg

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

fConvert

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 Values

S_OK

Indicates the object's conversion bit was set successfully.

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

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

E_OUTOFMEMORY

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

E_INVALIDARG

Indicates one or more arguments are invalid.

E_UNEXPECTED

Indicates an unexpected error occurred.

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

Remarks

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 dialogue (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 WriteFmtUserType() 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.

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

GetConvertStg