Função KsEnableEventWithAllocator (ks.h)

Artigo
02/26/2024

A função KsEnableEventWithAllocator permite eventos solicitados por meio de IOCTL_KS_ENABLE_EVENT mas também permite que um retorno de chamada de alocador opcional seja usado para fornecer um buffer para os parâmetros. Ele responde a todos os identificadores de evento definidos pelos conjuntos. Essa função só pode ser chamada em PASSIVE_LEVEL.

Se usado, talvez o filtro precise liberar o buffer de alguma maneira não inconveniente. Observe que os sinalizadores IRP_BUFFERED_IO e IRP_DEALLOCATE_BUFFER não são definidos ao usar um alocador personalizado.

Sintaxe

KSDDKAPI NTSTATUS KsEnableEventWithAllocator(
  [in]           PIRP              Irp,
  [in]           ULONG             EventSetsCount,
  [in]           const KSEVENT_SET *EventSet,
  [in, out]      PLIST_ENTRY       EventsList,
  [in, optional] KSEVENTS_LOCKTYPE EventsFlags,
  [in, optional] PVOID             EventsLock,
  [in, optional] PFNKSALLOCATOR    Allocator,
  [in, optional] ULONG             EventItemSize
);

Parâmetros

[in] Irp

Especifica o IRP com a solicitação de habilitação sendo tratada. O objeto de arquivo associado ao IRP é armazenado com o evento para comparação posterior ao desabilitar o evento.

[in] EventSetsCount

Indica o número de estruturas do conjunto de eventos que estão sendo passadas.

[in] EventSet

Especifica um ponteiro para a lista de informações do conjunto de eventos.

[in, out] EventsList

Se o evento de habilitação for KSEVENT_SET. AddHandler para o conjunto de eventos é NULL, ele deve apontar para o cabeçalho da lista de itens KSEVENT_ENTRY nos quais o evento deve ser adicionado. Essa função pressupõe uma única lista para pelo menos um subconjunto de eventos.

[in, optional] EventsFlags

Especifica KSEVENTS_LOCKTYPE sinalizadores que especificam o tipo de bloqueio de exclusão a ser usado no acesso à lista de eventos, se houver. Se nenhum sinalizador estiver definido, nenhum bloqueio será tomado. Se um manipulador já estiver especificado, esse parâmetro será ignorado.

[in, optional] EventsLock

Se o KSEVENT_SET. AddHandler para o conjunto de eventos que contém o evento que está sendo habilitado é NULL, então isso é usado para sincronizar o acesso à lista. Esse valor poderá ser NULL se nenhum sinalizador for definido em EventsFlags.

[in, optional] Allocator

Opcionalmente, aponta para uma função de alocação que será usada para alocar memória para armazenar os parâmetros de evento.

[in, optional] EventItemSize

Opcionalmente, contém o tamanho de cada estrutura KSEVENT_ITEM em cada lista de eventos. O item de evento pode ser estendido para armazenar informações privadas. Se esse parâmetro for zero, o tamanho da estrutura será considerado normal. Se for maior ou igual a uma estrutura de item de evento, a macro KSEVENT_ITEM_IRP_STORAGE poderá ser usada para retornar um ponteiro para o item de evento para que os dados personalizados possam ser recuperados. Em plataformas de 64 bits, esse parâmetro deve ser um múltiplo de 8.

Retornar valor

O mesmo que KsEnableEvent, que retorna STATUS_SUCCESS se tiver êxito ou um erro específico para o evento que está sendo habilitado se não tiver êxito. A função sempre define o IO_STATUS_BLOCK. Campo de informações do PIRP. Elemento IoStatus dentro do IRP para zero. Ele não define o IO_STATUS_BLOCK. Campo status, nem conclui o IRP.

Comentários

Se o retorno de chamada do alocador opcional for usado, o filtro poderá precisar liberar o buffer de alguma maneira não inconveniente. Observe que os sinalizadores IRP_BUFFERED_IO e IRP_DEALLOCATE_BUFFER não são definidos ao usar um alocador personalizado.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	ks.h (inclua Ks.h)
Biblioteca	Ks.lib

Compartilhar via