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 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 |