Fungsi WdfDeviceRetrieveDeviceInterfaceString (wdfdevice.h)

Artikel
02/27/2024

[Berlaku untuk KMDF dan UMDF]

Metode WdfDeviceRetrieveDeviceInterfaceString mengambil nama tautan simbolis yang ditetapkan sistem operasi ke antarmuka perangkat yang didaftarkan driver untuk perangkat tertentu.

Sintaks

NTSTATUS WdfDeviceRetrieveDeviceInterfaceString(
  [in]           WDFDEVICE        Device,
  [in]           const GUID       *InterfaceClassGUID,
  [in, optional] PCUNICODE_STRING ReferenceString,
  [in]           WDFSTRING        String
);

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in] InterfaceClassGUID

Pointer ke GUID yang mengidentifikasi kelas antarmuka perangkat.

[in, optional] ReferenceString

Penunjuk ke struktur UNICODE_STRING yang menjelaskan string referensi untuk antarmuka perangkat. Parameter ini bersifat opsional dan dapat berupa NULL jika driver tidak menentukan string referensi ketika disebut WdfDeviceCreateDeviceInterface.

[in] String

Handel ke objek string kerangka kerja. Kerangka kerja akan menetapkan string Unicode nama tautan simbolis ke objek string.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceRetrieveDeviceInterfaceString tidak dipanggil di IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid ditentukan.
STATUS_INVALID_DEVICE_REQUEST	Objek perangkat yang ditentukan diinisialisasi oleh WdfControlDeviceInitAllocate.
STATUS_OBJECT_NAME_NOT_FOUND	Antarmuka perangkat yang cocok dengan GUID dan string referensi yang ditentukan tidak dapat ditemukan.
STATUS_INVALID_DEVICE_STATE	Driver bernama WdfDeviceCreateDeviceInterface tetapi sistem belum menetapkan nama tautan simbolis ke antarmuka perangkat.

WdfDeviceRetrieveDeviceInterfaceString mungkin juga mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Untuk informasi selengkapnya tentang antarmuka perangkat, lihat Menggunakan Antarmuka Perangkat.

Contoh

Contoh kode berikut membuat objek string lalu mengambil nama tautan simbolis antarmuka perangkat tertentu.

NTSTATUS status;
WDFSTRING string;

status = WdfStringCreate(
                         NULL,
                         WDF_NO_OBJECT_ATTRIBUTES,
                         &string
                         );
if (NT_SUCCESS(status)) {
    status = WdfDeviceRetrieveDeviceInterfaceString(
                         Device,
                         &GUID_DEVINTERFACE_DDI_TEST1,
                         NULL,
                         string
                         );
    if (!NT_SUCCESS(status)) {
        return status;
    }
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfdevice.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)

Lihat juga

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate