EVT_SPB_TARGET_CONNECT função de retorno de chamada (spbcx.h)

Artigo
02/26/2024

Uma função de retorno de chamada de evento EvtSpbTargetConnect do driver de controlador SPB abre uma conexão com um dispositivo de destino no barramento.

Sintaxe

EVT_SPB_TARGET_CONNECT EvtSpbTargetConnect;

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

Parâmetros

[in] Controller

Um identificador WDFDEVICE para o objeto de dispositivo de estrutura que representa o controlador SPB.

[in] Target

Um identificador SPBTARGET para o destino a ser aberto. O destino é um dispositivo periférico ou uma porta anexada ao barramento.

Retornar valor

EvtSpbTargetConnect retornará STATUS_SUCCESS se o driver abrir com êxito a conexão com o destino. Caso contrário, a função retornará um código de erro NTSTATUS apropriado.

Comentários

A implementação dessa função pelo driver do controlador SPB é opcional.

A extensão da estrutura SPB (SpbCx) gerencia a fila de E/S para o controlador SPB. Se o driver do controlador SPB registrar uma função de retorno de chamada EvtSpbTargetConnect , o SpbCx chamará essa função quando um cliente (driver periférico) do controlador enviar uma solicitação IRP_MJ_CREATE para abrir uma conexão com um dispositivo de destino no barramento. Se a função EvtSpbTargetConnect retornar um código de erro, o SpbCx falhará na solicitação de IRP_MJ_CREATE . Um cliente que abre com êxito uma conexão com um destino tem acesso exclusivo ao destino até que a conexão seja fechada.

Chame o método SpbTargetGetConnectionParameters para obter os parâmetros de conexão para o dispositivo de destino. Um driver de controlador SPB normalmente chama esse método da função EvtSpbTargetConnect do driver. SpbTargetGetConnectionParameters grava os parâmetros de conexão em uma estrutura de SPB_CONNECTION_PARAMETERS fornecida pelo chamador. O membro ConnectionParameters dessa estrutura é um ponteiro para um buffer que contém as configurações de conexão para o dispositivo de destino. O driver usa essas configurações para configurar o controlador SPB para se comunicar com o dispositivo. Para obter mais informações, consulte Como obter as configurações de conexão de um dispositivo.

A função de retorno de chamada EvtSpbTargetConnect é chamada de forma síncrona do contexto do thread do cliente que solicita a conexão com o destino.

O SpbCx chama a função de retorno de chamada EvtSpbTargetDisconnect para fechar uma conexão de destino que foi aberta anteriormente por um retorno de chamada EvtSpbTargetConnect .

Para registrar uma função de retorno de chamada EvtSpbTargetConnect , chame o método SpbDeviceInitialize .

Exemplos

Para definir uma função de retorno de chamada EvtSpbTargetConnect , primeiro você deve fornecer uma declaração de função que identifique o tipo de função de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função de retorno de chamada EvtSpbTargetConnect chamada MyEvtSpbTargetConnect, use o tipo de função EVT_SPB_TARGET_CONNECT, conforme mostrado neste exemplo de código:

EVT_SPB_TARGET_CONNECT  MyEvtSpbTargetConnect;

Em seguida, implemente a função de retorno de chamada da seguinte maneira:

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

O tipo de função EVT_SPB_TARGET_CONNECT é definido no arquivo de cabeçalho Spbcx.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função EVT_SPB_TARGET_CONNECT no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers KMDF. Para obter mais informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte começando com Windows 8.
Plataforma de Destino	Área de Trabalho
Cabeçalho	spbcx.h
IRQL	Chamado em PASSIVE_LEVEL.