CoGetInstanceFromFile-Funktion (objbase.h)

Artikel
03/06/2024

Erstellt ein neues -Objekt und initialisiert es aus einer Datei mithilfe von IPersistFile::Load.

Syntax

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

Parameter

[in, optional] pServerInfo

Ein Zeiger auf eine COSERVERINFO-Struktur , die den Computer angibt, auf dem das Objekt instanziieren soll, und die zu verwendende Authentifizierungseinstellung. Dieser Parameter kann NULL sein. In diesem Fall wird das Objekt auf dem aktuellen Computer instanziiert, auf dem Computer, der unter dem Registrierungswert RemoteServerName für die Klasse angegeben ist, oder auf dem Computer, auf dem sich die pwszName-Datei befindet, wenn der ActivateAtStorage-Wert für die Klasse angegeben ist oder keine lokalen Registrierungsinformationen vorhanden sind.

[in, optional] pClsid

Ein Zeiger auf den Klassenbezeichner des zu erstellenden Objekts. Dieser Parameter kann NULL sein. In diesem Fall wird GetClassFile aufgerufen, wobei pwszName als Parameter verwendet wird, um die Klasse des zu instanziierenden Objekts abzurufen.

[in, optional] punkOuter

Wenn nicht NULL, gibt an, dass die instance als Teil eines Aggregats erstellt wird, und punkOuter als Zeiger auf die neue instance, die IUnknown steuert. Die Aggregation wird nicht prozess- oder computerübergreifend unterstützt. Beim Instanziieren eines Objekts aus dem Prozess wird CLASS_E_NOAGGREGATION zurückgegeben, wenn punkOuter nicht NULL ist.

[in] dwClsCtx

Werte aus der CLSCTX-Enumeration .

[in] grfMode

Gibt an, wie die Datei geöffnet werden soll. Weitere Informationen finden Sie unter STGM-Konstanten.

[in] pwszName

Die Datei, die zum Initialisieren des Objekts mit IPersistFile::Load verwendet wird. Dieser Parameter darf nicht NULL sein.

[in] dwCount

Die Anzahl der Strukturen in pResults. Dieser Parameter muss größer als 0 sein.

[in, out] pResults

Ein Array von MULTI_QI Strukturen. Jede Struktur verfügt über drei Member: den Bezeichner für eine angeforderte Schnittstelle (pIID), den Speicherort zum Zurückgeben des Schnittstellenzeigers (pItf) und den Rückgabewert des Aufrufs von QueryInterface (hr).

Rückgabewert

Diese Funktion kann den Standardrückgabewert E_INVALIDARG sowie die folgenden Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Die Funktion hat alle Schnittstellen erfolgreich abgerufen.
CO_S_NOTALLINTERFACES	Mindestens eine, aber nicht alle im pResults-Array angeforderten Schnittstellen wurden erfolgreich abgerufen. Der hr-Member der einzelnen MULTI_QI-Strukturen gibt mit S_OK oder E_NOINTERFACE an, ob die spezifische Schnittstelle zurückgegeben wurde.
E_NOINTERFACE	Keine der im pResults-Array angeforderten Schnittstellen wurde erfolgreich abgerufen.

Hinweise

CoGetInstanceFromFile erstellt ein neues Objekt und initialisiert es aus einer Datei mithilfe von IPersistFile::Load. Das Ergebnis dieser Funktion ähnelt dem Erstellen einer instance mit einem Aufruf von CoCreateInstanceEx, gefolgt von einem initialisierenden Aufruf von IPersistFile::Load mit den folgenden wichtigen Unterschieden:

Diese Funktion erfordert weniger Netzwerk roundtrips, wenn ein Objekt auf einem Remotecomputer instanziiert wird.
Wenn dwClsCtx auf CLSCTX_REMOTE_SERVER und pServerInfonull festgelegt ist, wenn die Klasse mit dem ActivateAtStorage-Unterschlüssel registriert ist oder keine zugeordneten Registrierungsinformationen enthält, instanziiert diese Funktion ein Objekt auf dem Computer, auf dem sich pwszName befindet, und stellt so den geringstmöglichen Netzwerkdatenverkehr bereit.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	objbase.h
Bibliothek	Ole32.lib
DLL	ComBase.dll

Weitere Informationen

CLSCTX

CoCreateInstanceEx

CoGetInstanceFromIStorage