WdfDeviceCreateSymbolicLink-Funktion (wdfdevice.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfDeviceCreateSymbolicLink--Methode erstellt eine symbolische Verknüpfung zu einem angegebenen Gerät.

Syntax

NTSTATUS WdfDeviceCreateSymbolicLink(
  [in] WDFDEVICE        Device,
  [in] PCUNICODE_STRING SymbolicLinkName
);

Parameter

[in] Device

Ein Handle zu einem Framework-Geräteobjekt.

[in] SymbolicLinkName

Ein Zeiger auf eine UNICODE_STRING Struktur, die einen sichtbaren Namen für das Gerät enthält.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die WdfDeviceCreateSymbolicLink- STATUS_SUCCCESS zurück. Weitere Rückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	Das System kann keinen Speicherplatz zuordnen, um den Gerätenamen zu speichern.

Die Methode gibt möglicherweise andere NTSTATUS-Wertezurück.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Wenn ein Treiber eine symbolische Verbindung für ein Gerät erstellt, können Anwendungen den symbolischen Linknamen verwenden, um auf das Gerät zuzugreifen. Anstatt symbolische Verknüpfungen bereitzustellen, bieten frameworkbasierte Treiber Geräteschnittstellen, die Anwendungen für den Zugriff auf ihre Geräte verwenden können.

Wenn das Gerät unerwartet entfernt wird (überraschend entfernt), entfernt das Framework die symbolische Verknüpfung zum Gerät. Der Treiber kann dann den symbolischen Verknüpfungsnamen für eine neue Instanz des Geräts verwenden.

Beispiele

Im folgenden Codebeispiel eines KMDF-Treibers wird ein MS-DOS Gerätename erstellt, den eine Anwendung für den Zugriff auf ein Gerät verwenden kann.

#define DOS_DEVICE_NAME  L"\\DosDevices\\MyDevice"
DECLARE_CONST_UNICODE_STRING(dosDeviceName, DOS_DEVICE_NAME);
NTSTATUS  status;

status = WdfDeviceCreateSymbolicLink(
                                     controlDevice,
                                     &dosDeviceName
                                     );
if (!NT_SUCCESS(status)) {
    goto Error;
}

Ein UMDF-Treiber muss einen symbolischen Linknamen im globalen DosDevices Namespace bereitstellen, wie das folgende Codebeispiel veranschaulicht.

#define DOS_DEVICE_NAME  L"\\DosDevices\\Global\\MyDevice"
DECLARE_CONST_UNICODE_STRING(dosDeviceName, DOS_DEVICE_NAME);
NTSTATUS  status;

status = WdfDeviceCreateSymbolicLink(
                                     controlDevice,
                                     &dosDeviceName
                                     );
if (!NT_SUCCESS(status)) {
    goto Error;
}

Informationen zu globalen und lokalen \DosDevices Namespaces finden Sie unter Lokalen und globalen MS-DOS Gerätenamen.

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfdevice.h (einschließen Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Siehe auch

UNICODE_STRING

Freigeben über