Funzione WdfRegistryQueryMultiString (wdfregistry.h)

Articolo
02/29/2024

[Si applica a KMDF e UMDF]

Il metodo WdfRegistryQueryMultiString recupera le stringhe attualmente assegnate a un valore del Registro di sistema multi stringhe specificato, crea un oggetto stringa di framework per ogni stringa e aggiunge ogni oggetto stringa a un insieme di oggetti specificato.

Sintassi

NTSTATUS WdfRegistryQueryMultiString(
  [in]           WDFKEY                 Key,
  [in]           PCUNICODE_STRING       ValueName,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringsAttributes,
  [in]           WDFCOLLECTION          Collection
);

Parametri

[in] Key

Handle per un oggetto chiave del Registro di sistema che rappresenta una chiave del Registro di sistema aperta.

[in] ValueName

Puntatore a una struttura UNICODE_STRING contenente un nome di valore.

[in, optional] StringsAttributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che contiene attributi di oggetto per ogni nuovo oggetto stringa. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[in] Collection

Handle a un oggetto raccolta framework fornito dal driver.

Valore restituito

WdfRegistryQueryMultiString 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	WdfRegistryQueryMultiString non è stato chiamato in IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare un oggetto stringa.
STATUS_ACCESS_DENIED	Il driver non ha aperto la chiave del Registro di sistema con KEY_QUERY_VALUE, KEY_READ o accesso KEY_ALL_ACCESS.
STATUS_OBJECT_TYPE_MISMATCH	Tipo di dati del valore del Registro di sistema specificato dal parametro ValueName non REG_MULTI_SZ.
STATUS_OBJECT_NAME_NOT_FOUND	Il valore del Registro di sistema non è stato disponibile.
STATUS_RESOURCE_DATA_NOT_FOUND	Il valore del Registro di sistema esiste sotto la chiave specificata, ma è vuoto.

Per un elenco di altri valori restituiti che il metodo WdfRegistryQueryMultiString potrebbe restituire, vedere Errori di creazione dell'oggetto Framework.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Prima che il driver chiami WdfRegistryQueryMultiString, deve chiamare WdfCollectionCreate per creare un oggetto raccolta.

Se il chiamante non fornisce un parametro StringsAttributes , tutti gli oggetti WDFSTRING creati dal framework sono padre per impostazione predefinita al WDFDRIVER.

Dopo aver restituito WdfRegistryQueryMultiString , il driver può chiamare WdfCollectionGetCount per ottenere il numero di stringhe recuperate e WdfCollectionGetItem per ottenere oggetti stringa dall'insieme.

Se l'insieme contiene oggetti prima che il driver chiami il metodo WdfRegistryQueryMultiString , il metodo non rimuove tali oggetti o modifica i relativi valori di indice. I nuovi oggetti vengono aggiunti alla fine dell'insieme.

Per ottenere una stringa da un oggetto stringa, il driver può chiamare WdfStringGetUnicodeStringStringString.

Per altre informazioni sugli oggetti chiave del Registro di sistema, vedere Uso del Registro di sistema in Framework-Based Driver.

Esempio

Nell'esempio di codice seguente viene creato un oggetto raccolta, inizializza una struttura WDF_OBJECT_ATTRIBUTES in modo che l'oggetto raccolta sia l'elemento padre di tutti gli oggetti stringa creati dal framework per la raccolta e recupera le stringhe da un valore del Registro di sistema a più stringhe. Infine, nell'esempio viene ottenuto il numero di oggetti stringa aggiunti al framework all'insieme.

WDF_OBJECT_ATTRIBUTES stringAttributes;
WDFCOLLECTION col;
NTSTATUS status;
ULONG count;
DECLARE_CONST_UNICODE_STRING(valueMultiSz, VALUE_MULTI_SZ);

status = WdfCollectionCreate(
                             NULL,
                             &col
                             );
ASSERT(NT_SUCCESS(status));

WDF_OBJECT_ATTRIBUTES_INIT(&stringAttributes);
stringAttributes.ParentObject = col;

status = WdfRegistryQueryMultiString(
                                     Key,
                                     &valueMultiSzEmpty,
                                     &stringAttributes,
                                     col
                                     );

count = WdfCollectionGetCount(col);

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfregistry.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)