Função CoGetInstanceFromFile (objbase.h)
Cria um novo objeto e o inicializa de um arquivo usando IPersistFile::Load.
Sintaxe
HRESULT CoGetInstanceFromFile(
[in, optional] COSERVERINFO *pServerInfo,
[in, optional] CLSID *pClsid,
[in, optional] IUnknown *punkOuter,
[in] DWORD dwClsCtx,
[in] DWORD grfMode,
[in] OLECHAR *pwszName,
[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 arquivo pwszName 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, caso em que há uma chamada para GetClassFile, usando pwszName como seu parâmetro para obter a classe do objeto a ser instanciada.
[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] grfMode
Especifica como o arquivo deve ser aberto. Consulte Constantes STGM.
[in] pwszName
O arquivo 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 |
|---|---|
|
A função recuperou todas as interfaces com êxito. |
|
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. |
|
Nenhuma das interfaces solicitadas na matriz pResults foi recuperada com êxito. |
Comentários
CoGetInstanceFromFile cria um novo objeto e o inicializa de um arquivo 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 a subchave ActivateAtStorage ou não tiver informações do Registro associadas, essa função criará uma instância de um objeto no computador em que pwszName 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 | ComBase.dll |