IClassFactory::CreateInstance

Creates an uninitialized object.

HRESULT CreateInstance(

IUnknown * pUnkOuter,
//Object is or isn't part of an aggregate
REFIID riid,
//Interface identifier
void ** ppvObject
//On return, pointer to interface pointer location
);

Parameters

pUnkOuter

[in] Indicates whether the object is being created as part of an aggregate. If so, you should use pUnkOuter to supply a pointer to the controlling unknown of the aggregate that will use the newly created object. If not, pUnkOuter should be NULL.

riid

[in]Specifies the IID 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.

ppvObject

[out]On return, points to the location of the requested interface pointer. If the object does not support the interface specified in riid, ppvObj is set to NULL.

Return Values

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 ppvObj points to does not support the interface identified by riid.

E_UNEXPECTED

An unexpected error occurred.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more arguments are invalid.

Comments

The IClassFactory interface is always on a class object. The CreateInstance method creates an uninitialized object, which is defined in the code associated with the class object.

The pUnkOuter parameter indicates whether the object is being created as part of an aggregate. Object definitions are not required to support aggregation pics/OLE00090000.gif they must be specifically designed and implemented to support it.

The riid parameter specifies the IID (interface ID) of the interface through which you communicate with the new object. If pUnkOuter is non-NULL (indicating 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), IPersistStream::Load, or IPersistFile::Load.

In general, if an application supports one object definition, 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 avoid returning an error, applications that support multiple object definitions with single-use class objects can revoke the registered class object of the first definition by calling CoRevokeClassObject when a request for instantiating a second is received. For example, suppose there are two classes, A and B. When IClassFactory::CreateInstance is called for class A, revoke the class object for B. When B is created, revoke the class object for A. This solution complicates shutdown because one of the class objects might have already been revoked (and cannot be revoked twice).

Software for developers
Delphi Components
.Net Components
Software for Android Developers
More information resources
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
Databases for Amazon shops developers
Amazon Categories Database
Browse Nodes Database