Funzione CoGetClassObject (combaseapi.h)

Articolo
08/22/2023

Fornisce un puntatore a un'interfaccia su un oggetto classe associato a un CLSID specificato. CoGetClassObject individua e, se necessario, carica dinamicamente il codice eseguibile necessario per eseguire questa operazione.

Chiamare CoGetClassObject direttamente per creare più oggetti tramite un oggetto classe per il quale è presente un CLSID nel Registro di sistema. È anche possibile recuperare un oggetto classe da un computer remoto specifico. La maggior parte degli oggetti classe implementa l'interfaccia IClassFactory . Si chiamerebbe quindi CreateInstance per creare un oggetto non inizializzato. Tuttavia, non è sempre necessario eseguire questo processo. Per creare un singolo oggetto, chiamare la funzione CoCreateInstanceEx , che consente di creare un'istanza in un computer remoto. In questo modo viene sostituita la funzione CoCreateInstance , che può comunque essere usata per creare un'istanza in un computer locale. Entrambe le funzioni incapsulano la connessione all'oggetto classe, la creazione dell'istanza e il rilascio dell'oggetto classe. Due altre funzioni, CoGetInstanceFromFile e CoGetInstanceFromIStorage, forniscono entrambe la creazione di istanze in un sistema remoto e l'attivazione di oggetti. Esistono numerose funzioni e metodi di interfaccia il cui scopo è creare oggetti di un singolo tipo e fornire un puntatore a un'interfaccia su tale oggetto.

Sintassi

HRESULT CoGetClassObject(
  [in]           REFCLSID rclsid,
  [in]           DWORD    dwClsContext,
  [in, optional] LPVOID   pvReserved,
  [in]           REFIID   riid,
  [out]          LPVOID   *ppv
);

Parametri

[in] rclsid

CLSID associato ai dati e al codice che verranno usati per creare gli oggetti.

[in] dwClsContext

Contesto in cui deve essere eseguito il codice eseguibile. Per abilitare un'attivazione remota, includere CLSCTX_REMOTE_SERVER. Per altre informazioni sui valori di contesto e sul relativo utilizzo, vedere l'enumerazione CLSCTX .

[in, optional] pvReserved

Puntatore al computer in cui creare un'istanza dell'oggetto classe. Se questo parametro è NULL, l'oggetto classe viene creata un'istanza nel computer corrente o nel computer specificato nella chiave RemoteServerName della classe, in base all'interpretazione del parametro dwClsCtx . Vedere COSERVERINFO.

[in] riid

Riferimento all'identificatore dell'interfaccia, che verrà fornito in ppv in caso di esito positivo. Questa interfaccia verrà usata per comunicare con l'oggetto classe . In genere questo valore è IID_IClassFactory, anche se sono consentiti altri valori, ad esempio IID_IClassFactory2 che supportano una forma di licenza. Tutti gli ID di interfaccia OLE definiti vengono definiti nei file di intestazione OLE come IID_interfacename, dove interfacename è il nome dell'interfaccia.

[out] ppv

Indirizzo della variabile del puntatore che riceve il puntatore di interfaccia richiesto in riid. Al termine della restituzione, *ppv contiene il puntatore all'interfaccia richiesto.

Valore restituito

Questa funzione può restituire i valori seguenti.

Codice restituito	Descrizione
S_OK	Posizione e connessione all'oggetto classe specificato hanno avuto esito positivo.
REGDB_E_CLASSNOTREG	CLSID non è registrato correttamente. Questo errore può anche indicare che il valore specificato in dwClsContext non si trova nel Registro di sistema.
E_NOINTERFACE	L'oggetto a cui punta ppv non supporta l'interfaccia identificata da riid o l'operazione QueryInterface sull'oggetto classe restituito E_NOINTERFACE.
REGDB_E_READREGDB	Errore durante la lettura del database di registrazione.
CO_E_DLLNOTFOUND	La DLL in-process o la DLL del gestore non è stata trovata (a seconda del contesto).
CO_E_APPNOTFOUND	Il file eseguibile (.exe) non è stato trovato (solo CLSCTX_LOCAL_SERVER).
E_ACCESSDENIED	Si è verificato un errore di accesso generale al carico.
CO_E_ERRORINDLL	Si è verificato un errore nell'immagine eseguibile.
CO_E_APPDIDNTREG	L'eseguibile è stato avviato, ma non ha registrato l'oggetto classe (e potrebbe essere stato arrestato).

Commenti

Un oggetto classe in OLE è un oggetto intermedio che supporta un'interfaccia che consente operazioni comuni a un gruppo di oggetti. Gli oggetti in questo gruppo sono istanze derivate dalla stessa definizione di oggetto rappresentata da un singolo CLSID. In genere, l'interfaccia implementata in un oggetto classe è IClassFactory, tramite la quale è possibile creare istanze di oggetto di una determinata definizione (classe).

Una chiamata a CoGetClassObject crea, inizializza e concede al chiamante l'accesso (tramite un puntatore a un'interfaccia specificata con il parametro riid ) all'oggetto classe. L'oggetto classe è quello associato al CLSID specificato nel parametro rclsid . I dettagli sul modo in cui il sistema individua il codice e i dati associati all'interno di un computer sono trasparenti per il chiamante, così come il caricamento dinamico di qualsiasi codice non già caricato.

Se il contesto della classe è CLSCTX_REMOTE_SERVER, a indicare che è necessaria l'attivazione remota, la struttura COSERVERINFO fornita nel parametro pServerInfo consente di specificare il computer in cui si trova il server. Per informazioni sull'algoritmo usato per individuare un server remoto quando pServerInfo è NULL, vedere l'enumerazione CLSCTX .

Esistono due posizioni in cui trovare un CLSID per una classe:

Il Registro di sistema contiene un'associazione tra CLSID e suffissi di file e tra CLSID e firme di file per determinare la classe di un oggetto.
Quando un oggetto viene salvato in una risorsa di archiviazione permanente, il relativo CLSID viene archiviato con i relativi dati.

Per creare e inizializzare oggetti documento OLE incorporati o collegati, non è necessario chiamare direttamente CoGetClassObject . Chiamare invece la funzione OleCreate o OleCreateXXX . Queste funzioni incapsulano l'intero processo di creazione e inizializzazione dell'oggetto e chiamano, tra le altre funzioni , CoGetClassObject.

Il parametro riid specifica l'interfaccia che il client userà per comunicare con l'oggetto classe. Nella maggior parte dei casi, questa interfaccia è IClassFactory. In questo modo è possibile accedere al metodo CreateInstance , tramite il quale il chiamante può quindi creare un oggetto non inizializzato del tipo specificato nell'implementazione. Tutte le classi registrate nel sistema con un CLSID devono implementare IClassFactory.

In rari casi, tuttavia, è possibile specificare un'altra interfaccia che definisce le operazioni comuni a un set di oggetti. Ad esempio, nel modo in cui OLE implementa i moniker, l'interfaccia nell'oggetto classe è IParseDisplayName, usata per trasformare il nome visualizzato di un oggetto in un moniker.

Il parametro dwClsContext specifica il contesto di esecuzione, consentendo l'associazione di un CLSID a parti di codice diverse in contesti di esecuzione diversi. L'enumerazione CLSCTX specifica i flag di contesto disponibili. CoGetClassObject consulta (come appropriato per il contesto indicato) sia il Registro di sistema che gli oggetti di classe attualmente registrati chiamando la funzione CoRegisterClassObject .

Per rilasciare un oggetto classe, utilizzare il metodo Release dell'oggetto classe. La funzione CoRevokeClassObject deve essere usata solo per rimuovere il CLSID di un oggetto classe dal Registro di sistema.

Requisiti


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