Fungsi WdfRegistryAssignMultiString (wdfregistry.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfRegistryAssignMultiString menetapkan sekumpulan string ke nama nilai tertentu dalam registri. String terkandung dalam kumpulan objek string kerangka kerja tertentu.

Sintaks

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

Parameter

[in] Key

Handel ke objek kunci registri yang mewakili kunci registri yang dibuka.

[in] ValueName

Penunjuk ke struktur UNICODE_STRING yang berisi nama nilai.

[in] StringsCollection

Handel ke objek kumpulan kerangka kerja yang mewakili kumpulan objek string kerangka kerja.

Nilai kembali

WdfRegistryAssignMultiString mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryAssignMultiString tidak dipanggil di IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid ditentukan, atau koleksi yang ditentukan parameter StringsCollection tidak berisi objek string.
STATUS_ACCESS_DENIED	Driver tidak membuka kunci registri dengan akses KEY_SET_VALUE.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Jika nama nilai yang ditentukan parameter ValueName sudah ada, WdfRegistryAssignMultiString memperbarui data nilai.

Kerangka kerja mengatur jenis data nilai ke REG_MULTI_SZ.

Koleksi objek yang ditentukan StringsCollection hanya boleh berisi objek string kerangka kerja.

Untuk informasi selengkapnya tentang objek kunci registri, lihat Menggunakan Registri di Driver Framework-Based.

Contoh

Contoh kode berikut membuat objek koleksi dan dua objek string, menambahkan objek string ke koleksi, lalu menetapkan dua string ke satu nilai registri.

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

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfregistry.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)