Funzione WdfRegistryAssignMultiString (wdfregistry.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfRegistryAssignMultiString assegna un set di stringhe a un nome valore specificato nel Registro di sistema. Le stringhe sono contenute in una raccolta specificata di oggetti stringa del framework.

Sintassi

NTSTATUS WdfRegistryAssignMultiString(
  [in] WDFKEY           Key,
  [in] PCUNICODE_STRING ValueName,
  [in] WDFCOLLECTION    StringsCollection
);

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] StringsCollection

Handle per un oggetto insieme framework che rappresenta una raccolta di oggetti stringa del framework.

Valore restituito

WdfRegistryAssignMultiString 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	WdfRegistryAssignMultiString non è stato chiamato in IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido oppure l'insieme specificato dal parametro StringsCollection non contiene oggetti stringa.
STATUS_ACCESS_DENIED	Il driver non ha aperto la chiave del Registro di sistema con accesso KEY_SET_VALUE.

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

Se il nome del valore specificato dal parametro ValueName esiste già, WdfRegistryAssignMultiString aggiorna i dati del valore.

Il framework imposta il tipo di dati del valore su REG_MULTI_SZ.

L'insieme di oggetti specificato da StringsCollection deve contenere solo oggetti stringa del framework.

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

Esempio

L'esempio di codice seguente crea un oggetto raccolta e due oggetti stringa, aggiunge gli oggetti stringa all'insieme e quindi assegna le due stringhe a un valore del Registro di sistema.

WDF_OBJECT_ATTRIBUTES attributes;
WDFCOLLECTION col = NULL;
WDFSTRING string1 = NULL, string2 = NULL;
UNICODE_STRING ustring1, ustring2, valueName;
NTSTATUS status;

status = WdfCollectionCreate(
                             WDF_NO_OBJECT_ATTRIBUTES,
                             &col
                             );
if (!NT_SUCCESS(status) {
    return status;
}

RtlInitUnicodeString(
                     &ustring1,
                     L"String1"
                     );
RtlInitUnicodeString(
                     &ustring2,
                     L"String2"
                     );
RtlInitUnicodeString(
                     &valueName,
                     L"ValueName"
                     );

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

status = WdfStringCreate(
                         &ustring1,
                         &attributes,
                         &string1
                         );
if (!NT_SUCCESS(status)) {
    goto exit;
}
status = WdfStringCreate(
                         &ustring2,
                         &attributes,
                         &string2
                         );
if (!NT_SUCCESS(status)) {
    goto exit;
}
status = WdfCollectionAdd(
                          col,
                          string1
                          );
if (!NT_SUCCESS(status)) {
    goto exit;
}
string1 = NULL;

status = WdfCollectionAdd(
                          col,
                          string2
                          );
if (!NT_SUCCESS(status)) {
    goto exit;
}
string2 = NULL;

status = WdfRegistryAssignMultiString(
                                      Key,
                                      &valueName,
                                      col
                                      );
if (!NT_SUCCESS(status)) {
    goto exit;
...
exit:
if (col != NULL) {
    WdfObjectDelete(col);    // This will empty the collection
                             // because the string objects are
                             // child objects of the collection object.
}

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)