WdfDeviceCreateSymbolicLink-Funktion (wdfdevice.h)

  • Artikel

[Gilt für KMDF und UMDF]

Die WdfDeviceCreateSymbolicLink-Methode erstellt einen symbolischen Link zu einem angegebenen Gerät.

Syntax

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

Parameter

[in] Device

Ein Handle für ein Framework-Geräteobjekt.

[in] SymbolicLinkName

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

Rückgabewert

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

Rückgabecode Beschreibung
STATUS_INSUFFICIENT_RESOURCES
 Das System kann keinen Speicherplatz zum Speichern des Gerätenamens zuweisen.
 

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

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Wenn ein Treiber eine symbolische Verknüpfung für ein Gerät erstellt, können Anwendungen den symbolischen Linknamen verwenden, um auf das Gerät zuzugreifen. Frameworkbasierte Treiber stellen in der Regel Geräteschnittstellen bereit, die Anwendungen für den Zugriff auf ihre Geräte verwenden können, anstatt symbolische Links bereitzustellen.

Wenn das Gerät unerwartet entfernt wird (überraschend entfernt), entfernt das Framework den symbolischen Link zum Gerät. Der Treiber kann dann den symbolischen Linknamen für eine neue instance 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 Lokale und globale MS-DOS-Gerätenamen.

Anforderungen

Anforderung Wert
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Kopfzeile wdfdevice.h (einschließen von Wdf.h)
Bibliothek Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI-Complianceregeln DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

UNICODE_STRING