Funzione CoCreateInstance (combaseapi.h)

Articolo
08/22/2023

Crea e inizializza un singolo oggetto della classe associato a un CLSID specificato.

Chiamare CoCreateInstance quando si vuole creare un solo oggetto nel sistema locale. Per creare un singolo oggetto in un sistema remoto, chiamare la funzione CoCreateInstanceEx . Per creare più oggetti in base a un singolo CLSID, chiamare la funzione CoGetClassObject .

Sintassi

HRESULT CoCreateInstance(
  [in]  REFCLSID  rclsid,
  [in]  LPUNKNOWN pUnkOuter,
  [in]  DWORD     dwClsContext,
  [in]  REFIID    riid,
  [out] LPVOID    *ppv
);

Parametri

[in] rclsid

CLSID associato ai dati e al codice che verranno usati per creare l'oggetto.

[in] pUnkOuter

Se NULL, indica che l'oggetto non viene creato come parte di un'aggregazione. Se non NULL, puntatore all'interfaccia IUnknown dell'oggetto di aggregazione (controllo di IUnknown).

[in] dwClsContext

Contesto in cui verrà eseguito il codice che gestisce l'oggetto appena creato. I valori vengono acquisiti dall'enumerazione CLSCTX.

[in] riid

Riferimento all'identificatore dell'interfaccia da usare per comunicare con l'oggetto .

[out] ppv

Indirizzo della variabile puntatore che riceve il puntatore dell'interfaccia richiesto in riid. Al termine della restituzione, *ppv contiene il puntatore dell'interfaccia richiesto. In caso di errore, *ppv contiene NULL.

Valore restituito

Questa funzione può restituire i valori seguenti.

Codice restituito	Descrizione
S_OK	È stata creata correttamente un'istanza della classe oggetto specificata.
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	Impossibile creare questa classe come parte di un'aggregazione.
E_NOINTERFACE	La classe specificata non implementa l'interfaccia richiesta oppure il controllo IUnknown non espone l'interfaccia richiesta.
E_POINTER	Il parametro ppv è NULL.

Commenti

La funzione CoCreateInstance fornisce un collegamento pratico connettendosi all'oggetto classe associato al CLSID specificato, creando un'istanza inizializzata predefinita e rilasciando l'oggetto classe. Di conseguenza, incapsula le funzionalità seguenti:

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); 
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj);
pCF->Release();

È pratico usare CoCreateInstance quando è necessario creare solo una singola istanza di un oggetto nel computer locale. Se si crea un'istanza nel computer remoto, chiamare CoCreateInstanceEx. Quando si creano più istanze, è più efficiente ottenere un puntatore all'interfaccia IClassFactory dell'oggetto di classe e usare i relativi metodi in base alle esigenze. In quest'ultimo caso, è necessario usare la funzione CoGetClassObject .

Nell'enumerazione CLSCTX è possibile specificare il tipo di server usato per gestire l'oggetto. Le costanti possono essere CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER o qualsiasi combinazione di questi valori. La costante CLSCTX_ALL è definita come combinazione di tutte e quattro. Per altre informazioni sull'uso di una o una combinazione di queste costanti, vedere CLSCTX.

Applicazioni UWP

Anche se non esistono restrizioni per cui clSID un'applicazione UWP può passare a CoCreateInstance, molti oggetti non riusciranno con E_ACCESSDENIED per motivi di sicurezza, soprattutto se non vengono eseguiti in-process. Inoltre, anche se è possibile creare correttamente un oggetto, potrebbe non riuscire in un secondo momento a causa di vincoli di sicurezza UWP, differenze del modello di app e così via. In particolare, le attività in background devono limitare gli oggetti con cui comunicano per evitare blocchi o altre complicazioni a causa della connessione stand-by.

Esempio

// Create WIC factory
hr = CoCreateInstance(
    CLSID_WICImagingFactory,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&m_pIWICFactory)
    );

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