Метод IPersistStorage::InitNew (objidl.h)

Статья
08/25/2023

Инициализирует новый объект хранилища.

Синтаксис

HRESULT InitNew(
  [in] IStorage *pStg
);

Параметры

[in] pStg

Указатель IStorage на новый объект хранилища, который необходимо инициализировать. Контейнер создает вложенный объект хранилища в своем объекте хранилища (см. раздел IStorage::CreateStorage). Затем контейнер вызывает функцию WriteClassStg для инициализации нового объекта хранения с помощью идентификатора класса объекта (CLSID).

Возвращаемое значение

Этот метод может возвращать следующие значения.

Код возврата	Описание
S_OK	Метод завершился успешно.
CO_E_ALREADYINITIALIZED	Объект уже инициализирован предыдущим вызовом метода IPersistStorage::Load или метода IPersistStorage::InitNew .
E_OUTOFMEMORY	Объект хранилища не инициализирован из-за нехватки памяти.
E_FAIL	Объект хранилища не был инициализирован по какой-либо причине, кроме нехватки памяти.

Объект, поддерживающий интерфейс IPersistStorage , должен иметь доступ к допустимому объекту хранилища во время его работы. Сюда входит время сразу после создания объекта, но до его сохранения. Контейнер объекта должен предоставить объекту допустимый указатель IStorage на хранилище в течение этого времени через вызов IPersistStorage::InitNew. В зависимости от состояния контейнера для этой цели может потребоваться создать временный файл.

Если объект хочет сохранить экземпляр IStorage , он должен вызвать AddRef , чтобы увеличить количество ссылок.

После вызова IPersistStorage::InitNew объект находится в загруженном или запущенном состоянии. Например, если класс объекта имеет внутрипроцессный сервер, объект будет находиться в состоянии выполнения. Однако если объект использует обработчик по умолчанию, вызов контейнера initNew вызывает только реализацию обработчика, которая не запускает объект. Позже, если контейнер запускает объект , обработчик вызывает метод InitNew для объекта .

Примечания к вызывающим абонентам

Вместо вызова IPersistStorage::InitNew напрямую вызывается вспомогающая функция OleCreate , которая выполняет следующие действия:

Вызывает функцию CoCreateInstance для создания экземпляра класса объекта .
Запрашивает новый экземпляр для интерфейса IPersistStorage .
Вызывает метод InitNew для инициализации объекта .

Приложение-контейнер должно кэшировать указатель IPersistStorage на объект для использования в последующих операциях с объектом .

Примечания для разработчиков

Реализация IPersistStorage::InitNew должна инициализировать объект в состоянии по умолчанию, выполнив следующие действия:

Предварительно откройте и кэшируйте указатели на все потоки или хранилища, которые объекту потребуется сохранить в этом хранилище.
Вызовите AddRef и кэшируйте переданный указатель хранилища.
Вызовите функцию WriteFmtUserTypeStg , чтобы записать собственный формат буфера обмена и строку пользовательского типа для объекта хранилища.
Установите флаг грязное для объекта .

Первые два шага особенно важны для обеспечения того, чтобы объект сохранял себя при нехватке памяти. Предварительное открытие и удержание указателей на интерфейсы потока и хранилища гарантирует, что операция сохранения в этом хранилище не завершится ошибкой из-за нехватки памяти.

Реализация этого метода должна возвращать код ошибки CO_E_ALREADYINITIALIZED, если он получает вызов метода IPersistStorage::InitNew или IPersistStorage::Load после его инициализации.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	objidl.h

См. также раздел

IPersistStorage