Функция обратного вызова PFNKSHANDLER (ks.h)

Статья
02/07/2025

Подпрограмма, предоставляемая мини-driver, вызывается при получении потоковой передачи ядра IOCTL_KS_METHODзапроса свойства get/set. Укажите указатель на этот обработчик в соответствующей KSMETHOD_ITEMструктуре KSPROPERTY_ITEM.

Синтаксис

PFNKSHANDLER Pfnkshandler;

NTSTATUS Pfnkshandler(
  [in]      PIRP Irp,
  [in]      PKSIDENTIFIER Request,
  [in, out] PVOID Data
)
{...}

Параметры

[in] Irp

Указывает IRP, содержащий запрос метода или свойства.

[in] Request

Указывает выровненную копию параметра метода. Обычно это указатель на структуру KSMETHOD или KSPROPERTY.

[in, out] Data

Указывает выровненную копию параметра данных метода или системный адрес исходного параметра данных в зависимости от флага, указанного в структуре KSMETHOD_ITEM метода.

Возвращаемое значение

Возвращает STATUS_SUCCESS, если метод обрабатывается и буфер данных был заполнен на флаг, указанный в KSMETHOD_ITEM. Если возвращаются данные, драйвер должен задать поле Irp->IoStatus.Information, но не следует задавать поле Irp->IoStatus.Status, а также не должно завершить IRP. Помечает ожидание IRP, если оно будет завершено асинхронно.

Кроме того, возвращается STATUS_SOME_NOT_MAPPED, если метод был обработан, но конкретный запрос не был завершен и должен быть завершен функцией вспомогательного вызова. Возвращает любое другое сообщение об ошибке, указывающее, что метод не поддерживается или произошла ошибка параметра.

Замечания

Мини-driver задает адрес этой подпрограммы в элементе MethodHandler структуры KSMETHOD_ITEM.

Объявление обработчика, используемое для KStrMethodHandler и KStrSupportHandler также используется для обработчиков наборов свойств и событий с теми же параметрами и возвращаемыми значениями.

Если вспомогательная функция, например KsMethodHandler вызывает обработчик метода, буфер данных которого определен как буфер записи или изменения, обработчик метода должен задать элемент Information элемента структуры IO_STATUS_BLOCK для элемента IoStatus в параметре IRP (Irp) размер этого буфера данных. Мини-driver задает элемент Flags структуры KSMETHOD_ITEM для метода KSMETHOD_TYPE_WRITE или KSMETHOD_TYPE_MODIFY, чтобы определить буфер данных обработчика метода как запись или изменение соответственно.

В следующем фрагменте кода показан пример реализации обработчика метода, который задает размер возвращаемого буфера данных в IRP:

NTSTATUS
  MethodHandler(PIRP pIrp, PKSIDENTIFIER Request, PVOID Data) {
    NTSTATUS Status = STATUS_UNSUCCESSFUL;
    // Pointer to hold the position on the Irp stack
    PIO_STACK_LOCATION  pIrpStack  = NULL;
    ASSERT(pIrp);
    if(Data) {
        // Modify data here
    }
    // Find the current Irp stack.
    pIrpStack = IoGetCurrentIrpStackLocation(pIrp);
    if(pIrpStack) {
        // Set the size of the returning Irp data.
        pIrp->IoStatus.Information =
          pIrpStack->Parameters.DeviceIoControl.OutputBufferLength;
        Status = STATUS_SUCCESS;
    }
    return(Status);
}

Мини-driver задает адрес этой подпрограммы в элементе GetPropertyHandler элемента структуры KSPROPERTY_ITEM.

Мини-driver задает адрес этой процедуры в SetPropertyHandler член структуры KSPROPERTY_ITEM.

Мини-driver задает адрес этой процедуры в элементе SupportHandler структуры KSMETHOD_ITEM.

Требования

Требование	Ценность
целевая платформа	Настольный
заголовка	ks.h (include Ks.h)

См. также

Поделиться через