Метод IClassFactory::CreateInstance (unknwn.h)

Статья
08/26/2023

Создает неинициализированный объект.

Синтаксис

HRESULT CreateInstance(
  [in]  IUnknown *pUnkOuter,
  [in]  REFIID   riid,
  [out] void     **ppvObject
);

Параметры

[in] pUnkOuter

Если объект создается как часть агрегата, укажите указатель на управляющий интерфейс IUnknown агрегата. В противном случае этот параметр должен иметь значение NULL.

[in] riid

Ссылка на идентификатор интерфейса, используемого для взаимодействия с вновь созданным объектом. Если pUnkOuter имеет значение NULL, этот параметр обычно является IID интерфейса инициализации; Если pUnkOuter не имеет значения NULL, riid должен быть IID_IUnknown.

[out] ppvObject

Адрес переменной указателя, получающей указатель интерфейса, запрошенный в riid. После успешного возврата *ppvObject содержит запрошенный указатель интерфейса. Если объект не поддерживает интерфейс, указанный в riid, реализация должна присвоить *ppvObject значение NULL.

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

Этот метод может возвращать стандартные возвращаемые значения E_INVALIDARG, E_OUTOFMEMORY и E_UNEXPECTED, а также следующие значения.

Код возврата	Описание
S_OK	Указанный объект был создан.
CLASS_E_NOAGGREGATION	Параметр pUnkOuter не имеет значения NULL , а объект не поддерживает агрегирование.
E_NOINTERFACE	Объект, на который указывает ppvObject , не поддерживает интерфейс, определяемый riid.

Реализация CreateInstance com-сервера должна возвращать ссылку на объект, содержащийся в объекте, принадлежавшем сопоставителя DCOM сервера. Он не должен возвращать ссылку на объект, содержащийся в удаленной квартире.

Интерфейс IClassFactory всегда находится в объекте класса. Метод CreateInstance создает неинициализированный объект класса, идентифицируемый указанным идентификатором CLSID. Если объект создается таким образом, идентификатор CLSID должен быть зарегистрирован в системном реестре с помощью функции CoRegisterClassObject .

Параметр pUnkOuter указывает, создается ли объект как часть агрегата. Определения объектов не требуются для поддержки агрегирования. Они должны быть специально разработаны и реализованы для поддержки.

Параметр riid задает идентификатор интерфейса, через который будет взаимодействовать с новым объектом. Если pUnkOuter не равно NULL (что указывает на агрегирование), значение параметра riid должно быть IID_IUnknown. Если объект не является частью агрегата, riid часто задает интерфейс, который будет инициализирован.

Для внедрения OLE интерфейс инициализации — IPersistStorage, но в других ситуациях используются другие интерфейсы. Чтобы инициализировать объект, необходимо выполнить последующий вызов соответствующего метода в интерфейсе инициализации. Распространенные функции инициализации включают IPersistStorage::InitNew (для новых пустых встраиваемых компонентов), IPersistStorage::Load (для перезагруженных внедренных компонентов), IPersistStream::Load (для объектов, хранящихся в объекте потока) или IPersistFile::Load (для объектов, хранящихся в файле).

Как правило, если приложение поддерживает только один класс объектов и объект класса зарегистрирован для однократного использования, можно создать только один объект. Приложение не должно создавать другие объекты, и запрос на это должен возвращать ошибку из IClassFactory::CreateInstance. То же самое относится и к приложениям, поддерживающим несколько классов, каждый из которых имеет объект класса, зарегистрированный для однократного использования; вызов CreateInstance для одного класса, за которым следует вызов CreateInstance для любого из классов, которые должны возвращать ошибку.

Чтобы избежать возврата ошибки, приложения, поддерживающие несколько классов с одноразовыми объектами класса, могут отозвать зарегистрированный объект класса первого класса путем вызова CoRevokeClassObject при получении запроса на создание второго экземпляра. Например, предположим, что существует два класса: A и B. При вызове CreateInstance для класса A отмените объект класса для B. При создании B отмените объект класса для A. Это решение усложняет завершение работы, так как один из объектов класса, возможно, уже был отозван (и не может быть отозван дважды).

Требования


Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	unknwn.h

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

CoCreateInstance

CoGetClassObject

CoRegisterClassObject

CoRevokeClassObject

IClassFactory