GetFullPathNameA, fonction (fileapi.h)
Récupère le chemin d’accès complet et le nom de fichier du fichier spécifié.
Pour effectuer cette opération en tant qu’opération transactionnelle, utilisez la fonction GetFullPathNameTransacted.
Pour plus d’informations sur les noms de fichiers et de chemins d’accès, consultez noms de fichiers, chemins et espaces de noms.
Syntaxe
DWORD GetFullPathNameA(
[in] LPCSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPSTR lpBuffer,
[out] LPSTR *lpFilePart
);
Paramètres
[in] lpFileName
Nom du fichier.
Ce paramètre peut être un court (formulaire 8.3) ou un nom de fichier long. Cette chaîne peut également être un nom de partage ou de volume.
[in] nBufferLength
Taille de la mémoire tampon à recevoir la chaîne terminée par null pour le lecteur et le chemin d’accès, dans TCHAR.
[out] lpBuffer
Pointeur vers une mémoire tampon qui reçoit la chaîne terminée par null pour le lecteur et le chemin d’accès.
[out] lpFilePart
Pointeur vers une mémoire tampon qui reçoit l’adresse (dans lpBuffer) du composant de nom de fichier final dans le chemin d’accès.
Ce paramètre peut être NULL.
Si lpBuffer fait référence à un répertoire et non à un fichier, lpFilePart reçoit zéro.
Valeur de retour
Si la fonction réussit, la valeur de retour est la longueur, dans TCHARs , de la chaîne copiée dans lpBuffer, sans inclure le caractère null de fin.
Si le lpBuffer tampon est trop petit pour contenir le chemin d’accès, la valeur de retour est la taille, dans TCHARs, de la mémoire tampon requise pour contenir le chemin d’accès et le 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.
Remarques
GetFullPathName fusionne le nom du lecteur et du répertoire actuel avec un nom de fichier spécifié pour déterminer le chemin d’accès complet et le nom de fichier d’un fichier spécifié. Il calcule également l’adresse de la partie nom de fichier du chemin d’accès complet et du nom de fichier.
Cette fonction ne vérifie pas que le chemin d’accès et le nom de fichier résultants sont valides ou qu’ils voient un fichier existant sur le volume associé.
Notez que le paramètre lpFilePart ne nécessite pas d’espace de mémoire tampon de chaîne, mais suffit pour une seule adresse. Cela est dû au fait qu’il retourne simplement une adresse dans la mémoire tampon qui existe déjà pour lpBuffer.
Les noms de partage et de volume sont des entrées valides pour lpFileName. Par exemple, la liste suivante identité le chemin d’accès retourné et les noms de fichiers si test-2 est un ordinateur distant et U : est un lecteur mappé réseau dont le répertoire actuel est la racine du volume :
- Si vous spécifiez « \\test-2\q$\lh », le chemin retourné est « \\test-2\q$\lh »
- Si vous spécifiez « \\ ?\UNC\test-2\q$\lh », le chemin d’accès retourné est « \\ ?\UNC\test-2\q$\lh »
- Si vous spécifiez « U : » le chemin retourné est le répertoire actif sur le lecteur « U :\ »
Si la valeur de retour est supérieure ou égale à la valeur spécifiée dans nBufferLength, vous pouvez appeler à nouveau la fonction avec une mémoire tampon suffisamment grande pour contenir le chemin. Pour obtenir un exemple de ce cas en plus d’utiliser la mémoire tampon de longueur nulle pour l’allocation dynamique, consultez la section Exemple de code.
Les chemins relatifs passés à la fonction GetFullPathName sont interprétés comme relatifs au répertoire actif du processus.
L’état du répertoire actuel écrit par la fonction SetCurrentDirectory
Pour éviter les problèmes causés par des résultats incohérents, les applications multithread et le code de bibliothèque partagée doivent éviter d’utiliser des chemins relatifs. Si un chemin relatif est reçu, il doit être consommé exactement une fois, soit en passant le chemin relatif directement à une fonction comme CreateFile, soit en le convertissant en chemin absolu et en utilisant le chemin absolu à partir de ce point vers l’avant.
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 C++ suivant montre une utilisation de base de GetFullPathName, GetLongPathNameet GetShortPathName. Pour obtenir un autre exemple d’allocation dynamique, consultez GetShortPathName.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE 4096
#define LONG_DIR_NAME TEXT("c:\\longdirectoryname")
void _tmain(int argc, TCHAR *argv[])
{
DWORD retval=0;
BOOL success;
TCHAR buffer[BUFSIZE]=TEXT("");
TCHAR buf[BUFSIZE]=TEXT("");
TCHAR** lppPart={NULL};
if( argc != 2 )
{
_tprintf(TEXT("Usage: %s [file]\n"), argv[0]);
return;
}
// Retrieve the full path name for a file.
// The file does not need to exist.
retval = GetFullPathName(argv[1],
BUFSIZE,
buffer,
lppPart);
if (retval == 0)
{
// Handle an error condition.
printf ("GetFullPathName failed (%d)\n", GetLastError());
return;
}
else
{
_tprintf(TEXT("The full path name is: %s\n"), buffer);
if (lppPart != NULL && *lppPart != 0)
{
_tprintf(TEXT("The final component in the path name is: %s\n"), *lppPart);
}
}
// Create a long directory name for use with the next two examples.
success = CreateDirectory(LONG_DIR_NAME,
NULL);
if (!success)
{
// Handle an error condition.
printf ("CreateDirectory failed (%d)\n", GetLastError());
return;
}
// Retrieve the short path name.
retval = GetShortPathName(LONG_DIR_NAME,
buf,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetShortPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The short name for %s is %s\n"),
LONG_DIR_NAME, buf);
// Retrieve the long path name.
retval = GetLongPathName(buf,
buffer,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetLongPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The long name for %s is %s\n"), buf, buffer);
// Clean up the directory.
success = RemoveDirectory(LONG_DIR_NAME);
if (!success)
{
// Handle an error condition.
printf ("RemoveDirectory failed (%d)\n", GetLastError());
return;
}
}
Note
L’en-tête fileapi.h définit GetFullPathName 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 XP [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | fileapi.h (include Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |