Edit

EVT_SPB_CONTROLLER_LOCK callback function (spbcx.h)

  • Article

An SPB controller driver's EvtSpbControllerLock event callback function locks the SPB controller for accesses of a single target device on the bus.

Syntax

EVT_SPB_CONTROLLER_LOCK EvtSpbControllerLock;

void EvtSpbControllerLock(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST LockRequest
)
{...}

Parameters

[in] Controller

A WDFDEVICE handle to the framework device object that represents the SPB controller.

[in] Target

An SPBTARGET handle to the target for this I/O request. The target is a peripheral device or port that is attached to the bus. The SPB framework extension (SpbCx) previously assigned this handle to the target in the EvtSpbTargetConnect callback that opened the connection to the target.

[in] LockRequest

An SPBREQUEST handle to an I/O control request to lock the controller. Your SPB controller driver must complete this request either by performing the requested operation or by returning an error status. For more information, see Remarks.

Return value

None

Remarks

SpbCx manages the I/O queue for the SPB controller. If the SPB controller driver registers an EvtSpbControllerLock callback function, SpbCx calls this function when a client (peripheral driver) of the controller sends an IOCTL_SPB_LOCK_CONTROLLER request to a target on the bus. The LockRequest parameter value is a handle that encapsulates this request.

The EvtSpbControllerLock and EvtSpbControllerUnlock functions perform complementary operations. Both functions are optional. If your SPB controller driver implements an EvtSpbControllerUnlock function, the driver is not required to implement an EvtSpbControllerLock function, but might do so. However, if your SPB controller driver implements an EvtSpbControllerLock function, it must also implement an EvtSpbControllerUnlock function. For more information, see Remarks in SPB_CONTROLLER_CONFIG.

While the lock is in effect, the controller must not allow accesses to targets on the bus other than the target designated by the LockRequest parameter.

If the SPB controller driver needs to change the mode of its controller to temporarily override the normal target selection mechanism, it can do so during the EvtSpbControllerLock callback. If this mode change involves a long delay or requires the driver to wait for a device interrupt, the driver should initiate the mode change and then return from the callback without delay. Later, the driver can complete the lock operation in a timer DPC or an interrupt DPC.

If the lock operation completes in a DPC, the SPB controller driver should previously have allocated all the resources that it needs for the lock operation.

An EvtSpbControllerLock callback must avoid failing a lock request. If Driver Verifier is enabled, such a failure will trigger a verifier trap, which will report to the Plug and Play manager that the controller has failed. SpbCx ignores the failure of a lock request and does not try to handle or mitigate the failure.

The EvtSpbControllerLock function does not return a value. Instead, the SPB controller driver indicates the status of the lock operation in the completion status of the I/O request that is identified by the LockRequest parameter. Set the completion status to STATUS_SUCCESS.

SpbCx calls the EvtSpbControllerUnlock event callback function to unlock a controller that was previously locked by an EvtSpbControllerLock callback.

To register an EvtSpbControllerLock callback function, call the SpbDeviceInitialize method.

For more information about the EvtSpbControllerLock function, see Handling Client-Implemented Sequences.

Examples

To define an EvtSpbControllerLock callback function, you must first provide a function declaration that identifies the type of callback function you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define an EvtSpbControllerLock callback function that is named MyEvtSpbControllerLock, use the EVT_SPB_CONTROLLER_LOCK function type, as shown in this code example:

EVT_SPB_CONTROLLER_LOCK  MyEvtSpbControllerLock;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MyEvtSpbControllerLock(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST LockRequest
    )
{ ... }

The EVT_SPB_CONTROLLER_LOCK function type is defined in the Spbcx.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the EVT_SPB_CONTROLLER_LOCK function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For more information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement Value
Minimum supported client Supported starting with Windows 8.
Target Platform Desktop
Header spbcx.h
IRQL Called at IRQL <= DISPATCH_LEVEL.

See also