Méthode IWDFFile ::RetrieveFileName (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 RetrieveFileName récupère le nom complet du fichier associé à l’appareil en mode noyau sous-jacent.

Syntaxe

HRESULT RetrieveFileName(
  [out]     PWSTR pFileName,
  [in, out] DWORD *pdwFileNameLengthInChars
);

Paramètres

[out] pFileName

Pointeur vers une mémoire tampon fournie par l’appelant qui reçoit une chaîne terminée par NULL qui représente le nom complet du fichier associé à l’appareil en mode noyau sous-jacent, si le pointeur fourni n’est pas NULL et que RetrieveFileName réussit.

[in, out] pdwFileNameLengthInChars

Pointeur vers une variable fournie par l’appelant qui reçoit la taille, en caractères, du nom de fichier complet vers lequel pFileName pointe. Si la mémoire tampon sur pFileName n’est pas NULL, l’infrastructure retourne la taille, en caractères, de la chaîne de nom de fichier.

Lors de l’entrée, le pilote définit cette variable sur la taille, en caractères, de la mémoire tampon vers laquelle pFileName pointe. Si le pilote fournit NULL pour pFileName et zéro pour la variable vers laquelle pdwFileNameLengthInChars pointe, le framework définit la variable à la taille, en caractères, requise par la chaîne de nom de fichier.

Valeur retournée

RetrieveFileName retourne S_OK pour les scénarios suivants :

• La mémoire tampon vers laquelle pointe le paramètre pFileName était non 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 vers laquelle pointe le paramètre pdwFileNameLengthInChars sur le nombre de caractères dans la chaîne.
• La mémoire tampon sur pFileName était NULL, le pilote a prédéfini la variable à pdwFileNameLengthInChars sur 0, et l’infrastructure a défini la variable sur pdwFileNameLengthInChars sur le nombre de caractères requis pour la chaîne.

RetrieveFileName retourne HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) pour indiquer que la mémoire tampon fournie n’est pas NULL et ne contient pas suffisamment d’espace pour contenir le nom de fichier. L’infrastructure définit la variable à l’emplacement pdwFileNameLengthInChars sur le nombre de caractères requis pour la chaîne.

RetrieveFileName peut également retourner d’autres valeurs HRESULT.

Remarques

Votre pilote peut appeler RetrieveFileName à partir de sa fonction de rappel IQueueCallbackCreate ::OnCreateFile . Pour plus d’informations, consultez Utilisation d’interfaces de périphérique dans les pilotes UMDF.

Exemples

L’exemple de code suivant montre comment récupérer le nom d’un fichier.

    ULONG fileNameCch = 0;
    PWSTR fileName = NULL;
    ULONG index;

    CComObject<CUmdfHidFile> *file = NULL;

    HRESULT hr;

    // Get the length of the file name to allocate a buffer.
    hr = WdfFile->RetrieveFileName(NULL, &fileNameCch);
    //
    // Allocate the buffer.
    //
    if (SUCCEEDED(hr))
    {
        fileName = new WCHAR[fileNameCch];

        if (fileName == NULL)
        {
            hr = E_OUTOFMEMORY;
        }
    }
    //
    // Get the file name.
    //
    if (SUCCEEDED(hr))
    {
        hr = WdfFile->RetrieveFileName(fileName, &fileNameCch);
    }

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

IWDFFile