Méthode IWDFRemoteInterfaceInitialize ::RetrieveSymbolicLink (wudfddi.h)

Article
03/05/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éthode RetrieveSymbolicLink récupère le nom de lien symbolique attribué par le système d’exploitation à une interface d’appareil.

Syntaxe

HRESULT RetrieveSymbolicLink(
  [out, optional] PWSTR pSymbolicLink,
  [in, out]       DWORD *pdwSymbolicLinkLengthInChars
);

Paramètres

[out, optional] pSymbolicLink

Pointeur vers une mémoire tampon qui reçoit une chaîne de caractères Unicode terminée par null qui représente le nom du lien symbolique. Définissez ce pointeur sur NULL pour obtenir la taille de mémoire tampon requise.

[in, out] pdwSymbolicLinkLengthInChars

Pointeur vers un emplacement alloué par l’appelant. En entrée, cet emplacement doit contenir la longueur fournie par l’appelant de la mémoire tampon vers laquelle pSymbolicLink pointe. À la sortie, l’emplacement reçoit la longueur, en caractères, du nom du lien symbolique, y compris le caractère de fin NULL .

Valeur retournée

RetrieveSymbolicLink retourne S_OK si l’opération réussit. Sinon, la méthode peut retourner la valeur suivante :

Code de retour	Description
E_NOT_SUFFICIENT_BUFFER	La mémoire tampon vers laquelle pSymbolicLink pointe est trop petite. Dans ce cas, l’infrastructure stocke la taille de mémoire tampon requise à l’emplacement vers lequel pointe pdwSymbolicLinkLengthInChars .

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

Remarques

Le nom du lien symbolique peut inclure un caractère de barre oblique inverse () ajouté, suivi d’une chaîne de référence spécifique à instance.

En règle générale, votre pilote doit appeler RetrieveSymbolicLink deux fois, comme suit :

Définissez le paramètre pSymbolicLink sur NULL et appelez RetrieveSymbolicLink. L’emplacement que pdwSymbolicLinkLengthInChars pointe vers reçoit le nombre de caractères que contient le nom du lien symbolique.
Allouez une mémoire tampon suffisamment grande pour recevoir le nom du lien symbolique.
Appelez à nouveau RetrieveSymbolicLink et définissez le paramètre pSymbolicLink sur l’adresse de la mémoire tampon que vous avez allouée.

Pour plus d’informations sur la méthode RetrieveSymbolicLink , consultez Utilisation d’interfaces d’appareil dans les pilotes basés sur UMDF.

Exemples

L’exemple de code suivant montre comment la fonction de rappel IPnpCallbackRemoteInterfaceNotification ::OnRemoteInterfaceArrival d’un pilote peut déterminer la longueur du nom de lien symbolique de l’interface d’appareil, allouer une mémoire tampon pour le nom, puis récupérer le nom.

void 
STDMETHODCALLTYPE
CMyDevice::OnRemoteInterfaceArrival(
    __in IWDFRemoteInterfaceInitialize  *FxRemoteInterfaceInit
    )
{
    HRESULT hr;
    INT BufferSize;
    hr= FxRemoteInterfaceInit->RetrieveSymbolicLink(NULL,
                                                    &BufferSize);
    if (FAILED(hr)) goto Error;
    hr = FxDriver->CreateWdfMemory(BufferSize, 
                                   NULL, 
                                   FxRemoteInterface, 
                                   &FxSymLinkBuffer);
    if (FAILED(hr)) goto Error;
    hr= FxRemoteInterfaceInit->RetrieveSymbolicLink(FxSymLinkBuffer->GetDataBuffer(NULL),
                                                    &BufferSize);
    if (FAILED(hr)) goto Error;
...
Error:
...
}

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

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize ::GetInterfaceGuid

Partager via