Funzione CoGetInstanceFromFile (objbase.h)

Articolo
02/29/2024

Crea un nuovo oggetto e lo inizializza da un file usando IPersistFile::Load.

Sintassi

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
);

Parametri

[in, optional] pServerInfo

Puntatore a una struttura COSERVERINFO che specifica il computer in cui creare un'istanza dell'oggetto e l'impostazione di autenticazione da usare. Questo parametro può essere NULL, nel qual caso l'oggetto viene creata un'istanza nel computer corrente, nel computer specificato nel valore del Registro di sistema RemoteServerName per la classe o nel computer in cui risiede il file pwszName se il valore ActivateAtStorage viene specificato per la classe o non sono presenti informazioni del Registro di sistema locali.

[in, optional] pClsid

Puntatore all'identificatore di classe dell'oggetto da creare. Questo parametro può essere NULL, nel qual caso è presente una chiamata a GetClassFile, usando pwszName come parametro per ottenere la classe dell'oggetto da creare un'istanza.

[in, optional] punkOuter

Quando non NULL, indica che l'istanza viene creata come parte di un'aggregazione e punkOuter deve essere usata come puntatore al controllo di IUnknown della nuova istanza. L'aggregazione non è supportata tra processi o cross-computer. Quando si crea un'istanza di un oggetto fuori processo, CLASS_E_NOAGGREGATION verrà restituito se punkOuter non è NULL.

[in] dwClsCtx

Valori dell'enumerazione CLSCTX .

[in] grfMode

Specifica la modalità di apertura del file. Vedere Costanti STGM.

[in] pwszName

File utilizzato per inizializzare l'oggetto con IPersistFile::Load. Questo parametro non può essere NULL.

[in] dwCount

Numero di strutture in pResults. Questo parametro deve essere maggiore di 0.

[in, out] pResults

Matrice di strutture MULTI_QI . Ogni struttura ha tre membri: l'identificatore per un'interfaccia richiesta (pIID), il percorso per restituire il puntatore dell'interfaccia (pItf) e il valore restituito della chiamata a QueryInterface (hr).

Valore restituito

Questa funzione può restituire il valore restituito standard E_INVALIDARG, nonché i valori seguenti.

Codice restituito	Descrizione
S_OK	La funzione ha recuperato tutte le interfacce correttamente.
CO_S_NOTALLINTERFACES	Almeno uno, ma non tutte le interfacce richieste nella matrice pResults sono state recuperate correttamente. Il membro hr di ogni struttura MULTI_QI indica con S_OK o E_NOINTERFACE se l'interfaccia specifica è stata restituita.
E_NOINTERFACE	Nessuna delle interfacce richieste nella matrice pResults è stata recuperata correttamente.

Commenti

CoGetInstanceFromFile crea un nuovo oggetto e lo inizializza da un file usando IPersistFile::Load. Il risultato di questa funzione è simile alla creazione di un'istanza con una chiamata a CoCreateInstanceEx, seguita da una chiamata di inizializzazione a IPersistFile::Load, con le distinzione importanti seguenti:

Meno round trip di rete sono richiesti da questa funzione quando si crea un'istanza di un oggetto in un computer remoto.
Nel caso in cui dwClsCtx sia impostato su CLSCTX_REMOTE_SERVER e pServerInfo è NULL, se la classe è registrata con la chiave secondaria ActivateAtStorage o non dispone di informazioni del Registro di sistema associate, questa funzione crea un'istanza di un oggetto nel computer in cui risiede pwszName , fornendo il traffico di rete minimo possibile.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	objbase.h
Libreria	Ole32.lib
DLL	ComBase.dll

Vedi anche

CLSCTX

CoCreateInstanceEx

CoGetInstanceFromIStorage