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

Artigo
02/07/2025

Uma função de retorno de chamada de evento EvtSpbControllerLock do driver de controlador SPB bloqueia o controlador SPB para acessos de um único dispositivo de destino no barramento.

Sintaxe

EVT_SPB_CONTROLLER_LOCK EvtSpbControllerLock;

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

Parâmetros

[in] Controller

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

[in] Target

Um identificador SPBTARGET para o destino dessa solicitação de E/S. O destino é um dispositivo periférico ou uma porta anexada ao barramento. A extensão da estrutura SPB (SpbCx) atribuiu anteriormente esse identificador ao destino no EvtSpbTargetConnect retorno de chamada que abriu a conexão com o destino.

[in] LockRequest

Um identificador SPBREQUEST para uma solicitação de controle de E/S para bloquear o controlador. O driver do controlador SPB deve concluir essa solicitação executando a operação solicitada ou retornando um status de erro. Para obter mais informações, consulte Comentários.

Valor de retorno

Nenhum

Observações

O 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 EvtSpbControllerLock, o SpbCx chamará essa função quando um cliente (driver periférico) do controlador enviar uma solicitação IOCTL_SPB_LOCK_CONTROLLER para um destino no barramento. O valor do parâmetro LockRequest é um identificador que encapsula essa solicitação.

As funções EvtSpbControllerLock e EvtSpbControllerUnlock executam operações complementares. Ambas as funções são opcionais. Se o driver do controlador SPB implementar uma função EvtSpbControllerUnlock, o driver não será necessário para implementar uma função de EvtSpbControllerLock, mas poderá fazê-lo. No entanto, se o driver do controlador SPB implementar uma função EvtSpbControllerLock, ele também deverá implementar uma função de EvtSpbControllerUnlock. Para obter mais informações, consulte Comentários em SPB_CONTROLLER_CONFIG.

Embora o bloqueio esteja em vigor, o controlador não deve permitir acessos a destinos no barramento que não sejam o destino designado pelo parâmetro LockRequest.

Se o driver do controlador SPB precisar alterar o modo de seu controlador para substituir temporariamente o mecanismo de seleção de destino normal, ele poderá fazê-lo durante o EvtSpbControllerLock retorno de chamada. Se essa alteração de modo envolver um longo atraso ou exigir que o driver aguarde uma interrupção do dispositivo, o driver deverá iniciar a alteração de modo e retornar do retorno de chamada sem atraso. Posteriormente, o driver pode concluir a operação de bloqueio em um DPC de temporizador ou em um DPC de interrupção.

Se a operação de bloqueio for concluída em um DPC, o driver do controlador SPB deverá ter alocado anteriormente todos os recursos necessários para a operação de bloqueio.

Um retorno de chamada EvtSpbControllerLock deve evitar falha em uma solicitação de bloqueio. Se Verificador de Driver estiver habilitado, essa falha disparará uma armadilha do verificador, que relatará ao gerenciador plug and play que o controlador falhou. O SpbCx ignora a falha de uma solicitação de bloqueio e não tenta manipular nem atenuar a falha.

A função EvtSpbControllerLock não retorna um valor. Em vez disso, o driver do controlador SPB indica o status da operação de bloqueio no status de conclusão da solicitação de E/S identificada pelo parâmetro LockRequest. Defina o status de conclusão como STATUS_SUCCESS.

O SpbCx chama a função de retorno de chamada de evento EvtSpbControllerUnlock para desbloquear um controlador bloqueado anteriormente por um retorno de chamada EvtSpbControllerLock.

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

Para obter mais informações sobre a função EvtSpbControllerLock, consulte Handling Client-Implemented Sequences.

Exemplos

Para definir uma função de retorno de chamada EvtSpbControllerLock, 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 encontram erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função de retorno de chamada EvtSpbControllerLock denominada MyEvtSpbControllerLock, use o tipo de função EVT_SPB_CONTROLLER_LOCK, conforme mostrado neste exemplo de código:

EVT_SPB_CONTROLLER_LOCK  MyEvtSpbControllerLock;

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

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

O tipo de função EVT_SPB_CONTROLLER_LOCK é 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_CONTROLLER_LOCK 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
de cliente com suporte mínimo	Com suporte a partir do Windows 8.
da Plataforma de Destino	Área de trabalho
cabeçalho	spbcx.h
IRQL	Chamado no <DO IRQL = DISPATCH_LEVEL.

Partilhar via