Export (0) Print
Expand All

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:

  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.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Ole2.h

Library

Ole32.lib

DLL

Ole32.dll

See also

GetConvertStg

 

 

Community Additions

ADD
Show:
© 2014 Microsoft