Función GetFullPathNameW (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 GetFullPathNameW(
[in] LPCWSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPWSTR lpBuffer,
[out] LPWSTR *lpFilePart
);
Parámetros
[in] lpFileName
Nombre del archivo.
Este parámetro puede ser un nombre de archivo corto (formulario 8.3) o largo. Esta cadena también puede ser un nombre de recurso compartido o de volumen.
De forma predeterminada, el nombre está limitado a MAX_PATH caracteres. Para ampliar este límite a 32 767 caracteres anchos, anteponga "\\?\\ " a la ruta de acceso. Para obtener más información, vea Nomenclatura de archivos, rutas de acceso y espacios de nombres.
Sugerencia
A partir de Windows 10, versión 1607, puede optar por quitar la limitación de MAX_PATH sin prepending "\\?\". Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Nombres de archivos, rutas de acceso y espacios de nombres para obtener más información.
[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 realiza 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 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 de 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 recurso compartido y de volumen 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 a la 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 "U:\" Conducir
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 ver un ejemplo de este caso además de usar el búfer de longitud cero para la asignación dinámica, consulte 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 puede cambiarse 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 generar 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 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 siguientes tecnologías.
| 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 mediante la asignación dinámica, vea 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 Convenciones para prototipos de función.
Requisitos
| 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 (incluye Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |