Skip to content

Latest commit

 

History

History
128 lines (82 loc) · 6.5 KB

nc-spbcx-evt_spb_target_connect.md

File metadata and controls

128 lines (82 loc) · 6.5 KB
Raw
UID title description old-location tech.root ms.date keywords ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames f1_keywords topic_type api_type api_location api_name
NC:spbcx.EVT_SPB_TARGET_CONNECT
EVT_SPB_TARGET_CONNECT (spbcx.h)
An SPB controller driver's EvtSpbTargetConnect event callback function opens a connection to a target device on the bus.
spb\evtspbtargetconnect.htm
SPB
04/30/2018
EVT_SPB_TARGET_CONNECT callback function
EVT_SPB_TARGET_CONNECT, EVT_SPB_TARGET_CONNECT callback, EvtSpbTargetConnect, EvtSpbTargetConnect callback function [Buses], SPB.evtspbtargetconnect, spbcx/EvtSpbTargetConnect
spbcx.h
Desktop
Supported starting with Windows 8.
Called at PASSIVE_LEVEL.
Windows
EVT_SPB_TARGET_CONNECT
spbcx/EVT_SPB_TARGET_CONNECT
APIRef
kbSyntax
UserDefined
Spbcx.h
EVT_SPB_TARGET_CONNECT

EVT_SPB_TARGET_CONNECT callback function

-description

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

-parameters

-param Controller [in]

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

-param Target [in]

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

-returns

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.

-see-also

EvtSpbTargetDisconnect

IRP_MJ_CREATE

SPBTARGET

SPB_CONNECTION_PARAMETERS

SpbDeviceInitialize