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巨集。

例子

下列程式代碼範例來自 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 （包括 Wdf.h）
連結庫	沒有

另請參閱

EvtWmiInstanceQueryInstance

UNICODE_STRING