функция WDF_WMI_BUFFER_APPEND_STRING (wdfwmi.h)

Статья
02/07/2025

[Применимо только к KMDF]

Функция WDF_WMI_BUFFER_APPEND_STRING копирует указанную строку Юникода в указанный буфер в формате, который требуется WMI.

Синтаксис

NTSTATUS WDF_WMI_BUFFER_APPEND_STRING(
  [out] PVOID            Buffer,
  [in]  ULONG            BufferLength,
  [in]  PCUNICODE_STRING String,
  [out] PULONG           RequiredSize
);

Параметры

[out] Buffer

Указатель на целевой буфер, получающий строку.

[in] BufferLength

Длина в байтах целевого буфера, получающего строку.

[in] String

Указатель на структуру UNICODE_STRING, содержащую скопированную строку.

[out] RequiredSize

Указатель на расположение, которое получает количество байтов, необходимых для хранения указанной строки в целевом буфере.

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

WDF_WMI_BUFFER_APPEND_STRING возвращает STATUS_SUCCESS, если операция выполнена успешно. Если целевой буфер слишком мал для хранения строки Юникода, указанной параметром строки, функция возвращает STATUS_BUFFER_TOO_SMALL.

Замечания

Для WMI требуется, чтобы строки, возвращаемые функцией обратного вызова EvtWmiInstanceQueryInstance, должны предшествовать числу байтов. Функция WDF_WMI_BUFFER_APPEND_STRING вычисляет число байтов, сохраняет его в целевом буфере, а затем копирует строку из структуры UNICODE_STRING в целевой буфер.

Когда WDF_WMI_BUFFER_APPEND_STRING возвращается, расположение, которое указывает параметр RequiredSize, содержит общее количество байтов, записанных в буфер. Чтобы найти первый адрес буфера, следующий за строкой, драйвер может передать значение RequiredSize макросу WDF_PTR_ADD_OFFSET, определенному в Wdfcore.h.

Примеры

В следующем примере кода используется пример драйвера serial. В этом примере используется функция обратного вызова EvtWmiInstanceQueryInstance, которая получает символическое имя устройства и копирует имя в выходной буфер функции обратного вызова.

NTSTATUS
EvtWmiQueryPortName(
    IN  WDFWMIINSTANCE WmiInstance,
    IN  ULONG OutBufferSize,
    IN  PVOID OutBuffer,
    OUT PULONG BufferUsed
    )
{
    WDFDEVICE device;
    PSERIAL_DEVICE_EXTENSION pDevExt;
    WCHAR pRegName[SYMBOLIC_NAME_LENGTH];
    UNICODE_STRING string;
    USHORT nameSize = sizeof(pRegName);
    NTSTATUS status;

    PAGED_CODE();

    device = WdfWmiInstanceGetDevice(WmiInstance);
    pDevExt = SerialGetDeviceExtension(device);

    status = SerialReadSymName(
                               device,
                               pRegName,
                               &nameSize
                               );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    RtlInitUnicodeString(
                         &string,
                         pRegName
                         );
    return WDF_WMI_BUFFER_APPEND_STRING(
                                        OutBuffer,
                                        OutBufferSize,
                                        &string,
                                        BufferUsed
                                        );
}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
заголовка	wdfwmi.h (include Wdf.h)
библиотеки	Никакой

См. также

EvtWmiInstanceQueryInstance

UNICODE_STRING

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