Función GetLongPathNameA (fileapi.h)

Artículo
11/20/2024

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 archivo y ruta de acceso, vea archivos de nomenclatura, rutas de acceso y espacios de nombres.

Sintaxis

DWORD GetLongPathNameA(
  [in]  LPCSTR lpszShortPath,
  [out] LPSTR  lpszLongPath,
  [in]  DWORD  cchBuffer
);

Parámetros

[in] lpszShortPath

Ruta de acceso que se va a convertir.

[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, 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.

Observaciones

En muchos sistemas de archivos, un nombre de archivo corto contiene un carácter 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 obtener 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 nombres largos de archivos de nomenclatura, 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	Soportado
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 (ReFS)	Sí

Ejemplos

Para obtener un ejemplo que usa GetLongPathName, vea la sección Código de ejemplo de 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 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2003 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	fileapi.h (incluya Windows.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll