Funzione WdfStringCreate (wdfstring.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfStringCreate crea un oggetto stringa del framework e assegna facoltativamente 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 contenente 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 contenente 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 che il metodo WdfStringCreate potrebbe restituire, vedere Errori di creazione dell'oggetto Framework.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Commenti

L'elemento padre predefinito per gli oggetti stringa del framework è l'oggetto driver del driver del driver. Tuttavia, a meno che la stringa sia associata al driver, il driver deve impostare il membro ParentObject 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 del dispositivo framework.

Se il driver fornisce funzioni di callback EvtCleanupCallback o EvtDestroyCallback 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 Uso di oggetti String.

Esempio

Nell'esempio di codice seguente viene inizializzata una struttura WDF_OBJECT_ATTRIBUTES e quindi viene creato un oggetto stringa di 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;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2,0
Intestazione	wdfstring.h (includere Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedi anche

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfStringGetUnicodeString

Condividi tramite