IClassFactory::CreateInstance

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This method creates an uninitialized object of a specified class identifier (CLSID).

HRESULT CreateInstance(
IUnknown *
pUnkOuter
,

REFIID
riid
,
void
**
ppvObject
);

Parameters

pUnkOuter

[in] If the object is being created as part of an aggregate, pointer to the controlling IUnknowninterface of the aggregate. Otherwise, pUnkOutermust be NULL.

riid

[in] Reference to the identifier of the interface to be used to communicate with the newly created object. If pUnkOuteris NULL, this parameter is frequently the IID of the initializing interface; if pUnkOuteris non-NULL, riidmust be IID_IUnknown(defined in the header as the IID for IUnknown).

ppvObject

[out] Pointer to a pointer variable that receives the interface pointer requested in riid. Upon successful return, * ppvObjectcontains the requested interface pointer. If the object does not support the interface specified in riid, the implementation must set * ppvObjectto NULL.

Return Values

This method supports the standard return values E_UNEXPECTED, E_OUTOFMEMORY, and E_INVALIDARG, as well as the values described in the following table.

Value	Description
S_OK	The specified object was created.
CLASS_E_NOAGGREGATION	The pUnkOuterparameter was non-NULL and the object does not support aggregation.
E_NOINTERFACE	The object that ppvObjectpoints to does not support the interface identified by riid.

Remarks

The IClassFactoryinterface is always on a class object. The CreateInstancemethod creates an uninitialized object of the class identified with the specified CLSID. When an object is created in this way, the CLSID must be registered in the system registry with CoRegisterClassObject.

The pUnkOuterparameter indicates whether the object is being created as part of an aggregate. Object definitions are not required to support aggregation — they must be specifically designed and implemented to support it.

The riidparameter specifies the interface identifier (IID) of the interface through which you will communicate with the new object. If pUnkOuteris non-NULL (that indicates aggregation), the value of the riidparameter must be IID_IUnknown. If the object is not part of an aggregate, riidoften specifies the interface though which the object will be initialized.

For OLE embeddings, the initialization interface is IPersistStorage, but in other situations, other interfaces are used. To initialize the object, there must be a subsequent call to an appropriate method in the initializing interface. Common initialization functions include IPersistStorage::InitNew(for new, blank embeddable components), IPersistStorage::Load(for reloaded embeddable components),

In general, if an application supports only one class of objects, and the class object is registered for single use, only one object can be created. The application must not create other objects, and a request to do so should return an error from IClassFactory::CreateInstance. The same is true for applications that support multiple classes, each with a class object registered for single use; a CreateInstancefor one class followed by a CreateInstancefor any of the classes should return an error.

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Objbase.h

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.