EVT_SPB_TARGET_CONNECT callback function (spbcx.h)

Article
10/21/2021

An SPB controller driver's EvtSpbTargetConnect event callback function opens a connection to a target device on the bus.

Syntax

EVT_SPB_TARGET_CONNECT EvtSpbTargetConnect;

NTSTATUS EvtSpbTargetConnect(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target
)
{...}

Parameters

[in] Controller

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

[in] Target

An SPBTARGET handle to the target to open. The target is a peripheral device or port that is attached to the bus.

Return value

EvtSpbTargetConnect returns STATUS_SUCCESS if the driver successfully opens the connection to the target. Otherwise, the function returns an appropriate NTSTATUS error code.

Remarks

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

The SPB framework extension (SpbCx) manages the I/O queue for the SPB controller. If the SPB controller driver registers an EvtSpbTargetConnect callback function, SpbCx calls this function when a client (peripheral driver) of the controller sends an IRP_MJ_CREATE request to open a connection to a target device on the bus. If the EvtSpbTargetConnect function returns an error code, SpbCx fails the IRP_MJ_CREATE request. A client that successfully opens a connection to a target has exclusive access to the target until the connection is closed.

Call the SpbTargetGetConnectionParameters method to get the connection parameters for the target device. An SPB controller driver typically calls this method from the driver's EvtSpbTargetConnect function. SpbTargetGetConnectionParameters writes the connection parameters to a caller-supplied SPB_CONNECTION_PARAMETERS structure. The ConnectionParameters member of this structure is a pointer to a buffer that contains the connection settings for the target device. The driver uses these settings to configure the SPB controller to communicate with the device. For more information, see How to Get the Connection Settings for a Device.

The EvtSpbTargetConnect callback function is called synchronously from the context of the client thread that requests the connection to the target.

SpbCx calls the EvtSpbTargetDisconnect callback function to close a target connection that was previously opened by an EvtSpbTargetConnect callback.

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

Examples

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

EVT_SPB_TARGET_CONNECT  MyEvtSpbTargetConnect;

Then, implement your callback function as follows:

_Use_decl_annotations_
NTSTATUS
  MyEvtSpbTargetConnect(
    WDFDEVICE Controller,
    SPBTARGET Target
    )
{ ... }

The EVT_SPB_TARGET_CONNECT 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_CONNECT 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.