Méthode IWDFDevice ::RetrieveDeviceName (wudfddi.h)

[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 RetrieveDeviceName récupère le nom d’un appareil en mode noyau sous-jacent.

Syntaxe

HRESULT RetrieveDeviceName(
  [out]     PWSTR pDeviceName,
  [in, out] DWORD *pdwDeviceNameLength
);

Paramètres

[out] pDeviceName

Pointeur vers une mémoire tampon qui reçoit une chaîne terminée par NULL qui représente le nom de l’appareil en mode noyau sous-jacent, si la mémoire tampon n’est pas NULL et que RetrieveDeviceName réussit.

[in, out] pdwDeviceNameLength

Pointeur vers une variable qui reçoit le nombre de caractères, y compris le caractère NULL , dans le nom de l’appareil.

Si la mémoire tampon à pDeviceName est NULL, la valeur que le pilote fournit est zéro. L’infrastructure retourne ensuite la taille, en caractères, requise pour la chaîne de nom d’appareil.

Si la mémoire tampon de pDeviceName n’est pas NULL, l’infrastructure retourne la taille, en caractères, de la chaîne de nom d’appareil.

Valeur retournée

RetrieveDeviceName retourne S_OK pour les scénarios suivants :

• La mémoire tampon vers laquelle le paramètre pDeviceName pointait n’était pas NULL et suffisamment grande pour contenir la chaîne de nom, y compris le caractère NULL , et l’infrastructure a correctement copié la chaîne dans la mémoire tampon fournie et a défini la variable pointée par pdwDeviceNameLength sur le nombre de caractères dans la chaîne.
• La mémoire tampon sur pDeviceName était NULL, le pilote a prédéfini la variable au niveau pdwDeviceNameLength sur 0 et l’infrastructure a défini la variable sur pdwDeviceNameLength sur le nombre de caractères requis pour la chaîne.

RetrieveDeviceName retourne HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) pour indiquer que la mémoire tampon fournie n’était pas NULL et ne contenait pas suffisamment d’espace pour contenir le nom de l’appareil. L’infrastructure définit la variable sur pdwDeviceNameLength sur le nombre de caractères requis pour la chaîne.

RetrieveDeviceName peut également retourner d’autres valeurs HRESULT.

Remarques

Le nom de l’appareil n’est pas le nom de l’objet d’appareil physique (PDO). Au lieu de cela, le nom de l’appareil est le nom du réflecteur. Le pilote doit cibler toutes les E/S sur cet objet d’appareil.

Exemples

L’exemple de code suivant montre comment récupérer le nom d’un appareil en mode noyau sous-jacent.

    PWSTR deviceName = NULL;
    DWORD deviceNameCch = 0;
    HRESULT hr;
    //
    // Get the length of the device name to allocate a buffer
    //
    hr = m_FxDevice->RetrieveDeviceName(NULL, &deviceNameCch);
    //
    // Allocate the buffer
    //
    deviceName = new WCHAR[deviceNameCch];

    if (deviceName == NULL) {
        hr = E_OUTOFMEMORY;
        goto Exit1;
    }
    //
    // Get the device name
    //
    hr = m_FxDevice->RetrieveDeviceName(deviceName,
                                        &deviceNameCch);

    // Open the device and get the handle

    m_Handle = CreateFile(deviceName, 
                         (GENERIC_READ | GENERIC_WRITE), 
                         0, 
                         NULL, 
                         OPEN_EXISTING, 
                         FILE_FLAG_OVERLAPPED, 
                         NULL);

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.5
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll

Voir aussi

IWDFDevice