ACQUIRE_RESOURCE

include vcomm.inc

cCall   dwContentionHandler<ACQUIRE_RESOURCE, dwResourceHandle, dwNotify, 
        dwRefData, fSteal>
or      eax, eax
jz      error_handler
mov     dwAcquireHandle, eax

Requests access to a VCOMM resource, stealing from a current owner if necessary.

Returns a handle to an acquired resource. This is often the same as the handle specified by dwResourceHandle, but it does not have to be.

dwResourceHandle

Handle returned by VCOMM_Map_Name_To_Resource for the resource.

dwNotify

Address of a callback function that receives steal and return notifications.

dwRefData

Address of data that is private to the caller and passed to the notification function.

fSteal

One of the following flags:

ACQUIRE_STEAL	Attempt to steal from current owner, if any.
ACQUIRE_NO_STEAL	Acquire only if there is no current owner.

ACQUIRE_RESOURCE fails if there are already two clients sharing the resource, one active and one waiting.

A client's callback function is called as follows:

cCall   [<e>dwNotify</e>],<[<e>dwRefData</e>],<e>dwNotification</e>

A client's callback function may receive any of the following notifications, specified in dwNotification:

0 = RESOURCE_STEAL_REQUEST	Notifies the client that another client is attempting to acquire or steal the resource specified in dwRefData. The client should save the resource state, if necessary, and return TRUE to allow the resource to be stolen. Otherwise, it should return FALSE to prevent it from being stolen. A client can optionally release the resource before returning TRUE.
1 = RESOURCE_STEAL_NOTIFY	Notifies the client that a previously stolen resource has been returned to it. The client must restore the state of the device, if necessary.

See also _VCOMM_Get_Contention_Handler, VCOMM_Map_Name_To_Resource