Initializes a new storage object.
| IStorage *pStg
||//Points to the new storage object
[in]Points to the new storage object to initialize and use. The container
creates a nested storage object in its storage object (see IStorage::CreateStorage
). Then, the container calls the WriteClassStg
function to initialize the new storage object with the component object class
The new storage object was successfully initialized.
The component object has already been initialized by a previous call to either
method or the IPersistStorage::InitNew
The storage object was not initialized due to a lack of memory.
The storage object was not initialized due to some reason besides a lack of
A container application can call this method when it needs to create a new
object, for example, with an InsertObject command.
An object that uses the IPersistStorage
interface must have access to a valid IStorage
instance at all times while it is running. This includes the time just after
the object has been created but before it has been made persistent. The
object's container must provide the object with access to an IStorage
instance during this time by calling IPersistStorage::InitNew
. Depending on the container's state, a temporary file might need to be
created for this purpose.
If the object wants to retain the IStorage
instance, it must call IUnknown::AddRef
to increment its reference count.
After the call to IPersistStorage::InitNew
, the component object is in either the loaded or running state. For example,
if the object class has an in-process server, the object will be in the running
state. However, if the object uses the default handler, the container's call
only invokes the handler's implementation which does not run the component
object. Later if the container runs the component object, the handler calls the IPersistStorage::InitNew
method for the object.
Notes to Callers
Rather than calling IPersistStorage::InitNew
directly, you typically call the OleCreate
helper function which performs the following steps:
- Calls the CoCreateInstance function to create an instance of the object class
- Queries the new instance for the IPersistStorage interface
- Calls the IPersistStorage::InitNew method to initialize the component object
The container application should cache the PersistStorage
interface for the object for use in later operations on the object.
Notes to Implementors
An implementation of IPersistStorage::InitNew
should initialize the component object to its default state. In particular,
your implementation should perform the following steps to initialize the storage
- Pre-open and cache the pointers to any streams or storages that the component
will need to save itself to this storage.
- Call IPersistStorage::AddRef and cache the passed in storage pointer.
- Call the WriteFmtUserTypeStg function to write the native clipboard format and user type string for the
component object to the storage object.
- Set the dirty flag for the component object.
The first two steps are particularly important for ensuring that the component
object can save itself in low memory situations. By pre-opening the necessary
streams, the component object can guarantee that a save operation to this
storage object 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.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages