GetFinalPathNameByHandleA, fonction (fileapi.h)

Récupère le chemin d’accès 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 GetFinalPathNameByHandleA(
  [in]  HANDLE hFile,
  [out] LPSTR  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, en TCHAR. Cette valeur doit inclure un caractère d’arrêt NULL .

[in] dwFlags

Type de résultat à retourner. Ce paramètre peut prendre les valeurs suivantes.

Ce paramètre peut également inclure l’une des valeurs suivantes.

Valeur retournée

Si la fonction réussit, la valeur de retour correspond à 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 parce que lpszFilePath est trop petit pour contenir la chaîne plus le caractère null de fin, la valeur de retour est la taille de mémoire tampon requise, en 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 zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

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 d’accès final est le chemin qui est 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 est « D :\yourdir ».

La chaîne retournée par cette fonction utilise la syntaxe « \\ ?\ ». Pour plus d’informations, consultez CreateFile.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

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);
}

Configuration requise

Voir aussi

Fonctions de gestion des fichiers