Función GetLongPathNameW (fileapi.h)

Artículo
06/02/2023

Convierte la ruta de acceso especificada en su forma larga.

Para realizar esta operación como una operación de transacción, use la función GetLongPathNameTransacted .

Para obtener más información sobre los nombres de archivos y rutas de acceso, vea Nombres de archivos, rutas de acceso y espacios de nombres.

Importante

Para usar esta función, el autor de la llamada debe tener los siguientes permisos en la ruta de acceso y los directorios primarios especificados:

Carpeta de lista
Leer datos
Atributos de lectura

Sintaxis

DWORD GetLongPathNameW(
  [in]  LPCWSTR lpszShortPath,
  [out] LPWSTR  lpszLongPath,
  [in]  DWORD   cchBuffer
);

Parámetros

[in] lpszShortPath

Ruta de acceso que se va a convertir.

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.

[out] lpszLongPath

Puntero al búfer para recibir la ruta de acceso larga.

Puede usar el mismo búfer que usó para el parámetro lpszShortPath .

[in] cchBuffer

El tamaño del búfer lpszLongPath apunta a, en TCHAR.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es la longitud, en TCHAR, de la cadena copiada en lpszLongPath, 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, como si el archivo no existe, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

En muchos sistemas de archivos, un nombre de archivo corto contiene un carácter de tilde (~). Sin embargo, no todos los sistemas de archivos siguen esta convención. Por lo tanto, no suponga que puede omitir la llamada a GetLongPathName si la ruta de acceso no contiene un carácter de tilde (~).

Si el archivo o directorio existe pero no se encuentra una ruta de acceso larga, GetLongPathName se realiza correctamente, después de copiar la cadena a la que hace referencia el parámetro lpszShortPath al búfer al que hace referencia el parámetro lpszLongPath .

Si el valor devuelto es mayor que el valor especificado en cchBuffer, 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, vea la sección Código de ejemplo para GetFullPathName.

Nota Aunque el valor devuelto en este caso es una longitud que incluye el carácter nulo de terminación, el valor devuelto en success no incluye el carácter nulo de terminación en el recuento.

Es posible tener acceso a un archivo o directorio, pero no tener acceso a algunos de los directorios primarios de ese archivo o directorio. Como resultado, GetLongPathName puede producir un error cuando no puede consultar el directorio primario de un componente de ruta de acceso para determinar el nombre largo de ese componente. Esta comprobación se puede omitir para los componentes de directorio que tienen extensiones de archivo de más de 3 caracteres o longitudes totales de más de 12 caracteres. Para obtener más información, vea la sección Nombres cortos frente a largos de nombres de archivos, rutas de acceso y espacios de nombres.

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

Para obtener un ejemplo que use GetLongPathName, vea la sección Código de ejemplo para GetFullPathName.

Nota:

El encabezado fileapi.h define GetLongPathName 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


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