Función GetShortPathNameW (fileapi.h)

Artículo
03/05/2024

Recupera el formato corto de ruta de acceso de la ruta de acceso especificada.

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

Sintaxis

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

Parámetros

[in] lpszLongPath

Cadena de ruta de acceso.

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

Puntero a un búfer para recibir la forma abreviada terminada en null de la ruta de acceso que lpszLongPath especifica.

Pasar NULL para este parámetro y cero para cchBuffer siempre devolverá el tamaño de búfer necesario para un lpszLongPath especificado.

[in] cchBuffer

Tamaño del búfer al que lpszShortPath apunta, en TCHAR.

Establezca este parámetro en cero si lpszShortPath está establecido en NULL.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es la longitud, en TCHAR, de la cadena que se copia en lpszShortPath, sin incluir el carácter nulo de terminación.

Si el búfer lpszShortPath es demasiado pequeño para contener la ruta de acceso, el valor devuelto es el tamaño del búfer, en TCHAR, 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, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La ruta de acceso que especifica el parámetro lpszLongPath no tiene que ser una ruta de acceso completa o larga. El formato corto puede ser mayor que la ruta de acceso especificada.

Si el valor devuelto es mayor que el valor especificado en el parámetro 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 además de usar el búfer de longitud cero para la asignación dinámica, consulte la sección Código de ejemplo.

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.

Si la ruta de acceso especificada ya está en su formato corto y no es necesaria la conversión, la función simplemente copia la ruta de acceso especificada al búfer especificado por el parámetro lpszShortPath .

Puede establecer el parámetro lpszShortPath en el mismo valor que el parámetro lpszLongPath ; es decir, puede establecer el búfer de salida para la ruta de acceso corta a la dirección de la cadena de ruta de acceso de entrada. Asegúrese siempre de que el parámetro cchBuffer representa con precisión el tamaño total, en TCHAR, de este búfer.

Puede obtener el nombre largo de un archivo con el nombre corto llamando a la función GetLongPathName . Como alternativa, donde GetLongPathName no está disponible, puede llamar a FindFirstFile en cada componente de la ruta de acceso para obtener el nombre largo correspondiente.

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, GetShortPathName puede producir un error cuando no puede consultar el directorio primario de un componente de ruta de acceso para determinar el nombre corto de ese componente. Esta comprobación se puede omitir para los componentes de directorio que ya cumplen los requisitos de un nombre corto. 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	No
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	No
Sistema de archivos de Volumen compartido de clúster (CsvFS)	No
Sistema de archivos resistente a errores (ReFS)	Sí

SMB 3.0 no admite nombres cortos en recursos compartidos con capacidad de disponibilidad continua.

El sistema de archivos resistente (ReFS) no admite nombres cortos. Si llama a GetShortPathName en una ruta de acceso que no tiene nombres cortos en el disco, la llamada se realizará correctamente, pero devolverá la ruta de acceso de nombre largo en su lugar. Este resultado también es posible con volúmenes NTFS porque no hay ninguna garantía de que exista un nombre corto para un nombre largo determinado.

Ejemplos

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

En el siguiente ejemplo de C++ se muestra cómo usar un búfer de salida asignado dinámicamente.

//...
    long     length = 0;
    TCHAR*   buffer = NULL;

// First obtain the size needed by passing NULL and 0.

    length = GetShortPathName(lpszPath, NULL, 0);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

// Dynamically allocate the correct size 
// (terminating null char was included in length)

    buffer = new TCHAR[length];

// Now simply call again using same long path.

    length = GetShortPathName(lpszPath, buffer, length);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

    _tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
    
    delete [] buffer;
///...

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	fileapi.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll