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 nombre de recurso compartido o 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.
Comentarios
GetFullPathName combina el nombre de la unidad y el directorio actuales 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 cadena, 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 recursos compartidos y volúmenes son una entrada válida para lpFileName. Por ejemplo, en la lista siguiente se muestran 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 de 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 que se pasan a la función GetFullPathName 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 se puede cambiar por cualquier subproceso en cualquier momento. Las aplicaciones deben tener en cuenta que las llamadas consecutivas a la función GetFullPathName 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 compartido 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 convirtiéndola en una ruta de acceso absoluta y usando la ruta de acceso absoluta desde ese punto hacia delante.
En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.
| Tecnología | Compatible |
|---|---|
| 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 a errores (ReFS) | Sí |
Ejemplos
En el siguiente ejemplo de C++ se muestra un uso básico de GetFullPathName, GetLongPathName y 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows XP [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | fileapi.h (incluya Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |