Função CoGetInstanceFromIStorage (objbase.h)

Cria um novo objeto e o inicializa de um objeto de armazenamento por meio de uma chamada interna para IPersistFile::Load.

Sintaxe

HRESULT CoGetInstanceFromIStorage(
  [in, optional] COSERVERINFO *pServerInfo,
  [in, optional] CLSID        *pClsid,
  [in, optional] IUnknown     *punkOuter,
  [in]           DWORD        dwClsCtx,
  [in]           IStorage     *pstg,
  [in]           DWORD        dwCount,
  [in, out]      MULTI_QI     *pResults
);

Parâmetros

[in, optional] pServerInfo

Um ponteiro para uma estrutura COSERVERINFO que especifica o computador no qual criar uma instância do objeto e a configuração de autenticação a ser usada. Esse parâmetro pode ser NULL, caso em que o objeto é instanciado no computador atual, no computador especificado sob o valor do registro RemoteServerName para a classe ou no computador em que o objeto de armazenamento pstg reside se o valor ActivateAtStorage for especificado para a classe ou se não houver informações do registro local.

[in, optional] pClsid

Um ponteiro para o identificador de classe do objeto a ser criado. Esse parâmetro pode ser NULL; nesse caso, há uma chamada para IStorage::Stat para localizar a classe do objeto .

[in, optional] punkOuter

Quando não NULL, indica que a instância está sendo criada como parte de uma agregação, e punkOuter deve ser usado como o ponteiro para o IUnknown controlador da nova instância. Não há suporte para agregação entre processos ou entre computadores. Ao instanciar um objeto fora do processo, CLASS_E_NOAGGREGATION será retornado se punkOuter não for NULL.

[in] dwClsCtx

Valores da enumeração CLSCTX .

[in] pstg

Um ponteiro para o objeto de armazenamento usado para inicializar o objeto com IPersistFile::Load. Esse parâmetro não pode ser NULL.

[in] dwCount

O número de estruturas em pResults. Esse parâmetro deve ser maior que 0.

[in, out] pResults

Uma matriz de estruturas MULTI_QI . Cada estrutura tem três membros: o identificador de uma interface solicitada (pIID), o local para retornar o ponteiro da interface (pItf) e o valor retornado da chamada para QueryInterface (hr).

Retornar valor

Essa função pode retornar o valor retornado padrão E_INVALIDARG, bem como os valores a seguir.

Código de retorno	Descrição
S_OK	A função recuperou todas as interfaces com êxito.
CO_S_NOTALLINTERFACES	Pelo menos uma, mas nem todas as interfaces solicitadas na matriz pResults foram recuperadas com êxito. O membro hr de cada uma das estruturas de MULTI_QI indica com S_OK ou E_NOINTERFACE se a interface específica foi retornada.
E_NOINTERFACE	Nenhuma das interfaces solicitadas na matriz pResults foi recuperada com êxito.

Comentários

CoGetInstanceFromIStorage cria um novo objeto e o inicializa de um objeto de armazenamento usando IPersistFile::Load. O resultado dessa função é semelhante à criação de uma instância com uma chamada para CoCreateInstanceEx, seguida por uma chamada de inicialização para IPersistFile::Load, com as seguintes distinções importantes:

• Menos viagens de ida e volta de rede são exigidas por essa função ao instanciar um objeto em um computador remoto.
• No caso em que dwClsCtx estiver definido como CLSCTX_REMOTE_SERVER e pServerInfo for NULL, se a classe for registrada com o valor ActivateAtStorage ou não tiver informações do Registro associadas, essa função criará uma instância de um objeto no computador em que o pstg reside, fornecendo o menor tráfego de rede possível.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	objbase.h
Biblioteca	Ole32.lib
DLL	Ole32.dll

Confira também

CLSCTX

Cocreateinstanceex

CoGetInstanceFromFile