Método IClassFactory::CreateInstance (unknwn.h)

Cria um objeto não inicializado.

Sintaxe

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

Parâmetros

[in] pUnkOuter

Se o objeto estiver sendo criado como parte de uma agregação, especifique um ponteiro para a interface IUnknown de controle da agregação. Caso contrário, esse parâmetro deve ser NULL.

[in] riid

Uma referência ao identificador da interface a ser usada para se comunicar com o objeto recém-criado. Se pUnkOuter for NULL, esse parâmetro geralmente será o IID da interface de inicialização; se pUnkOuter não for NULL, riid deverá ser IID_IUnknown.

[out] ppvObject

O endereço da variável de ponteiro que recebe o ponteiro de interface solicitado em riid. Após o retorno bem-sucedido, *ppvObject contém o ponteiro de interface solicitado. Se o objeto não der suporte à interface especificada em riid, a implementação deverá definir *ppvObject como NULL.

Valor retornado

Esse método pode retornar os valores retornados padrão E_INVALIDARG, E_OUTOFMEMORY e E_UNEXPECTED, bem como os valores a seguir.

Código de retorno	Descrição
S_OK	O objeto especificado foi criado.
CLASS_E_NOAGGREGATION	O parâmetro pUnkOuter não era NULL e o objeto não dá suporte à agregação.
E_NOINTERFACE	O objeto para o qual ppvObject aponta não dá suporte à interface identificada por riid.

Comentários

A implementação de CreateInstance de um servidor COM deve retornar uma referência a um objeto contido em um apartment que pertença ao resolvedor DCOM do servidor. Ele não deve retornar uma referência a um objeto contido em um apartamento remoto.

A interface IClassFactory está sempre em um objeto de classe. O método CreateInstance cria um objeto não inicializado da classe identificada com o CLSID especificado. Quando um objeto é criado dessa forma, o CLSID deve ser registrado no registro do sistema com a função CoRegisterClassObject .

O parâmetro pUnkOuter indica se o objeto está sendo criado como parte de uma agregação. As definições de objeto não são necessárias para dar suporte à agregação. Elas devem ser especificamente projetadas e implementadas para dar suporte a ela.

O parâmetro riid especifica o IID (identificador de interface) da interface por meio da qual você se comunicará com o novo objeto. Se pUnkOuter for não NULL (indicando agregação), o valor do parâmetro riid deverá ser IID_IUnknown. Se o objeto não fizer parte de uma agregação, riid geralmente especificará a interface na qual o objeto será inicializado.

Para inserções OLE, a interface de inicialização é IPersistStorage, mas em outras situações, outras interfaces são usadas. Para inicializar o objeto, deve haver uma chamada subsequente para um método apropriado na interface de inicialização. As funções de inicialização comuns incluem IPersistStorage::InitNew (para novos componentes inseriveis em branco), IPersistStorage::Load (para componentes inseriveis recarregados), IPersistStream::Load, (para objetos armazenados em um objeto de fluxo) ou IPersistFile::Load (para objetos armazenados em um arquivo).

Em geral, se um aplicativo der suporte a apenas uma classe de objetos e o objeto de classe estiver registrado para uso único, somente um objeto poderá ser criado. O aplicativo não deve criar outros objetos e uma solicitação para fazer isso deve retornar um erro de IClassFactory::CreateInstance. O mesmo vale para aplicativos que dão suporte a várias classes, cada uma com um objeto de classe registrado para uso único; uma chamada para CreateInstance para uma classe seguida por uma chamada para CreateInstance para qualquer uma das classes que devem retornar um erro.

Para evitar o retorno de um erro, aplicativos que dão suporte a várias classes com objetos de classe de uso único podem revogar o objeto de classe registrado da primeira classe chamando CoRevokeClassObject quando uma solicitação para instanciar um segundo é recebida. Por exemplo, suponha que haja duas classes, A e B. Quando CreateInstance for chamado para a classe A, revogue o objeto de classe para B. Quando B for criado, revogue o objeto de classe para A. Essa solução complica o desligamento porque um dos objetos de classe pode já ter sido revogado (e não pode ser revogado duas vezes).

Requisitos

Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	unknwn.h

Confira também

Cocreateinstance

Cogetclassobject

Coregisterclassobject

Corevokeclassobject

IClassFactory