Platform SDK: Transaction Server

IObjectControl Interface

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

You implement the IObjectControl interface when you want to define context-specific initialization and cleanup procedures for your MTS objects and specify whether or not the objects can be recycled. Implementing the IObjectControl interface is optional.

Remarks

The header file for the IObjectControl interface is mtx.h.

If you implement the IObjectControl interface in your component, the MTS run-time environment automatically calls the IObjectControl methods on your objects at the appropriate times.

When an object supports the IObjectControl interface, MTS calls its Activate method once for each time the object is activated. The Activate method is called before any of the object's other methods are called. You can use this method to perform any context-specific initialization an object may require.

Note An object's context isn't available during object construction (from the object's class factory), so context-specific initialization can't be performed in an object's constructor.

MTS calls the object's Deactivate method each time the object is deactivated. This can be the result of the object returning from a method in which it calls SetComplete or SetAbort, or due to the root of the object's transaction, causing the transaction to complete. You use the Deactivate method to clean up state that you initialized in the Activate method.

After calling the Deactivate method, the MTS run-time environment calls the CanBePooled method. If this method returns TRUE, the deactivated object is placed in an object pool for reuse. If the CanBePooled method returns FALSE, the object is released in the usual way and its destructor is invoked.

Note On systems that don't support object pooling, the value returned by this method is ignored.

The IObjectControl interface is not accessible to an object's clients or to the object itself. Only the MTS run-time environment can invoke the IObjectControl methods. If a client queries for the IObjectControl interface, QueryInterface will return E_NOINTERFACE.

The IObjectControl interface exposes the following methods.

Method	Description
Activate	Allows an object to perform context-specific initialization whenever it's activated. This method is called by the MTS run-time environment before any other methods are called on the object.
CanBePooled	Allows an object to notify the MTS run-time environment of whether it can be pooled for reuse. Return TRUE if you want instances of this component to be pooled, or FALSE if not.
Deactivate	Allows an object to perform whatever cleanup is necessary before it's recycled or destroyed. This method is called by the MTS run-time environment whenever an object is deactivated.