IWDFDevice ::RetrieveDeviceName, méthode (wudfddi.h)

Article
02/07/2025

[Avertissement : UMDF 2 est la dernière version de UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide de UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et il existe une prise en charge limitée de UMDF 1 sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Bien démarrer 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 NULL-terminated qui représente le nom de l’appareil en mode noyau sous-jacent, si la mémoire tampon n’est pasNULL et 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 égale à 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 à pDeviceName n’est pasNULL, l’infrastructure retourne la taille, en caractères, de la chaîne de nom d’appareil.

Valeur de retour

RetrieveDeviceName retourne S_OK pour les scénarios suivants :

La mémoire tampon vers laquelle le paramètre pDeviceName a été non-NULL et suffisamment volumineux 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 défini la variable pointée par pdwDeviceNameLength au nombre de caractères de la chaîne.
La mémoire tampon à pDeviceName a été NULL, le pilote a prédéfini la variable à 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 à pdwDeviceNameLength 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);

Exigences

Exigence	Valeur
fin du support	Indisponible dans UMDF 2.0 et versions ultérieures.
plateforme cible	Bureau
version minimale de UMDF	1.5
d’en-tête	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Voir aussi

IWDFDevice

Partager via