Función GetLongPathNameA (fileapi.h)

Artículo
02/28/2024

Convierte la ruta de acceso especificada a su formato largo.

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.

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

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

Requisito	Value
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