Función GetFullPathNameTransactedW (winbase.h)

Artículo
03/08/2023

[Microsoft recomienda encarecidamente que los desarrolladores usen medios alternativos para lograr las necesidades de la aplicación. Muchos escenarios para los que se desarrolló TxF se pueden lograr mediante técnicas más sencillas y disponibles. Además, es posible que TxF no esté disponible en versiones futuras de Microsoft Windows. Para más información y alternativas a TxF, consulte Alternativas al uso de NTFS transaccional].

Recupera la ruta de acceso completa y el nombre de archivo del archivo especificado como una operación de transacción.

Para realizar esta operación sin transacciones, use la función GetFullPathName .

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

Sintaxis

DWORD GetFullPathNameTransactedW(
  [in]  LPCWSTR lpFileName,
  [in]  DWORD   nBufferLength,
  [out] LPWSTR  lpBuffer,
  [out] LPWSTR  *lpFilePart,
  [in]  HANDLE  hTransaction
);

Parámetros

[in] lpFileName

Nombre del archivo.

Esta cadena puede usar nombres de archivo cortos (formulario 8.3) o largos. Esta cadena puede ser un recurso compartido o un nombre de volumen.

El archivo debe residir en el equipo local; de lo contrario, se produce un error en la función y el último código de error se establece en ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] nBufferLength

Tamaño del búfer para recibir la cadena terminada en NULL para la unidad y la ruta de acceso, en TCHAR.

[out] lpBuffer

Puntero a un búfer que recibe la cadena terminada en null para la unidad y la ruta de acceso.

[out] lpFilePart

Puntero a un búfer que recibe la dirección (en lpBuffer) del componente de nombre de archivo final en la ruta de acceso. Especifique NULL si no necesita recibir esta información.

Si lpBuffer apunta a un directorio y no a un archivo, lpFilePart recibe 0 (cero).

[in] hTransaction

Identificador de la transacción. La función CreateTransaction devuelve este identificador.

Valor devuelto

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

Comentarios

GetFullPathNameTransacted combina el nombre de la unidad actual y el directorio con un nombre de archivo especificado para determinar la ruta de acceso completa y el nombre de archivo de un archivo especificado. También calcula la dirección de la parte del nombre de archivo de la ruta de acceso completa y el nombre de archivo. Esta función no comprueba que la ruta de acceso resultante y el nombre de archivo sean válidos o que vean un archivo existente en el volumen asociado.

Los nombres de recurso compartido y de volumen son una entrada válida para lpFileName. Por ejemplo, en la lista siguiente se muestran las identidades de la ruta de acceso devuelta y los nombres de archivo si test-2 es un equipo remoto y U: es una unidad asignada a la red:

Si especifica "\\test-2\q$\lh", la ruta de acceso devuelta es "\\test-2\q$\lh"
Si especifica "\\\?\UNC\test-2\q$\lh", la ruta de acceso devuelta es "\\?\UNC\test-2\q$\lh"
Si especifica "U:", la ruta de acceso devuelta es "U:\"

GetFullPathNameTransacted no convierte el nombre de archivo especificado, lpFileName. Si el nombre de archivo especificado existe, puede usar GetLongPathNameTransacted, GetLongPathName o GetShortPathName para convertir a nombres de ruta de acceso largos o cortos, respectivamente.

Si el valor devuelto es mayor que el valor especificado en nBufferLength, 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, así como 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.

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

SMB 3.0 no admite TxF.

Nota

El encabezado winbase.h define GetFullPathNameTransacted 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 Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbase.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll