WdfStringCreate-Funktion (wdfstring.h)

  • Artikel

[Gilt für KMDF und UMDF]

Die WdfStringCreate-Methode erstellt ein Frameworkzeichenfolgenobjekt und weist dem Objekt optional eine angegebene Unicode-Zeichenfolge zu.

Syntax

NTSTATUS WdfStringCreate(
  [in, optional] PCUNICODE_STRING       UnicodeString,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringAttributes,
  [out]          WDFSTRING              *String
);

Parameter

[in, optional] UnicodeString

Ein Zeiger auf eine UNICODE_STRING-Struktur , die eine Unicode-Zeichenfolgenkonstante enthält. Das Framework kopiert die Zeichenfolge in das neue Frameworkzeichenfolgenobjekt. Dieser Zeiger ist optional und kann NULL sein.

[in, optional] StringAttributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur , die vom Treiber bereitgestellte Attribute für das neue Zeichenfolgenobjekt enthält. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] String

Ein Zeiger auf eine Position, die ein Handle auf das neue Zeichenfolgenobjekt empfängt.

Rückgabewert

WdfStringCreate gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode Beschreibung
STATUS_INVALID_DEVICE_REQUEST

WdfStringCreate wurde bei IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER
 Ein ungültiger Parameter wurde angegeben.
STATUS_INSUFFICIENT_RESOURCES
 Ein Zeichenfolgenobjekt konnte nicht zugeordnet werden.
 

Eine Liste mit anderen Rückgabewerten, die die WdfStringCreate-Methode möglicherweise zurückgibt, finden Sie unter Fehler beim Erstellen von Frameworkobjekten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Hinweise

Das Übergeordnete Standardobjekt für Frameworkzeichenfolgenobjekte ist das Frameworktreiberobjekt des Treibers. Es sei denn, die Zeichenfolge ist dem Treiber zugeordnet, sollte ihr Treiber das ParentObject-Element der WDF_OBJECT_ATTRIBUTES-Struktur auf ein Objekt festlegen, das den Bereich der Zeichenfolge darstellt. In der Regel sind Zeichenfolgen gerätespezifisch, und ihr übergeordnetes Objekt sollte ein Frameworkgeräteobjekt sein.

Wenn Ihr Treiber EvtCleanupCallback - oder EvtDestroyCallback-Rückruffunktionen für das Frameworkzeichenfolgenobjekt bereitstellt, beachten Sie, dass das Framework diese Rückruffunktionen unter IRQL = PASSIVE_LEVEL aufruft.

Weitere Informationen zu Frameworkzeichenfolgenobjekten finden Sie unter Verwenden von Zeichenfolgenobjekten.

Beispiele

Im folgenden Codebeispiel wird eine WDF_OBJECT_ATTRIBUTES-Struktur initialisiert und anschließend ein Frameworkzeichenfolgenobjekt erstellt.

NTSTATUS  status;
WDFSTRING  stringHandle = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = pDeviceContext->Device;
status = WdfStringCreate(
                         NULL,
                         &attributes,
                         &stringHandle
                         );
if (!NT_SUCCESS(status)){
    return status;
}

Anforderungen

Anforderung Wert
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Kopfzeile wdfstring.h (einschließen von Wdf.h)
Bibliothek Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI-Complianceregeln DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfStringGetUnicodeString