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 |
|---|---|
|
O objeto especificado foi criado. |
|
O parâmetro pUnkOuter não era NULL e o objeto não dá suporte à agregação. |
|
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 |