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.

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.

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.

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);
}

Requisitos

Vea también

Funciones de administración de archivos