Função IoBuildSynchronousFsdRequest (wdm.h)

Artigo
08/08/2023

A rotina IoBuildSynchronousFsdRequest aloca e configura um IRP para uma solicitação de E/S processada de forma síncrona.

Sintaxe

__drv_aliasesMem PIRP IoBuildSynchronousFsdRequest(
  [in]           ULONG            MajorFunction,
  [in]           PDEVICE_OBJECT   DeviceObject,
  [in, out]      PVOID            Buffer,
  [in, optional] ULONG            Length,
  [in, optional] PLARGE_INTEGER   StartingOffset,
  [in]           PKEVENT          Event,
  [out]          PIO_STATUS_BLOCK IoStatusBlock
);

Parâmetros

[in] MajorFunction

O código de função principal para o IRP. Esse código pode ser IRP_MJ_PNP, IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_FLUSH_BUFFERS ou IRP_MJ_SHUTDOWN.

[in] DeviceObject

Um ponteiro para a estrutura de DEVICE_OBJECT do objeto de dispositivo do driver inferior, que representa o dispositivo de destino.

[in, out] Buffer

Um ponteiro para um buffer de dados. Se MajorFunction for IRP_MJ_WRITE, o buffer conterá dados a serem gravados. Se MajorFunction for IRP_MJ_READ, o buffer receberá dados. Se MajorFunction for IRP_MJ_FLUSH_BUFFERS ou IRP_MJ_SHUTDOWN, esse parâmetro deverá ser NULL.

[in, optional] Length

O comprimento, em bytes, do buffer apontado por Buffer. Para dispositivos como discos, esse valor deve ser um múltiplo inteiro do tamanho do setor. Começando com Windows 8, o tamanho do setor pode ser de 4.096 ou 512 bytes. Em versões anteriores do Windows, o tamanho do setor é sempre de 512 bytes. Esse parâmetro é necessário para solicitações de leitura e gravação, mas deve ser zero para solicitações de liberação e desligamento.

[in, optional] StartingOffset

Um ponteiro para o deslocamento no disco, para solicitações de leitura e gravação. As unidades e o significado desse valor são específicos do driver. Esse parâmetro é necessário para solicitações de leitura e gravação, mas deve ser zero para solicitações de liberação e desligamento.

[in] Event

Um ponteiro para um objeto de evento alocado pelo chamador e inicializado. O gerenciador de E/S define o evento como o estado Sinalizado quando um driver de nível inferior conclui a operação solicitada. Depois de chamar IoCallDriver, o driver pode aguardar o objeto de evento.

[out] IoStatusBlock

Um ponteiro para um local que recebe o bloco de status de E/S definido quando o IRP é concluído por um driver de nível inferior.

Retornar valor

Se a operação for bem-sucedida, IoBuildSynchronousFsdRequest retornará um ponteiro para uma estrutura IRP inicializada, com o local de pilha de E/S do driver mais baixo configurado a partir dos parâmetros fornecidos. Caso contrário, a rotina retornará NULL.

Comentários

Um FSD (driver do sistema de arquivos) ou outro driver de nível superior pode chamar IoBuildSynchronousFsdRequest para configurar IRPs que ele envia de forma síncrona para drivers de nível inferior.

IoBuildSynchronousFsdRequest aloca e configura um IRP que solicita drivers de nível inferior para executar uma operação síncrona de leitura, gravação, liberação ou desligamento. O IRP contém informações suficientes para iniciar a operação.

Drivers de nível inferior podem impor restrições aos parâmetros fornecidos a essa rotina. Por exemplo, os drivers de disco podem exigir que os valores fornecidos para Length e StartingOffset sejam múltiplos inteiros do tamanho do setor do dispositivo.

Depois de chamar IoBuildSynchronousFsdRequest para criar uma solicitação, o driver deve chamar IoCallDriver para enviar a solicitação para o driver mais baixo. Se IoCallDriver retornar STATUS_PENDING, o driver deverá aguardar a conclusão do IRP chamando KeWaitForSingleObject no Evento especificado. A maioria dos drivers não precisa definir uma rotina IoCompletion para o IRP.

Os IRPs criados por IoBuildSynchronousFsdRequest devem ser concluídos por uma chamada de driver para IoCompleteRequest. Um driver que chama IoBuildSynchronousFsdRequest não deve chamar IoFreeIrp, pois o gerenciador de E/S libera esses IRPs síncronos depois que IoCompleteRequest é chamado.

IoBuildSynchronousFsdRequest enfileira os IRPs que ele cria para uma fila IRP específica para o thread atual. Se o thread for encerrado, o gerenciador de E/S cancelará o IRP.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Regras de conformidade da DDI	ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDIs(storport), IoBuildSynchronousFsdRequestNoFree(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)