Función KsEnableEventWithAllocator (ks.h)

Artículo
08/07/2023

La función KsEnableEventWithAllocator habilita los eventos solicitados a través de IOCTL_KS_ENABLE_EVENT, pero también permite usar una devolución de llamada de asignador opcional para proporcionar un búfer para los parámetros. Responde a todos los identificadores de eventos definidos por los conjuntos. Solo se puede llamar a esta función en PASSIVE_LEVEL.

Si se usa, es posible que el filtro tenga que liberar el búfer de alguna manera no convencional. Tenga en cuenta que las marcas IRP_BUFFERED_IO y IRP_DEALLOCATE_BUFFER no se establecen al usar un asignador personalizado.

Sintaxis

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 el IRP con la solicitud enable que se está controlando. El objeto de archivo asociado al IRP se almacena con el evento para su posterior comparación al deshabilitar el evento.

[in] EventSetsCount

Indica el número de estructuras del conjunto de eventos que se pasan.

[in] EventSet

Especifica un puntero a la lista de información del conjunto de eventos.

[in, out] EventsList

Si la KSEVENT_SET del evento de habilitación. AddHandler para el conjunto de eventos es NULL, debe apuntar al encabezado de la lista de KSEVENT_ENTRY elementos en los que se va a agregar el evento. Esta función supone una sola lista para al menos un subconjunto de eventos.

[in, optional] EventsFlags

Especifica KSEVENTS_LOCKTYPE marcas que especifican el tipo de bloqueo de exclusión que se va a usar para acceder a la lista de eventos, si existe. Si no se establece ninguna marca, no se toma ningún bloqueo. Si ya se especifica un controlador, se omite este parámetro.

[in, optional] EventsLock

Si el KSEVENT_SET. AddHandler para el conjunto de eventos que contiene el evento que se está habilitando es NULL y, a continuación, se usa para sincronizar el acceso a la lista. Este valor puede ser NULL si no hay ninguna marca establecida en EventsFlags.

[in, optional] Allocator

Opcionalmente, apunta a una función de asignación que se usará para asignar memoria para almacenar los parámetros de evento.

[in, optional] EventItemSize

Opcionalmente, contiene el tamaño de cada estructura de KSEVENT_ITEM en cada lista de eventos. El elemento de evento se puede extender para almacenar información privada. Si este parámetro es cero, se supone que el tamaño de la estructura es normal. Si es mayor o igual que una estructura de elementos de evento, se puede usar la macro KSEVENT_ITEM_IRP_STORAGE para devolver un puntero al elemento de evento para que se puedan recuperar los datos personalizados. En plataformas de 64 bits, este parámetro debe ser un múltiplo de 8.

Valor devuelto

Igual que KsEnableEvent, que devuelve STATUS_SUCCESS si se ejecuta correctamente, o un error específico del evento que se está habilitando si no se realiza correctamente. La función siempre establece el IO_STATUS_BLOCK. Campo de información del PIRP. Elemento IoStatus dentro del IRP a cero. No establece el IO_STATUS_BLOCK. Campo de estado, ni completa el IRP.

Comentarios

Si se usa la devolución de llamada del asignador opcional, es posible que el filtro tenga que liberar el búfer de alguna manera no constante. Tenga en cuenta que las marcas IRP_BUFFERED_IO y IRP_DEALLOCATE_BUFFER no se establecen al usar un asignador personalizado.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	ks.h (incluye Ks.h)
Library	Ks.lib

Compartir a través de