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.

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

Confira também

CLSCTX

Cocreateinstanceex

CoGetInstanceFromIStorage