Función GetFullPathNameA (fileapi.h)
Recupera la ruta de acceso completa y el nombre de archivo del archivo especificado.
Para realizar esta operación como una operación de transacción, use la función GetFullPathNameTransacted.
Para obtener más información sobre los nombres de archivo y ruta de acceso, vea nombres de archivo, rutas de acceso y espacios de nombres.
Sintaxis
DWORD GetFullPathNameA(
[in] LPCSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPSTR lpBuffer,
[out] LPSTR *lpFilePart
);
Parámetros
[in] lpFileName
Nombre del archivo.
Este parámetro puede ser un nombre de archivo corto (el formulario 8.3) o largo. Esta cadena también puede ser un recurso compartido o un nombre de volumen.
[in] nBufferLength
Tamaño del búfer para recibir la cadena terminada en NULL para la unidad y la ruta de acceso, en TCHAR.
[out] lpBuffer
Puntero a un búfer que recibe la cadena terminada en NULL para la unidad y la ruta de acceso.
[out] lpFilePart
Puntero a un búfer que recibe la dirección (dentro de lpBuffer) del componente de nombre de archivo final en la ruta de acceso.
Este parámetro puede ser null.
Si lpBuffer hace referencia a un directorio y no a un archivo, lpFilePart recibe cero.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es la longitud, en TCHAR, de la cadena copiada en lpBuffer, sin incluir el carácter nulo de terminación.
Si el búfer lpBuffer es demasiado pequeño para contener la ruta de acceso, el valor devuelto es el tamaño, en TCHAR, del búfer necesario para contener la ruta de acceso y el carácter nulo de terminación.
Si se produce un error en la función por cualquier otro motivo, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
Observaciones
GetFullPathName combina el nombre de la unidad y directorio actual con un nombre de archivo especificado para determinar la ruta de acceso completa y el nombre de archivo de un archivo especificado. También calcula la dirección de la parte del nombre de archivo de la ruta de acceso completa y el nombre de archivo.
Esta función no comprueba que la ruta de acceso resultante y el nombre de archivo sean válidos o que vean un archivo existente en el volumen asociado.
Tenga en cuenta que el parámetro lpFilePart no requiere espacio en búfer de cadenas, sino solo suficiente para una sola dirección. Esto se debe a que simplemente devuelve una dirección dentro del búfer que ya existe para lpBuffer.
Los nombres de recurso compartido y volumen son entradas válidas para lpFileName. Por ejemplo, en la lista siguiente se enumeran las identidades de la ruta de acceso y los nombres de archivo devueltos si test-2 es un equipo remoto y U: es una unidad asignada por red cuyo directorio actual es la raíz del volumen:
- Si especifica "\\test-2\q$\lh", la ruta de acceso devuelta es "\\test-2\q$\lh"
- Si especifica "\\\?\UNC\test-2\q$\lh", la ruta de acceso devuelta es "\\?\UNC\test-2\q$\lh"
- Si especifica "U:", la ruta de acceso devuelta es el directorio actual en la unidad "U:\"
Si el valor devuelto es mayor o igual que el valor especificado en nBufferLength, puede llamar a la función de nuevo con un búfer lo suficientemente grande como para contener la ruta de acceso. Para obtener un ejemplo de este caso además de usar el búfer de longitud cero para la asignación dinámica, vea la sección Código de ejemplo.
Las rutas de acceso relativas pasadas al GetFullPathName función se interpretan como relativas al directorio actual del proceso. El estado del directorio actual escrito por la función SetCurrentDirectory es global para el proceso y cualquier subproceso puede cambiarlo en cualquier momento. Las aplicaciones deben tener en cuenta que las llamadas consecutivas a la GetFullPathName función con una ruta de acceso relativa pueden producir resultados diferentes si el directorio actual cambia entre las dos llamadas.
Para evitar problemas causados por resultados incoherentes, las aplicaciones multiproceso y el código de biblioteca compartida deben evitar el uso de rutas de acceso relativas. Si se recibe una ruta de acceso relativa, se debe consumir exactamente una vez, pasando la ruta de acceso relativa directamente a una función como CreateFile, o convirtiendola en una ruta de acceso absoluta y usando la ruta de acceso absoluta desde ese punto hacia adelante.
En Windows 8 y Windows Server 2012, esta función es compatible con las siguientes tecnologías.
| Tecnología | Soportado |
|---|---|
| Protocolo bloque de mensajes del servidor (SMB) 3.0 | Sí |
| Conmutación por error transparente (TFO) de SMB 3.0 | Sí |
| SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO) | Sí |
| Sistema de archivos de volumen compartido de clúster (CsvFS) | Sí |
| Sistema de archivos resistente (ReFS) | Sí |
Ejemplos
En el siguiente ejemplo de C++ se muestra un uso básico de GetFullPathName, GetLongPathNamey GetShortPathName. Para obtener otro ejemplo con la asignación dinámica, consulte 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;
}
}
Nota
El encabezado fileapi.h define GetFullPathName como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows XP [aplicaciones de escritorio | Aplicaciones para UWP] |
| servidor mínimo admitido | Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP] |
| de la plataforma de destino de |
Windows |
| encabezado de |
fileapi.h (incluya Windows.h) |
| biblioteca de |
Kernel32.lib |
| DLL de |
Kernel32.dll |
Consulte también
funciones de administración de archivos