Méthode IWDFDevice2 ::CreateSymbolicLinkWithReferenceString (wudfddi.h)

Article
02/27/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La méthodeCreateSymbolicLinkWithReferenceString crée un nom de lien symbolique et éventuellement une chaîne de référence pour un appareil

Syntaxe

HRESULT CreateSymbolicLinkWithReferenceString(
  [in]           PCWSTR pSymbolicLink,
  [in, optional] PCWSTR pReferenceString
);

Paramètres

[in] pSymbolicLink

Pointeur vers une chaîne de caractères terminée par null qui devient le nom visible par l’utilisateur de l’appareil. Le nom du lien symbolique doit se trouver dans l’espace de noms DosDevices global.

[in, optional] pReferenceString

Pointeur vers une chaîne de caractères terminée par NULL que Windows ajoute au nom de l’appareil lorsqu’une application utilise le nom symbolique spécifié par le paramètre pSymbolicLink . Pour plus d'informations, consultez la section Notes qui suit. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

CreateSymbolicLinkWithReferenceString retourne S_OK si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
E_INVALIDARG	L’appelant a spécifié une valeur non valide pour un paramètre d’entrée.
E_OUTOFMEMORY	L’allocation de mémoire a échoué.

Cette méthode peut retourner l’une des autres valeurs que Winerror.h contient.

Remarques

CreateSymbolicLinkWithReferenceString crée un nom de lien symbolique et éventuellement une chaîne de référence pour l’appareil que représente l’interface IWDFDevice2 . Après qu’un pilote a appelé CreateSymbolicLinkWithReferenceString, les applications peuvent utiliser le nom de lien symbolique pour accéder à l’appareil.

Supposons que le nom de votre appareil est « \Device\MyDevice ». Vous pouvez créer un nom de lien symbolique « DeviceUserName » pour votre appareil en spécifiant « L » DeviceUserName » pour le paramètre pSymbolicLink . Si vous spécifiez « L » Instance3 » pour le paramètre pReferenceString, vous créez un lien symbolique vers \Device\MyDevice\Instance3. Si une application ouvre l’appareil à l’aide du nom de lien symbolique, le gestionnaire d’E/S ouvre \Device\MyDevice et crée un objet de fichier WDM qui contient la chaîne \Instance3 comme nom de fichier. Votre pilote UMDF reçoit un objet de fichier créé par l’infrastructure, qui contient également la chaîne \Instance3 comme nom de fichier (voir IWDFFile ::RetrieveFileName).

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.

Si vous n’avez pas besoin d’ajouter de chaîne de référence au nom de lien symbolique de votre appareil, votre pilote peut appeler IWDFDevice ::CreateSymbolicLink au lieu de CreateSymbolicLinkWithReferenceString.

Exemples

La ligne suivante définit un préfixe de nom de lien symbolique dans l’espace de noms DosDevices global.

#define SYMBOLIC_LINK_NAME_PREFIX   L"\\DosDevices\\Global\\"

L’exemple de code suivant crée une chaîne de nom symbolique, obtient l’interface IWDFDevice2 , puis appelle CreateSymbolicLinkWithReferenceString.


    IWDFDevice2 *pDevice2 = NULL;
    HRESULT hr;

    //
    // Create symbolic link name string.
    //
    hr = StringCchPrintf(portFullName,
                         portFullNameLength,
                         L"%ws%ws",
                         SYMBOLIC_LINK_NAME_PREFIX,
                         portName);
    if (FAILED(hr))
    {
        goto Exit;
    }

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pDevice2);
    if (SUCCEEDED(hr)) 
    {
    hr = pDevice2->CreateSymbolicLinkWithReferenceString(portFullName,
                                                         portCountString);
    if (FAILED(hr))
        {
            goto Exit;
        }
        SAFE_RELEASE(pDevice2);
    }

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1,9
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll

Voir aussi

IWDFDevice2

IWDFDevice ::CreateSymbolicLink

Partager via