IHolder::TrackResource

Tracks the resource.

HRESULT IHolder::TrackResource (

const RESID

ResId);

Parameters

ResId [in]
The handle of the resource to track. The resource dispenser has already created this resource before calling TrackResource.

Return Values

S_OK
Success.

E_INVALIDARG
ResId is not a valid resource handle; is NULL or "" or duplicate.

E_FAIL
Failure. Resource ResId has not been tracked. Likely cause is that the caller's transaction is aborting.

Comments

Some resources are not kept in inventory; they are always manufactured on demand, for example, memory allocation through Malloc. The holder is used only as a mechanism to automatically free the resources left at end of an object's lifetime.

TrackResource tells the holder that a resource should be tracked until it is freed by calling UntrackResource, or until the object which called TrackResource is released, at which time DispMan automatically frees the resource.

If TrackResource is called from a transactional object, it calls back to the resource dispenser's EnlistResource method. The EnlistResource method may enlist the resource in the transaction, or it may return S_FALSE, indicating that the resource is not transaction capable and has not been enlisted.

This resource will eventually be destroyed after both of the following are true:

• The resource dispenser calls UntrackResource (most likely at the component's request) or the object’s lifetime ends.
• The transaction that the resource was enlisted in (if any) is done.