Funzione WdfStringCreate (wdfstring.h)

Articolo
02/07/2025

[Si applica a KMDF e UMDF]

Il metodo WdfStringCreate crea un oggetto stringa framework e, facoltativamente, assegna una stringa Unicode specificata all'oggetto .

Sintassi

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

Parametri

[in, optional] UnicodeString

Puntatore a una struttura UNICODE_STRING che contiene una costante stringa Unicode. Il framework copia la stringa nel nuovo oggetto stringa del framework. Questo puntatore è facoltativo e può essere NULL.

[in, optional] StringAttributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che contiene gli attributi forniti dal driver per il nuovo oggetto stringa. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[out] String

Puntatore a una posizione che riceve un handle per il nuovo oggetto stringa.

Valore restituito

WdfStringCreate restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	WdfStringCreate non è stato chiamato in IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare un oggetto stringa.

Per un elenco di altri valori restituiti dal metodo WdfStringCreate, vedere Framework Object Creation Errors.

Questo metodo potrebbe anche restituire altri valori NTSTATUS .

Osservazioni

L'elemento padre predefinito per gli oggetti stringa del framework è l'oggetto driver del driver del driver. Tuttavia, a meno che la stringa non sia associata al driver, il driver deve impostare il ParentObject membro della struttura WDF_OBJECT_ATTRIBUTES su un oggetto che rappresenta l'ambito della stringa. In genere, le stringhe sono specifiche del dispositivo e il relativo oggetto padre deve essere un oggetto dispositivo framework.

Se il driver fornisce EvtCleanupCallback o EvtDestroyCallback funzioni di callback per l'oggetto stringa del framework, si noti che il framework chiama queste funzioni di callback in IRQL = PASSIVE_LEVEL.

Per altre informazioni sugli oggetti stringa del framework, vedere Using String Objects.

Esempi

Nell'esempio di codice seguente viene inizializzata una struttura WDF_OBJECT_ATTRIBUTES e quindi viene creato un oggetto stringa del framework.

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

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	2.0
intestazione	wdfstring.h (include Wdf.h)
libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedere anche

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfStringGetUnicodeString

Condividi tramite