Important: |
---|
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This method initializes a new object, providing a pointer to the storage to be used for the object.
Syntax
HRESULT InitNew( IStorage* pStg ); |
Parameters
- pStg
-
[in] IStoragepointer to the new storage object to be initialized.
The container creates a nested storage object in its storage object (see IStorage::CreateStorage). Then, the container calls the WriteClassStgfunction to initialize the new storage object with the object class identifier (CLSID).
Return Value
The following table shows the return values for this method.
Value | Description |
---|---|
S_OK |
The new storage object was successfully initialized. |
CO_E_ALREADYINITIALIZED |
The object has already been initialized by a previous call to either the IPersistStorage::Loadmethod or the IPersistStorage::InitNewmethod. |
E_OUTOFMEMORY |
The storage object was not initialized due to a lack of memory. |
E_FAIL |
The storage object was not initialized for some reason other than a lack of memory. |
Remarks
A container application can call this method when it needs to initialize a new object, for example, with an InsertObject command.
An object that supports the IPersistStorageinterface must have access to a valid storage object 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 a valid IStoragepointer to the storage during this time through the call to IPersistStorage::InitNew.
Depending on the container's state, a temporary file might have to be created for this purpose.
If the object wants to retain the IStorageinstance, it must call the IUnknown::AddRefmethod to increment its reference count.
After the call to IPersistStorage::InitNew, the 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 to InitNewonly invokes the handler's implementation, which does not run the object.
Later, if the container runs the object, the handler calls the IPersistStorage::InitNewmethod for the object.
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Notes to Callers
Rather than calling IPersistStorage::InitNewdirectly, you typically call the OleCreatehelper function that does the following:
- Calls the
CoCreateInstancefunction to create an instance of the object
class
- Queries the new instance for the
IPersistStorageinterface
- Calls the
IPersistStorage::InitNewmethod to initialize the object
The container application should cache the IPersistStoragepointer to the object for use in later operations on the object.
Notes to Implementers
An implementation of IPersistStorage::InitNewshould initialize the object to its default state, taking the following steps:
- Pre-open and cache the pointers to any streams or storages that
the object will need to save itself to this storage.
- Call
IPersistStorage::AddRefand cache the storage pointer that is
passed in.
- Call the
WriteFmtUserTypeStgfunction to write the native clipboard
format and user type string for the object to the storage object.
- Set the dirty flag for the object.
The first two steps are particularly important for ensuring that the object can save itself in low memory situations. Pre-opening and holding onto pointers to the stream and storage interfaces 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::InitNewmethod or the IPersistStorage::Loadmethod after it is already initialized.
Requirements
Header | objidl.h, objidl.idl |
Library | ole32.lib, uuid.lib |
Windows Embedded CE | Windows CE 2.0 and later |
Windows Mobile | Windows Mobile Version 5.0 and later |