Metodo IClassFactory::CreateInstance (unknwn.h)

Crea un oggetto non inizializzato.

Sintassi

HRESULT CreateInstance(
  [in]  IUnknown *pUnkOuter,
  [in]  REFIID   riid,
  [out] void     **ppvObject
);

Parametri

[in] pUnkOuter

Se l'oggetto viene creato come parte di un'aggregazione, specificare un puntatore all'interfaccia IUnknown di controllo dell'aggregazione. In caso contrario, questo parametro deve essere NULL.

[in] riid

Riferimento all'identificatore dell'interfaccia da utilizzare per comunicare con l'oggetto appena creato. Se pUnkOuter è NULL, questo parametro è in genere l'IID dell'interfaccia di inizializzazione; se pUnkOuter è diverso da NULL, riid deve essere IID_IUnknown.

[out] ppvObject

Indirizzo della variabile del puntatore che riceve il puntatore di interfaccia richiesto in riid. Al termine della restituzione, *ppvObject contiene il puntatore all'interfaccia richiesto. Se l'oggetto non supporta l'interfaccia specificata in riid, l'implementazione deve impostare *ppvObject su NULL.

Valore restituito

Questo metodo può restituire i valori restituiti standard E_INVALIDARG, E_OUTOFMEMORY e E_UNEXPECTED, nonché i valori seguenti.

Codice restituito	Descrizione
S_OK	L'oggetto specificato è stato creato.
CLASS_E_NOAGGREGATION	Il parametro pUnkOuter non è NULL e l'oggetto non supporta l'aggregazione.
E_NOINTERFACE	L'oggetto che ppvObject punta a non supporta l'interfaccia identificata da riid.

Commenti

L'implementazione di un server COM di CreateInstance deve restituire un riferimento a un oggetto contenuto in un apartment appartenente al resolver DCOM del server. Non deve restituire un riferimento a un oggetto contenuto in un apartment remoto.

L'interfaccia IClassFactory è sempre in un oggetto classe. Il metodo CreateInstance crea un oggetto non inizializzato della classe identificata con il CLSID specificato. Quando un oggetto viene creato in questo modo, il CLSID deve essere registrato nel Registro di sistema con la funzione CoRegisterClassObject .

Il parametro pUnkOuter indica se l'oggetto viene creato come parte di un'aggregazione. Le definizioni degli oggetti non sono necessarie per supportare l'aggregazione, ma devono essere progettate e implementate in modo specifico per supportarlo.

Il parametro riid specifica l'IID (identificatore dell'interfaccia) dell'interfaccia tramite cui si comunicherà con il nuovo oggetto. Se pUnkOuter è diverso da NULL (che indica l'aggregazione), il valore del parametro riid deve essere IID_IUnknown. Se l'oggetto non fa parte di un'aggregazione, riid specifica spesso l'interfaccia tramite cui verrà inizializzato l'oggetto.

Per gli incorporamenti OLE, l'interfaccia di inizializzazione è IPersistStorage, ma in altre situazioni vengono usate altre interfacce. Per inizializzare l'oggetto, deve essere presente una chiamata successiva a un metodo appropriato nell'interfaccia di inizializzazione. Le funzioni di inizializzazione comuni includono IPersistStorage::InitNew (per i nuovi componenti incorporabili vuoti), IPersistStorage::Load (per i componenti incorporabili ricaricati), IPersistStream::Load, (per gli oggetti archiviati in un oggetto flusso) o IPersistFile::Load (per gli oggetti archiviati in un file).

In generale, se un'applicazione supporta solo una classe di oggetti e l'oggetto classe viene registrato per un singolo utilizzo, è possibile creare un solo oggetto. L'applicazione non deve creare altri oggetti e una richiesta a tale scopo deve restituire un errore da IClassFactory::CreateInstance. Lo stesso vale per le applicazioni che supportano più classi, ognuna con un oggetto classe registrato per un singolo uso; una chiamata a CreateInstance per una classe seguita da una chiamata a CreateInstance per una delle classi che devono restituire un errore.

Per evitare di restituire un errore, le applicazioni che supportano più classi con oggetti classe a uso singolo possono revocare l'oggetto classe registrato della prima classe chiamando CoRevokeClassObject quando viene ricevuta una richiesta di creazione di un'istanza di un secondo. Si supponga, ad esempio, che siano presenti due classi, A e B. Quando createInstance viene chiamato per la classe A, revocare l'oggetto classe per B. Quando viene creato B, revocare l'oggetto classe per A. Questa soluzione complica l'arresto perché uno degli oggetti classe potrebbe essere già stato revocato (e non può essere revocato due volte).

Requisiti

Client minimo supportato	Windows 2000 Professional [app desktop | App UWP]
Server minimo supportato	Windows 2000 Server [app desktop | App UWP]
Piattaforma di destinazione	Windows
Intestazione	unknwn.h

Vedi anche

Cocreateinstance

CoGetClassObject

CoRegisterClassObject

CoRevokeClassObject

IClassFactory