EVT_SPB_TARGET_DISCONNECT callback function (spbcx.h)

Article
10/21/2021

An SPB controller driver's EvtSpbTargetDisconnect event callback function closes a connection to a target device that was previously opened by a call to the driver's EvtSpbTargetConnect event callback function.

Syntax

EVT_SPB_TARGET_DISCONNECT EvtSpbTargetDisconnect;

void EvtSpbTargetDisconnect(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target
)
{...}

Parameters

[in] Controller

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

[in] Target

A SPBTARGET handle to the target to close. 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.

Return value

None

Remarks

Implementation of this function by the SPB controller driver is optional.

SpbCx manages the I/O queue for the SPB controller. If the SPB controller driver registers an EvtSpbTargetDisconnect callback function, SpbCx calls this function when a client (peripheral driver) of the controller driver sends an IRP_MJ_CLOSE request to close an SPBTARGET handle. This handle represents a connection to a target device on the bus that the client opened in a previous IRP_MJ_CREATE request. If the EvtSpbTargetDisconnect function returns an error code, SpbCx fails the IRP_MJ_CLOSE request.

The EvtSpbTargetDisconnect function is called synchronously from the context of the client's closing thread after all client-initiated I/O operations have ended and after the client has unlocked the controller (if the client previously locked the controller).

If the SPB controller driver has allocated I/O requests and sent them to the next-lower driver in the I/O-request chain for the target device, the EvtSpbTargetDisconnect function should cancel these requests before it returns.

A client driver's DispatchCleanup and CreateProcessNotifyEx callback routines can be called at any time after the EvtSpbTargetDisconnect callback returns. When the client driver's process exits, its CreateProcessNotifyEx routine is called just before the last thread to exit the process is destroyed.

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

Examples

To define an EvtSpbTargetDisconnect 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 EvtSpbTargetDisconnect callback function that is named MyEvtSpbTargetDisconnect, use the EVT_SPB_TARGET_DISCONNECT function type, as shown in this code example:

EVT_SPB_TARGET_DISCONNECT  MyEvtSpbTargetDisconnect;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MyEvtSpbTargetDisconnect(
    WDFDEVICE Controller,
    SPBTARGET Target
    )
{ ... }

The EVT_SPB_TARGET_DISCONNECT 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_TARGET_DISCONNECT 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 PASSIVE_LEVEL.