Platform SDK: Transaction Server

IObjectContext::CreateInstance Method

[This product will work only on Windows NT 4.0 versions and earlier. For Windows 2000 and later, see COM+ (Component Services).]

Instantiates an MTS object.

Provided By

IObjectContext

HRESULT IObjectContext::CreateInstance (
    REFCLSID rclsid,
    REFIID riid,
    LPVOID FAR* ppvObj
);

Parameter

rclsid
[in] A reference to the CLSID of the type of object to instantiate.

riid
[in] A reference to the interface ID of the interface through which you want to communicate with the new object.

ppvObj
[out] A reference to the requested interface on the new object.

Return Values

S_OK
The object was created and a reference to it is returned in the ppvObj parameter.

REGDB_E_CLASSNOTREG
The component specified by rclsid is not registered as a COM component.

E_OUTOFMEMORY
There's not enough memory available to instantiate the object.

E_INVALIDARG
The argument passed in the ppvObj parameter is invalid.

E_UNEXPECTED
An unexpected error occurred. This can happen if one object passes its IObjectContext pointer to another object, and the other object calls CreateInstance using this pointer. An IObjectContext pointer is not valid outside the context of the object that originally obtained it.

Remarks

CreateInstance creates a COM object. However, the object will have context only if its component is registered with MTS.

When you create an object by using CreateInstance, the new object's context is derived from the current object's ObjectContext and the declarative properties of the new object's component. The new object always executes within the same activity as the object that created it. If the current object has a transaction, the transaction attribute of the new object's component determines whether or not the new object will execute within the scope of that transaction.

If the component's transaction attribute is set to either Requires a transaction or Supports transactions, the new object inherits its creator's transaction. If the component's transaction attribute is set to Requires a new transaction, MTS initiates a new transaction for the new object. If the component's transaction attribute is set to Does not support transactions, the new object doesn't execute under any transaction.

If the Microsoft Distributed Transaction Coordinator is not running and the object is transactional, the object is successfully created. However, method calls to that object will fail with CONTEXT_E_TMNOTAVAILABLE. Objects cannot recover from this condition and should be released.

MTS always uses standard marshaling. Even if a component exposes the IMarshal interface, its IMarshal methods will never be called by the MTS run-time environment.

You can't create MTS objects as part of an aggregation. In this respect, using CreateInstance is like using CoCreateInstance and specifying NULL for the controlling IUnknown interface (pUnkOuter).

Example