WDF_WMI_BUFFER_APPEND_STRING-Funktion (wdfwmi.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die WDF_WMI_BUFFER_APPEND_STRING-Funktion kopiert eine angegebene Unicode-Zeichenfolge in einen angegebenen Puffer im von WMI benötigten Format.

Syntax

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

Parameter

[out] Buffer

Ein Zeiger auf einen Zielpuffer, der die Zeichenfolge empfängt.

[in] BufferLength

Die Länge des Zielpuffers in Bytes, der die Zeichenfolge empfängt.

[in] String

Ein Zeiger auf eine UNICODE_STRING Struktur, die die zu kopierende Zeichenfolge enthält.

[out] RequiredSize

Ein Zeiger auf eine Position, die die Anzahl der Bytes empfängt, die zum Speichern der angegebenen Zeichenfolge im Zielpuffer erforderlich sind.

Rückgabewert

WDF_WMI_BUFFER_APPEND_STRING gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Wenn der Zielpuffer zu klein ist, um die Unicode-Zeichenfolge, die der String Parameter angibt, zu enthalten, gibt die Funktion STATUS_BUFFER_TOO_SMALL zurück.

Bemerkungen

WMI erfordert, dass Zeichenfolgen, die eine EvtWmiInstanceQueryInstance Rückruffunktion zurückgegeben werden, einer Byteanzahl vorangestellt werden. Die WDF_WMI_BUFFER_APPEND_STRING-Funktion berechnet die Byteanzahl, speichert sie im Zielpuffer und kopiert dann die Zeichenfolge aus der UNICODE_STRING Struktur in den Zielpuffer.

Wenn WDF_WMI_BUFFER_APPEND_STRING zurückgegeben wird, verweist der Speicherort, auf den der RequiredSize Parameter verweist, auf die Gesamtzahl der Bytes, die in den Puffer geschrieben wurden. Um die erste Pufferadresse zu finden, die auf die Zeichenfolge folgt, kann ihr Treiber den RequiredSize-wert an das WDF_PTR_ADD_OFFSET Makro übergeben, das in Wdfcore.hdefiniert ist.

Beispiele

Das folgende Codebeispiel stammt aus dem Serial Beispieltreiber. Dieses Beispiel ist eine EvtWmiInstanceQueryInstance Rückruffunktion, die den symbolischen Namen eines Geräts abruft und den Namen in den Ausgabepuffer der Rückruffunktion kopiert.

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

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Header-	wdfwmi.h (einschließen Wdf.h)
Library	Nichts

Siehe auch

EvtWmiInstanceQueryInstance

UNICODE_STRING

Freigeben über