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.
Syntax
WINOLEAPI SetConvertStg( IStorage *pStg, BOOL fConvert );
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 value
- S_OK
-
Indicates that the object's conversion bit was set successfully.
- STG_E_ACCESSDENIED
-
Access denied because the caller does not have enough permissions, 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 that the conversion bit was not set due to a lack of memory.
- E_INVALIDARG
-
Indicates that one or more arguments are not valid.
- E_UNEXPECTED
-
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.
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 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:
- Unload the object if it is currently loaded.
- Call WriteClassStg to write the new CLSID to the object storage.
- Call WriteFmtUserTypeStg to write the new user-type name and the existing main format to the storage.
- 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.
- 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:
- Call the GetConvertStg function to retrieve the value of the conversion bit.
- If the bit is set, the server reads the data out of the object according to the format associated with the new CLSID.
- 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.
- The object should then call SetConvertStg with the fConvert parameter set to FALSE to reset the object's conversion bit.
Requirements
|
Minimum supported client |
Windows 2000 Professional [desktop apps only] |
|---|---|
|
Minimum supported server |
Windows 2000 Server [desktop apps only] |
|
Header |
|
|
Library |
|
|
DLL |
|
See also