Función GetVolumePathNameW (fileapi.h)

  • Artículo

Recupera el punto de montaje del volumen donde se monta la ruta de acceso especificada.

Sintaxis

BOOL GetVolumePathNameW(
  [in]  LPCWSTR lpszFileName,
  [out] LPWSTR  lpszVolumePathName,
  [in]  DWORD   cchBufferLength
);

Parámetros

[in] lpszFileName

Puntero a la cadena de ruta de acceso de entrada. Los nombres de archivo y directorio absolutos y relativos, por ejemplo, "..", son aceptables en esta ruta de acceso.

Si especifica un directorio o nombre de archivo relativo sin un calificador de volumen, GetVolumePathName devuelve la letra de unidad del volumen de arranque.

Si este parámetro es una cadena vacía, "", se produce un error en la función, pero el último error se establece en ERROR_SUCCESS.

[out] lpszVolumePathName

Puntero a una cadena que recibe el punto de montaje del volumen para la ruta de acceso de entrada.

[in] cchBufferLength

Longitud del búfer de salida, en TCHAR.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Si se pasa una ruta de acceso especificada, GetVolumePathName devuelve la ruta de acceso al punto de montaje del volumen, lo que significa que devuelve la raíz del volumen donde se encuentra el punto final de la ruta de acceso especificada.

Por ejemplo, supongamos que tiene el volumen D montado en C:\Mnt\Ddrive y el volumen E montado en C:\Mnt\Ddrive\Mnt\Edrive. Suponga también que tiene un archivo con la ruta de acceso E:\Dir\Subdir\MyFile. Si pasa C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile a GetVolumePathName, devuelve la ruta de acceso C:\Mnt\Ddrive\Mnt\Edrive\.

Si se pasa un directorio relativo o un archivo sin un calificador de volumen, la función devuelve la letra de unidad del volumen de arranque. La letra de unidad del volumen de arranque también se devuelve si se especifica un nombre de archivo o directorio no válido sin un calificador de volumen válido. Si se proporciona un especificador de volumen válido y el volumen existe, pero se especifica un nombre de archivo o directorio no válido, la función se realizará correctamente y se devolverá ese nombre de volumen. Para obtener ejemplos, vea la sección Ejemplos de este tema.

Debes especificar una ruta de acceso de espacio de nombres Win32 válida. Si especifica una ruta de acceso de espacio de nombres NT, por ejemplo, \DosDevices\H: o \Device\HardDiskVolume6, la función devuelve la letra de unidad del volumen de arranque, no la letra de unidad de esa ruta de acceso del espacio de nombres NT.

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

Puede especificar rutas de acceso locales y remotas. Si especifica una ruta de acceso local, GetVolumePathName devuelve una ruta de acceso completa cuyo prefijo es el prefijo más largo que representa un volumen.

Si se especifica un recurso compartido de red, GetVolumePathName devuelve la ruta de acceso más corta para la que GetDriveType devuelve DRIVE_REMOTE, lo que significa que la ruta de acceso se valida como una unidad remota que existe, a la que puede acceder el usuario actual.

Hay ciertos casos especiales que no devuelven una barra diagonal inversa final. Estos se producen cuando la longitud del búfer de salida es un carácter demasiado corto. Por ejemplo, si lpszFileName es y lpszVolumePathName tiene 4 caracteres, el valor devuelto es C:\; sin embargo, si lpszVolumePathName tiene C: 3 caracteres, el valor devuelto es C:. Una manera más segura pero más lenta de establecer el tamaño del búfer de devolución es llamar a la función GetFullPathName y, a continuación, asegurarse de que el tamaño del búfer sea al menos el mismo tamaño que la ruta de acceso completa que devuelve GetFullPathName . Si el búfer de salida es más de un carácter demasiado corto, se producirá un error en la función y se devolverá un error.

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 No
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) Sí
Sistema de archivos resistente a errores (ReFS) Sí

SMB no admite funciones de administración de volúmenes.

Elementos de ruta de acceso finales

Los elementos de ruta de acceso finales que no son válidos se omiten. En el caso de las rutas de acceso remotas, toda la ruta de acceso (no solo los elementos finales) se considera no válida si se cumple una de las condiciones siguientes:

  • La ruta de acceso no se forma correctamente.
  • La ruta de acceso no existe.
  • El usuario actual no tiene acceso a la ruta de acceso.

Puntos de unión y carpetas montadas

Si la ruta de acceso especificada atraviesa un punto de unión, GetVolumePathName devuelve el volumen al que hace referencia el punto de unión. Por ejemplo, si W:\Adir es un punto de unión que apunta a C:\Adir, GetVolumePathName invocado en W:\Adir\Afile devuelve C:\. Si la ruta de acceso especificada atraviesa varios puntos de unión, se sigue toda la cadena y GetVolumePathName devuelve el volumen al que hace referencia el último punto de unión de la cadena.

Si se especifica una ruta de acceso remota a una carpeta montada o un punto de unión, la ruta de acceso se analiza como una ruta de acceso remota y se omite la carpeta montada o el punto de unión. Por ejemplo, si C:\Dir_C está vinculado a D:\Dir_D y C: se asigna a X: en un equipo remoto, llamar a GetVolumePathName y especificar X:\Dir_C en el equipo remoto devuelve X:\.

Ejemplos

Para el siguiente conjunto de ejemplos, U: se asigna al equipo \\_YourComputer_\C$remoto y Q es una unidad local.

Ruta de acceso especificada La función devuelve
\\_YourComputer_\C$\Windows \\_YourComputer_\C$\
\\?\UNC\_YourComputer_\C$\Windows \\?\UNC\_YourComputer_\C$\
Q:\Windows Q:\
\\?\Q:\Windows \\?\Q:\
\\.\Q:\Windows \\.\Q:\
\\?\UNC\W:\Windows FALSE con el error 123 porque una ruta de acceso remota especificada no era válida; El recurso compartido W$ no existe o no se concede acceso de usuario.
C:\COM2 (que existe) \\.\COM2\
C:\COM3 (no existente) FALSE con el error 123 porque se especificó un dispositivo COM inexistente.

Para el siguiente conjunto de ejemplos, las rutas de acceso contienen elementos de ruta final no válidos.

Ruta de acceso especificada La función devuelve
G:\invalid (ruta de acceso no válida) G:\
\\.\I:\aaa\invalid (ruta de acceso no válida) \\.\I:\
\\_YourComputer_\C$\invalid (elemento de ruta de acceso final no válido) \\_YourComputer_\C$\

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

Vea también