GetFinalPathNameByHandleW, fonction (fileapi.h)
Récupère le chemin final du fichier spécifié.
Pour plus d’informations sur les noms de fichiers et de chemins d’accès, consultez nommage d’un fichier.
Syntaxe
DWORD GetFinalPathNameByHandleW(
[in] HANDLE hFile,
[out] LPWSTR lpszFilePath,
[in] DWORD cchFilePath,
[in] DWORD dwFlags
);
Paramètres
[in] hFile
Handle vers un fichier ou un répertoire.
[out] lpszFilePath
Pointeur vers une mémoire tampon qui reçoit le chemin d’accès de hFile.
[in] cchFilePath
Taille de lpszFilePath, dans TCHAR. Cette valeur doit inclure un caractère d’arrêt NULL
[in] dwFlags
Type de résultat à retourner. Ce paramètre peut être l’une des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Retourne le nom du lecteur normalisé. Il s’agit de la valeur par défaut. |
|
Retournez le nom de fichier ouvert (non normalisé). |
Ce paramètre peut également inclure l’une des valeurs suivantes.
Valeur de retour
Si la fonction réussit, la valeur de retour est la longueur de la chaîne reçue par lpszFilePath, dans TCHARs. Cette valeur n’inclut pas la taille du caractère null de fin.
Windows Server 2008 et Windows Vista : Pour la version ANSI de cette fonction, GetFinalPathNameByHandleA, la valeur de retour inclut la taille du caractère null de fin.
Si la fonction échoue, car lpszFilePath est trop petite pour contenir la chaîne plus le caractère null de fin, la valeur de retour est la taille de mémoire tampon requise, dans TCHARs. Cette valeur inclut la taille du caractère null de fin.
Si la fonction échoue pour une autre raison, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.
| Retourner le code | Description |
|---|---|
|
Peut être retourné si vous recherchez une lettre de lecteur et qu’il n’existe pas. Par exemple, le handle a été ouvert sur un lecteur qui n’est pas monté actuellement, ou si vous créez un volume et ne l’affectez pas à une lettre de lecteur. Si un volume n’a pas de lettre de lecteur, vous pouvez utiliser le volume GUID chemin d’accès pour l’identifier.
Cette valeur de retour peut également être retournée si vous recherchez un volume GUID chemin d’accès sur un partage réseau. Les chemins d’accès guid de volume |
|
Mémoire insuffisante pour terminer l’opération. |
|
Les indicateurs non valides ont été spécifiés pour dwFlags. |
Remarques
Le protocole SMB (Server Message Block) ne prend pas en charge les requêtes pour les chemins normalisés. Par conséquent, lorsque vous appelez cette fonction en passant le handle d’un fichier ouvert à l’aide de SMB, et avec l’indicateur FILE_NAME_NORMALIZED, la fonction fractionne le chemin d’accès en ses composants et tente d’interroger le nom normalisé de chacun de ces composants à son tour. Si l’utilisateur n’a pas l’autorisation d’accès à l’un de ces composants, l’appel de fonction échoue avec ERROR_ACCESS_DENIED.
Un chemin final est le chemin retourné lorsqu’un chemin d’accès est entièrement résolu. Par exemple, pour un lien symbolique nommé « C :\tmp\mydir » qui pointe vers « D :\yourdir », le chemin final serait « D :\yourdir ».
Lorsque vous utilisez VOLUME_NAME_DOS, la chaîne retournée par cette fonction utilise la syntaxe « \\ ?\ ». Pour plus d’informations, consultez CreateFile.
Lorsque vous utilisez VOLUME_NAME_GUID, le chemin retourné commence par un chemin GUID de volume mis en forme comme « \\ ?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\ ».
Lorsque vous utilisez VOLUME_NAME_NT, le chemin d’accès retourné est destiné à un objet d’appareil NT et commence par un nom d’appareil tel que « \Device\HarddiskVolume1\ ». Ce type de chemin d’accès ne peut pas être utilisé directement par les programmes Windows, car il ressemble à un chemin relatif.
Certains pilotes tiers peuvent créer une lettre de lecteur ou un point de montage sans utiliser le Gestionnaire de montage. Si le Gestionnaire de montage n’a pas été utilisé pour créer le lecteur, VOLUME_NAME_DOS ou VOLUME_NAME_GUID ne réussira pas ; seuls VOLUME_NAME_NT seront disponibles. Pour déterminer la lettre de lecteur du chemin d’accès de l’appareil de volume, utilisez la fonction QueryDosDevice sur chaque lettre de lecteur jusqu’à ce qu’un nom d’appareil correspondant soit trouvé.
Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.
| Technologie | Supporté |
|---|---|
| Protocole SMB (Server Message Block) 3.0 | Oui |
| Basculement transparent SMB 3.0 (TFO) | Oui |
| SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) | Oui |
| Cluster Shared Volume File System (CsvFS) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
Exemples
L’exemple suivant illustre l’utilisation de la fonction GetFinalPathNameByHandle.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE MAX_PATH
void __cdecl _tmain(int argc, TCHAR *argv[])
{
TCHAR Path[BUFSIZE];
HANDLE hFile;
DWORD dwRet;
printf("\n");
if( argc != 2 )
{
printf("ERROR:\tIncorrect number of arguments\n\n");
printf("%s <file_name>\n", argv[0]);
return;
}
hFile = CreateFile(argv[1], // file to open
GENERIC_READ, // open for reading
FILE_SHARE_READ, // share for reading
NULL, // default security
OPEN_EXISTING, // existing file only
FILE_ATTRIBUTE_NORMAL, // normal file
NULL); // no attr. template
if( hFile == INVALID_HANDLE_VALUE)
{
printf("Could not open file (error %d\n)", GetLastError());
return;
}
dwRet = GetFinalPathNameByHandle( hFile, Path, BUFSIZE, VOLUME_NAME_NT );
if(dwRet < BUFSIZE)
{
_tprintf(TEXT("\nThe final path is: %s\n"), Path);
}
else printf("\nThe required buffer size is %d.\n", dwRet);
CloseHandle(hFile);
}
Note
L’en-tête fileapi.h définit GetFinalPathNameByHandle comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows Vista [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2008 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | fileapi.h (include Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |