функция обратного вызова PO_FX_POWER_CONTROL_CALLBACK (wdm.h)

Статья
03/08/2023

Подпрограмма обратного вызова PowerControlCallback выполняет операцию управления питанием, запрошенную платформой управления питанием (PoFx).

Синтаксис

PO_FX_POWER_CONTROL_CALLBACK PoFxPowerControlCallback;

NTSTATUS PoFxPowerControlCallback(
                  PVOID DeviceContext,
  [in]            LPCGUID PowerControlCode,
  [in, optional]  PVOID InBuffer,
  [in]            SIZE_T InBufferSize,
  [out, optional] PVOID OutBuffer,
  [in]            SIZE_T OutBufferSize,
  [out, optional] PSIZE_T BytesReturned
)
{...}

Параметры

DeviceContext

[in] PowerControlCode

Указатель на код элемента управления питанием. Этот код представляет собой значение GUID, указывающее запрошенную операцию.

[in, optional] InBuffer

Указатель на буфер, содержащий входные данные для операции. Формат данных в этом буфере зависит от кода управления питанием, заданного параметром PowerControlCode . Параметр InBuffer является необязательным и может быть указан как NULL, если указанная операция не требует входных данных.

[in] InBufferSize

Размер входного буфера в байтах, на который указывает параметр InBuffer . Если InBuffer имеет значение NULL, этот параметр равен нулю.

[out, optional] OutBuffer

Указатель на буфер, в который подпрограмма обратного вызова записывает выходные данные операции. Формат данных в этом буфере зависит от кода управления питанием, заданного параметром PowerControlCode . Параметр OutBuffer является необязательным и может быть указан как NULL, если указанная операция не создает выходных данных.

[in] OutBufferSize

Размер выходного буфера в байтах, на который указывает параметр OutBuffer . Если OutBuffer имеет значение NULL, этот параметр равен нулю.

[out, optional] BytesReturned

Указатель на расположение, в которое подпрограмма записывает количество байтов данных, записанных в буфер, на который указывает OutBuffer. Число записанных байтов должно быть меньше или равно OutBufferSize. Этот параметр является необязательным и может быть указан как NULL, если вызывающей объекту не нужно знать, сколько байтов было записано в выходной буфер.

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

Подпрограмма PowerControlCallback возвращает STATUS_SUCCESS, если вызов выполнен успешно. В противном случае возвращается соответствующий код ошибки.

PoFx вызывает эту подпрограмму для отправки запроса на управление питанием непосредственно драйверу устройства. Запрос управления питанием аналогичен запросу на управление вводом-выводом (IOCTL). Однако, в отличие от IOCTL, запрос на управление питанием отправляется непосредственно драйверу и не наблюдается другими драйверами устройств в стеке устройств. Во время вызова PowerControlCallback драйвер синхронно выполняет запрошенную операцию.

Эта подпрограмма является необязательной. Драйвер устройства, не поддерживающий операции управления питанием, не требуется для реализации подпрограммы PowerControlCallback .

Драйвер устройства может вызвать подпрограмму PoFxPowerControl для отправки запроса на управление питанием в PoFx.

Дополнительные сведения о запросах на управление питанием см. в разделе PoFxPowerControl.

Примеры

Чтобы определить подпрограмму обратного вызова PowerControlCallback , необходимо сначала предоставить объявление функции, определяющее тип определяемой процедуры обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить подпрограмму обратного вызова PowerControlCallback с именем MyPowerControlCallback, используйте тип PO_FX_POWER_CONTROL_CALLBACK, как показано в следующем примере кода:

PO_FX_POWER_CONTROL_CALLBACK MyPowerControlCallback;

Затем реализуйте процедуру обратного вызова следующим образом:

_Use_decl_annotations_
NTSTATUS
  MyPowerControlCallback(
    PVOID Context,
    LPCGUID PowerControlCode,
    PVOID InBuffer,
    SIZE_T InBufferSize,
    PVOID OutBuffer,
    SIZE_T OutBufferSize,
    PSIZE_T BytesReturned
    )
  {
      // Function body
  }

Тип функции PO_FX_POWER_CONTROL_CALLBACK определен в файле заголовка Wdm.h. Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку _Use_decl_annotations_ в определение функции. Заметка _Use_decl_annotations_ гарантирует, что будут использоваться заметки, которые применяются к типу функции PO_FX_POWER_CONTROL_CALLBACK в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов WDM. Сведения о _Use_decl_annotations_см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается начиная с Windows 8.
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wudfwdm.h)
IRQL	Вызывается по адресу IRQL <= DISPATCH_LEVEL.

См. также раздел

PO_FX_DEVICE

PoFxPowerControl

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