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, IStream::Read, and IStream::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.
See Also