IPersistStorage::Load

Initializes an object from its existing storage.

HRESULT Load(

IStorage *pStg
//Pointer to existing storage object for the component object
);

Parameter

pStg

[in]Points to the existing storage object from which the component object is to be loaded.

Return Values

S_OK

The object was successfully loaded.

CO_E_ALREADYINITIALIZED

The object has already been initialized by a previous call to the IPersistStorage::Load method or the IPersistStorage::InitNew method.

E_OUTOFMEMORY

The object was not loaded due to lack of memory.

E_FAIL

The object was not loaded due to some reason besides a lack of memory.

Comments

This method initializes a component object from an existing storage object. The component object is placed in the loaded state if this method is called by the container application. If called by the default handler, this method places the component object in the running state.

Either the default handler or the component object itself can hold onto the IStorage interface while the object is loaded or running.

Notes to Callers

Rather than calling IPersistStorage::Load directly, you typically call the OleLoad helper function which performs the following steps:

  1. Create an uninitialized instance of the component object class

  2. Query the new instance for the IPersistStorage interface

  3. Call the IPersistStorage::Load method to initialize the component from the existing storage

You also call this method indirectly when you call the OleCreateFromData function or the OleCreateFromFile function to insert a component object into a compound file (as in a drag-and-drop or clipboard paste operation).

The container should cache the IPersistStorage interface for use in later operations on the component object.

Notes to Implementors

Your implementation should perform the following steps to load a component object:

  1. Open the component object's streams in the storage object, and read the necessary data into the object's internal data structures.

  2. Clear the component object's dirty flag.

  3. Call the IPersistStorage::AddRef method and cache the passed in storage pointer.

  4. Keep open and cache the pointers to any streams or storages that the component object will need to save itself to this storage.

  5. Perform any other default initialization required for the component object.

Steps 3 and 4 are particularly important for ensuring that the component can save itself in low memory situations. By holding onto pointers to the storage and streams, the component can guarantee that a save operation to this storage will not fail due to insufficient memory.

Your implementation of this method should return the CO_E_ALREADYINITIALIZED error code if it receives a call to either the IPersistStorage::InitNew method or the IPersistStorage::Load method after it is already initialized.

See Also

GetConvertStg, IPersistStorage::InitNew, OleLoad, ReadFmtUserTypeStg, SetConvertStg, WriteFmtUserTypeStg

Software for developers
Delphi Components
.Net Components
Software for Android Developers
More information resources
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
Databases for Amazon shops developers
Amazon Categories Database
Browse Nodes Database