IDispenserDriver::RateResource

Holder asks resource dispenser to evaluate how well a candidate resource matches.

HRESULT IDispenserDriver::RateResource (

RESOURCERATING *

pRating);

Parameters

ResTypId [in]
The type of resource that DispMan is looking to match.

ResId [in]
The candidate resource that DispMan is considering.

fRequiresTransactionEnlistment [in]
If TRUE, the candidate resource (ResId) if chosen, will require transaction enlistment. If enlistment is expensive, RateResource may want to rate such a resource lower than one which is already enlisted in the correct transaction.

pRating [out]
The Dispenser’s rating of this candidate.

0 = Candidate resource is unuseable for this request. Resource is not or cannot be changed to be of type ResTypId.

1 = Bad fit, but a useable candidate. DispMan will continue to suggest candidates.

2 = Better than 1. DispMan will continue to suggest candidates.

100 = Perfect fit. DispMan stops suggesting candidates when resource dispenser gives a "100" rating to a candidate.

Return Values

S_OK
Successfully rated. Resource dispenser must set *pRating before returning S_OK.

E_FAIL
Failure.

Comments

If fRequiresTransactionEnlistment is FALSE, then an object was dispensed this resource in this transaction, the object used and then freed the resource (explicitly or implicitly at end of object lifetime). A second object in the same transaction asks for a similar resource, and the resource that the first object used is considered. This resource is a good candidate because it is already enlisted in the correct transaction.

If a particular type of resource can only be used once per transaction, then a resource which has already been used once in the transaction may be identified by an fRequiresTransactionEnlistment of FALSE and may be rejected for further use by returning *pRating=0.