WDF_WMI_BUFFER_APPEND_STRING関数 (wdfwmi.h)

[KMDF にのみ適用]

WDF_WMI_BUFFER_APPEND_STRING関数は、指定した Unicode 文字列を 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を返します。 コピー先バッファーが小さすぎて String パラメーターで指定されている Unicode 文字列を保持するには、関数は STATUS_BUFFER_TOO_SMALLを返します。

注釈

WMI では、 EvtWmiInstanceQueryInstance コールバック関数が返す文字列の前にバイト数が必要です。 WDF_WMI_BUFFER_APPEND_STRING関数はバイト数を計算し、それをコピー先バッファーに格納してから、UNICODE_STRING構造体からコピー先バッファーに文字列をコピーします。

WDF_WMI_BUFFER_APPEND_STRINGが返されると、RequiredSize パラメーターが指す場所には、バッファーに書き込まれた合計バイト数が格納されます。 文字列の後に続く最初のバッファー アドレスを検索するために、ドライバーは、Wdfcore.h で定義されているWDF_PTR_ADD_OFFSET マクロに RequiredSize 値を渡すことができます。

例

シリアル サンプル ドライバー のコード例を次に示します。 この例は、デバイスのシンボリック名を取得し、その名前をコールバック関数の出力バッファーにコピーする 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
                                        );
}

要件

関連項目

EvtWmiInstanceQueryInstance

UNICODE_STRING