Funzione CoCreateInstanceEx (combaseapi.h)

Articolo
02/28/2024

Crea un'istanza di una classe specifica in un computer specifico.

Sintassi

HRESULT CoCreateInstanceEx(
  [in]      REFCLSID     Clsid,
  [in]      IUnknown     *punkOuter,
  [in]      DWORD        dwClsCtx,
  [in]      COSERVERINFO *pServerInfo,
  [in]      DWORD        dwCount,
  [in, out] MULTI_QI     *pResults
);

Parametri

[in] Clsid

CLSID dell'oggetto da creare.

[in] punkOuter

Se questo parametro non è NULL, indica che l'istanza viene creata come parte di un'aggregazione e punkOuter deve essere usato come controllo di IUnknown della nuova istanza. L'aggregazione non è attualmente supportata tra processi o tra computer. Quando si crea un'istanza di un oggetto fuori processo, CLASS_E_NOAGGREGATION verrà restituito se punkOuter è diverso da NULL.

[in] dwClsCtx

Valore dell'enumerazione CLSCTX .

[in] pServerInfo

Informazioni sul computer in cui creare un'istanza dell'oggetto. Vedere COSERVERINFO. Questo parametro può essere NULL, nel qual caso viene creata un'istanza dell'oggetto nel computer locale o nel computer specificato nel Registro di sistema con il valore RemoteServerName della classe, in base all'interpretazione del parametro dwClsCtx .

[in] dwCount

Numero di strutture in pResults. Questo valore 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), la posizione in cui restituire il puntatore di 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	Indica l'esito positivo dell'operazione.
REGDB_E_CLASSNOTREG	Una classe specificata non è registrata nel database di registrazione. Può anche indicare che il tipo di server richiesto nell'enumerazione CLSCTX non è registrato o i valori per i tipi di server nel Registro di sistema sono danneggiati.
CLASS_E_NOAGGREGATION	Questa classe non può essere creata come parte di un'aggregazione.
CO_S_NOTALLINTERFACES	Almeno una, ma non tutte le interfacce richieste nella matrice pResults sono state recuperate correttamente. Il membro hr di ognuna delle strutture MULTI_QI in pResults indica con S_OK o E_NOINTERFACE se è stata restituita l'interfaccia specifica.
E_NOINTERFACE	Nessuna delle interfacce richieste nella matrice pResults è stata recuperata correttamente.

Commenti

CoCreateInstanceEx crea un singolo oggetto non inizializzato associato al CLSID specificato in un computer remoto specificato. Si tratta di un'estensione della funzione CoCreateInstance, che crea un oggetto solo nel computer locale. Inoltre, anziché richiedere una singola interfaccia e ottenere un singolo puntatore a tale interfaccia, CoCreateInstanceEx consente di specificare una matrice di strutture, ognuna che punta a un identificatore di interfaccia (IID) sull'input e, in caso di restituzione, contenente (se disponibile) un puntatore all'interfaccia richiesta e il valore restituito della chiamata QueryInterface per tale interfaccia. Ciò consente un minor numero di round trip tra i computer.

Questa funzione incapsula tre chiamate: per prima cosa, a CoGetClassObject per connettersi all'oggetto classe associato al CLSID specificato, specificando la posizione della classe; in secondo luogo, a IClassFactory::CreateInstance per creare un'istanza non inizializzata e infine a IClassFactory::Release, per rilasciare l'oggetto classe.

L'oggetto creato deve comunque essere inizializzato tramite una chiamata a una delle interfacce di inizializzazione, ad esempio IPersistStorage::Load. Due funzioni, CoGetInstanceFromFile e CoGetInstanceFromIStorage incapsulano sia la creazione dell'istanza che l'inizializzazione dalle origini ovvie.

La struttura COSERVERINFO passata come parametro pServerInfo contiene le impostazioni di sicurezza che COM userà durante la creazione di una nuova istanza dell'oggetto specificato. Si noti che questo parametro non influisce sulle impostazioni di sicurezza usate durante l'esecuzione di chiamate al metodo sull'oggetto di cui è stata creata un'istanza. Queste impostazioni di sicurezza sono configurabili, per ogni interfaccia, con la funzione CoSetProxyBlanket . Vedere anche IClientSecurity::SetBlanket.

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	combaseapi.h (include Objbase.h)
Libreria	Ole32.lib
DLL	Ole32.dll

Vedi anche

CoGetInstanceFromFile

CoGetInstanceFromIStorage