IWDFFile ::RetrieveFileName, méthode (wudfddi.h)
[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 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 NULL-terminated 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 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 à pFileName n’est pasNULL, 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 qui pdwFileNameLengthInChar s pointe vers, l’infrastructure définit la variable sur la taille, en caractères, que la chaîne de nom de fichier requiert.
Valeur de retour
RetrieveFileName retourne S_OK pour les scénarios suivants :
- La mémoire tampon à laquelle le paramètre pFileName pointe n’était pasNULL et suffisamment volumineux pour contenir la chaîne de nom, y compris le caractère NULL, et que l’infrastructure a correctement copié la chaîne dans la mémoire tampon fournie et défini la variable pointée par la pdwFileNameLengthInChars paramètre sur le nombre de caractères de la chaîne.
- La mémoire tampon à pFileName était NULL, le pilote prédéfinit 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 fonction de rappel. Pour plus d’informations, consultez Using Device Interfaces in UMDF Drivers.
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);
}
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 |