Función GetFinalPathNameByHandleW (fileapi.h)
Recupera la ruta de acceso final del archivo especificado.
Para obtener más información sobre los nombres de archivo y ruta de acceso, consulte Nomenclatura de un archivo.
Sintaxis
DWORD GetFinalPathNameByHandleW(
[in] HANDLE hFile,
[out] LPWSTR lpszFilePath,
[in] DWORD cchFilePath,
[in] DWORD dwFlags
);
Parámetros
[in] hFile
Identificador de un archivo o directorio.
[out] lpszFilePath
Puntero a un búfer que recibe la ruta de acceso de hFile.
[in] cchFilePath
Tamaño de lpszFilePath, en TCHARs. Este valor debe incluir un carácter de terminación NULL .
[in] dwFlags
El tipo de resultado que se va a devolver. Este parámetro puede ser uno de los valores siguientes.
| Valor | Significado |
|---|---|
|
Devuelve el nombre de la unidad normalizada. Este es el valor predeterminado. |
|
Devuelve el nombre de archivo abierto (no normalizado). |
Este parámetro también puede incluir uno de los valores siguientes.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es la longitud de la cadena recibida por lpszFilePath, en TCHARs. Este valor no incluye el tamaño del carácter nulo de terminación.
Windows Server 2008 y Windows Vista: Para la versión ANSI de esta función, GetFinalPathNameByHandleA, el valor devuelto incluye el tamaño del carácter nulo de terminación.
Si se produce un error en la función porque lpszFilePath es demasiado pequeño para contener la cadena más el carácter nulo de terminación, el valor devuelto es el tamaño de búfer necesario, en TCHARs. Este valor incluye el tamaño del 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.
| Código devuelto | Descripción |
|---|---|
|
Se puede devolver si busca una letra de unidad y no existe. Por ejemplo, el identificador se abrió en una unidad que no está montada actualmente, o si crea un volumen y no lo asigna una letra de unidad. Si un volumen no tiene ninguna letra de unidad, puede usar la ruta de acceso GUID del volumen para identificarlo.
Este valor devuelto también se puede devolver si busca una ruta de acceso GUID de volumen en un recurso compartido de red. Las rutas de acceso guid de volumen no se crean para los recursos compartidos de red. |
|
Memoria insuficiente para completar la operación. |
|
Se especificaron marcas no válidas para dwFlags. |
Comentarios
El protocolo bloque de mensajes del servidor (SMB) no admite consultas para rutas de acceso normalizadas. Por lo tanto, cuando se llama a esta función pasando el identificador de un archivo abierto mediante SMB y con la marca FILE_NAME_NORMALIZED, la función divide la ruta de acceso en sus componentes e intenta consultar el nombre normalizado de cada uno de esos componentes a su vez. Si el usuario no tiene permiso de acceso a cualquiera de esos componentes, se produce un error en la llamada de función con ERROR_ACCESS_DENIED.
Una ruta de acceso final es la ruta de acceso que se devuelve cuando una ruta de acceso se resuelve por completo. Por ejemplo, para un vínculo simbólico denominado "C:\tmp\mydir" que apunta a "D:\yourdir", la ruta de acceso final sería "D:\yourdir".
Cuando se usa VOLUME_NAME_DOS, la cadena devuelta por esta función usa la sintaxis "\\?\\". Para obtener más información, consulte CreateFile.
Al usar VOLUME_NAME_GUID, la ruta de acceso devuelta comenzará con una ruta de acceso GUID de volumen con formato "\\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\".
Al usar VOLUME_NAME_NT, la ruta de acceso devuelta es para un objeto de dispositivo NT y comenzará con un nombre de dispositivo como "\Device\HarddiskVolume1\". Los programas de Windows no pueden usar directamente este tipo de ruta de acceso, ya que se parece a una ruta de acceso relativa.
Algunos controladores de terceros pueden crear una letra de unidad o un punto de montaje sin usar el Administrador de montaje. Si el Administrador de montaje no se usó para crear la unidad, VOLUME_NAME_DOS o VOLUME_NAME_GUID no se realizarán correctamente; solo VOLUME_NAME_NT estarán disponibles. Para determinar la letra de unidad de la ruta de acceso del dispositivo de volumen, use la función QueryDosDevice en cada letra de unidad hasta que se encuentre un nombre de dispositivo coincidente.
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 ejemplo siguiente se muestra el uso de la función GetFinalPathNameByHandle .
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE MAX_PATH
void __cdecl _tmain(int argc, TCHAR *argv[])
{
TCHAR Path[BUFSIZE];
HANDLE hFile;
DWORD dwRet;
printf("\n");
if( argc != 2 )
{
printf("ERROR:\tIncorrect number of arguments\n\n");
printf("%s <file_name>\n", argv[0]);
return;
}
hFile = CreateFile(argv[1], // file to open
GENERIC_READ, // open for reading
FILE_SHARE_READ, // share for reading
NULL, // default security
OPEN_EXISTING, // existing file only
FILE_ATTRIBUTE_NORMAL, // normal file
NULL); // no attr. template
if( hFile == INVALID_HANDLE_VALUE)
{
printf("Could not open file (error %d\n)", GetLastError());
return;
}
dwRet = GetFinalPathNameByHandle( hFile, Path, BUFSIZE, VOLUME_NAME_NT );
if(dwRet < BUFSIZE)
{
_tprintf(TEXT("\nThe final path is: %s\n"), Path);
}
else printf("\nThe required buffer size is %d.\n", dwRet);
CloseHandle(hFile);
}
Nota:
El encabezado fileapi.h define GetFinalPathNameByHandle 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 Vista [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | fileapi.h (incluya Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |