WdfDeviceCreateSymbolicLink-Funktion (wdfdevice.h)

[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 zu einem Framework-Geräteobjekt.

[in] SymbolicLinkName

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

Rückgabewert

Wenn der Vorgang erfolgreich verläuft, gibt der WdfDeviceCreateSymbolicLink STATUS_SUCCCESS zurück. Weitere Rückgabewerte umfassen:

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

Die Methode kann andere NTSTATUS-Werte zurückgeben.

Eine Fehlerprüfung tritt auf, wenn der Treiber einen ungültigen Objekthandpunkt bereitstellt.

Hinweise

Wenn ein Treiber einen symbolischen Link für ein Gerät erstellt, können Anwendungen den symbolischen Linknamen verwenden, um auf das Gerät zuzugreifen. Statt symbolische Links bereitzustellen, bieten frameworkbasierte Treiber Geräteschnittstellen , mit denen Anwendungen auf ihre Geräte zugreifen können.

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 Instanz des Geräts verwenden.

Beispiele

Im folgenden Codebeispiel eines KMDF-Treibers wird ein MS-DOS-Gerätename erstellt, mit dem eine Anwendung auf ein Gerät zugreifen 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

   
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Header wdfdevice.h (enthalten 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