Compartir a través de


Función GetFinalPathNameByHandleA (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 GetFinalPathNameByHandleA(
  [in]  HANDLE hFile,
  [out] LPSTR  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
FILE_NAME_NORMALIZED
0x0
Devuelve el nombre de la unidad normalizada. Este es el valor predeterminado.
FILE_NAME_OPENED
0x8
Devuelve el nombre de archivo abierto (no normalizado).
 

Este parámetro también puede incluir uno de los valores siguientes.

Valor Significado
VOLUME_NAME_DOS
0x0
Devuelve la ruta de acceso con la letra de unidad. Este es el valor predeterminado.
VOLUME_NAME_GUID
0x1
Devuelve la ruta de acceso con una ruta de acceso GUID de volumen en lugar del nombre de la unidad.
VOLUME_NAME_NONE
0x4
Devuelve la ruta de acceso sin información de unidad.
VOLUME_NAME_NT
0x2
Devuelve la ruta de acceso con la ruta de acceso del dispositivo de volumen.

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
ERROR_PATH_NOT_FOUND
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.

ERROR_NOT_ENOUGH_MEMORY
Memoria insuficiente para completar la operación.
ERROR_INVALID_PARAMETER
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".

La cadena devuelta por esta función usa la sintaxis "\\?\\ ". Para obtener más información, consulte CreateFile.

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
Conmutación por error transparente (TFO) de SMB 3.0
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)
Sistema de archivos de Volumen compartido de clúster (CsvFS)
Sistema de archivos resistente a errores (ReFS)
 

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

Requisito Value
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 (incluye Windows.h)
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también

Funciones de administración de archivos