WdfDeviceCreateSymbolicLink, fonction (wdfdevice.h)

Article
02/27/2024

[S’applique à KMDF et UMDF]

La méthode WdfDeviceCreateSymbolicLink crée un lien symbolique vers un appareil spécifié.

Syntaxe

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

Paramètres

[in] Device

Handle d’un objet d’appareil framework.

[in] SymbolicLinkName

Pointeur vers une structure UNICODE_STRING qui contient un nom visible par l’utilisateur pour l’appareil.

Valeur retournée

Si l’opération réussit, WdfDeviceCreateSymbolicLink retourne STATUS_SUCCCESS. Les valeurs de retour supplémentaires sont les suivantes :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	Le système ne peut pas allouer d’espace pour stocker le nom de l’appareil.

La méthode peut retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Si un pilote crée un lien symbolique pour un appareil, les applications peuvent utiliser le nom de lien symbolique pour accéder à l’appareil. En règle générale, au lieu de fournir des liens symboliques, les pilotes basés sur l’infrastructure fournissent des interfaces d’appareil que les applications peuvent utiliser pour accéder à leurs appareils.

Si l’appareil est supprimé de manière inattendue (suppression surprise), l’infrastructure supprime le lien symbolique vers l’appareil. Le pilote peut ensuite utiliser le nom de lien symbolique pour une nouvelle instance de l’appareil.

Exemples

L’exemple de code suivant à partir d’un pilote KMDF crée un nom d’appareil MS-DOS qu’une application peut utiliser pour accéder à un appareil.

#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;
}

Un pilote UMDF doit fournir un nom de lien symbolique dans l’espace de noms DosDevices global, comme l’illustre l’exemple de code suivant.

#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;
}

Pour plus d’informations sur les espaces de noms \DosDevices globaux et locaux, consultez Noms d’appareils MS-DOS locaux et globaux.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfdevice.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

UNICODE_STRING

Partager via