WDF_WMI_BUFFER_APPEND_STRING function (wdfwmi.h)

Article
10/21/2021

[Applies to KMDF only]

The WDF_WMI_BUFFER_APPEND_STRING function copies a specified Unicode string into a specified buffer in the format that WMI requires.

Syntax

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

Parameters

[out] Buffer

A pointer to a destination buffer that receives the string.

[in] BufferLength

The length, in bytes, of the destination buffer that receives the string.

[in] String

A pointer to a UNICODE_STRING structure that contains the string to be copied.

[out] RequiredSize

A pointer to a location that receives the number of bytes that are required to store the specified string in the destination buffer.

Return value

WDF_WMI_BUFFER_APPEND_STRING returns STATUS_SUCCESS if the operation succeeds. If the destination buffer is too small to hold the Unicode string that the String parameter specifies, the function returns STATUS_BUFFER_TOO_SMALL.

Remarks

WMI requires that strings that an EvtWmiInstanceQueryInstance callback function returns be preceded by a byte count. The WDF_WMI_BUFFER_APPEND_STRING function calculates the byte count, stores it in the destination buffer, and then copies the string from the UNICODE_STRING structure into the destination buffer.

When WDF_WMI_BUFFER_APPEND_STRING returns, the location that the RequiredSize parameter points to contains the total number of bytes that were written to the buffer. To find the first buffer address that follows the string, your driver can pass the RequiredSize value to the WDF_PTR_ADD_OFFSET macro that is defined in Wdfcore.h.

Examples

The following code example is from the Serial sample driver. This example is an EvtWmiInstanceQueryInstance callback function that obtains a device's symbolic name and copies the name into the callback function's output buffer.

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
                                        );
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfwmi.h (include Wdf.h)
Library	None