WDF_WMI_BUFFER_APPEND_STRING函式 (wdfwmi.h)

[僅適用於 KMDF]

WDF_WMI_BUFFER_APPEND_STRING函式會以 WMI 所需的格式，將指定的 Unicode 字串複製到指定的緩衝區。

語法

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。 如果目的地緩衝區太小而無法保存 String 參數指定的 Unicode 字串，函式會傳回STATUS_BUFFER_TOO_SMALL。

備註

WMI 要求 EvtWmiInstanceQueryInstance 回呼函式傳回的字串前面加上位元組計數。 WDF_WMI_BUFFER_APPEND_STRING 函式會計算位元組計數、將其儲存在目的地緩衝區中，然後將字元串從UNICODE_STRING結構複製到目的地緩衝區。

當 WDF_WMI_BUFFER_APPEND_STRING 傳回時， RequiredSize 參數指向的位置會包含寫入緩衝區的位元組總數。 若要尋找字串後面的第一個緩衝區位址，您的驅動程式可以將 RequiredSize 值傳遞至 Wdfcore.h 中定義的WDF_PTR_ADD_OFFSET宏。

範例

下列程式代碼範例來自 序列 範例驅動程式。 此範例是 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
                                        );
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
標頭	wdfwmi.h (包含 Wdf.h)
程式庫	無

另請參閱

EvtWmiInstanceQueryInstance

UNICODE_STRING