IClassFactory::CreateInstance
A version of this page is also available for
4/8/2010
This method creates an uninitialized object of a specified class identifier (CLSID).
Syntax
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 IUnknown interface of the aggregate. Otherwise, pUnkOuter must be NULL.
riid
[in] Reference to the identifier of the interface to be used to communicate with the newly created object.If pUnkOuter is NULL, this parameter is frequently the IID of the initializing interface.
If pUnkOuter is non-NULL, riid must 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, *ppvObject contains the requested interface pointer.
If the object does not support the interface specified in riid, the implementation must set *ppvObject to NULL.
Return Value
This method supports the standard return values E_UNEXPECTED, E_OUTOFMEMORY, and E_INVALIDARG. The following table shows the additional return values for this method.
| Value | Description |
|---|---|
S_OK |
The specified object was created. |
CLASS_E_NOAGGREGATION |
The pUnkOuter parameter was non-NULL and the object does not support aggregation. |
E_NOINTERFACE |
The object that ppvObject points to does not support the interface identified by riid. |
Remarks
The IClassFactory interface is always on a class object. The CreateInstance method 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 the CoRegisterClassObject function.
The pUnkOuter parameter 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 riid parameter specifies the interface identifier (IID) of the interface through which you will communicate with the new object.
If pUnkOuter is non-NULL (that indicates aggregation), the value of the riid parameter must be IID_IUnknown.
If the object is not part of an aggregate, riid often 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 CreateInstance for one class followed by a CreateInstance for any of the classes should return an error.
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Requirements
| Header | ocidl.h, ocidl.idl |
| Library | ole32.lib, uuid.lib |
| Windows Embedded CE | Windows CE 2.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
IClassFactory
IUnknown
IPersistStorage
IPersistStorage::InitNew
IPersistStorage::Load