GetFullPathNameA, fonction (fileapi.h)
Récupère le chemin d’accès complet et le nom du fichier .wim 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 nom de fichier court (le formulaire 8.3) ou long. Cette chaîne peut également être un nom de partage ou de volume.
[in] nBufferLength
Taille de la mémoire tampon pour recevoir la chaîne terminée par null pour le lecteur et le chemin d’accès, dans les 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 retournée
Si la fonction réussit, la valeur de retour est la longueur, en TCHAR, de la chaîne copiée dans lpBuffer, sans inclure le caractère null de fin.
Si la mémoire tampon lpBuffer est trop petite pour contenir le chemin, la valeur de retour correspond à la taille, en TCHAR, de la mémoire tampon requise pour contenir le chemin et le 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
GetFullPathName fusionne le nom du lecteur et du répertoire actuels 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 du 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 uniquement suffisant pour une seule adresse. En effet, 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 et les noms de fichiers retournés 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 d’accès 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 d’accès 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 de l’utilisation d’une mémoire tampon de longueur nulle pour l’allocation dynamique, consultez la section Exemple de code.
Les chemins d’accès 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 est global au processus et peut être modifié par n’importe quel thread à tout moment. Les applications doivent savoir que les appels consécutifs à la fonction GetFullPathName avec un chemin relatif peuvent produire des résultats différents si le répertoire actif change entre les deux appels.
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 d’accès relatifs. Si un chemin d’accès relatif est reçu, il doit être consommé une seule fois, soit en passant le chemin d’accès relatif directement à une fonction comme CreateFile, soit en le convertissant en chemin absolu et en utilisant le chemin absolu à partir de ce point.
Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.
| Technologie | Prise en charge |
|---|---|
| Protocole Server Message Block (SMB) 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 |
| Système de fichiers du volume partagé de cluster (CsvFS) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
Exemples
L’exemple C++ suivant montre une utilisation de base de GetFullPathName, GetLongPathName et 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;
}
}
Notes
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. La combinaison 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | fileapi.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |