Función CreateFileTransactedA (winbase.h)
[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].
Crea o abre un archivo, una secuencia de archivos o un directorio como una operación de transacción. La función devuelve un identificador que se puede usar para tener acceso al objeto .
Para realizar esta operación como una operación no transaccionada o para tener acceso a objetos distintos de los archivos (por ejemplo, canalizaciones con nombre, dispositivos físicos, mailslots), use la función CreateFile .
Para obtener más información sobre las transacciones, vea la sección Comentarios de este tema.
Sintaxis
HANDLE CreateFileTransactedA(
[in] LPCSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwCreationDisposition,
[in] DWORD dwFlagsAndAttributes,
[in, optional] HANDLE hTemplateFile,
[in] HANDLE hTransaction,
[in, optional] PUSHORT pusMiniVersion,
PVOID lpExtendedParameter
);
Parámetros
[in] lpFileName
Nombre de un objeto que se va a crear o abrir.
El objeto 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.
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.
Para crear una secuencia de archivos, especifique el nombre del archivo, dos puntos y, a continuación, el nombre de la secuencia. Para obtener más información, vea Secuencias de archivos.
[in] dwDesiredAccess
Acceso al objeto , que se puede resumir como lectura, escritura, ambos o ninguno (cero). Los valores más usados son GENERIC_READ, GENERIC_WRITE o ambos (GENERIC_READ | GENERIC_WRITE). Para obtener más información, vea Derechos de acceso genéricos y Derechos de acceso y seguridad de archivos.
Si este parámetro es cero, la aplicación puede consultar atributos de archivo, directorio o dispositivo sin tener acceso a ese archivo o dispositivo. Para obtener más información, vea la sección Comentarios.
No se puede solicitar un modo de acceso que entre en conflicto con el modo de uso compartido especificado en una solicitud abierta que tenga un identificador abierto. Para más información, consulte Crear y abrir archivos.
[in] dwShareMode
Modo de uso compartido de un objeto, que se puede leer, escribir, ambos, eliminar, todos ellos o ninguno (consulte la tabla siguiente).
Si este parámetro es cero y CreateFileTransacted se ejecuta correctamente, el objeto no se puede compartir y no se puede volver a abrir hasta que se cierre el identificador. Para obtener más información, vea la sección Comentarios.
No se puede solicitar un modo de uso compartido que entre en conflicto con el modo de acceso especificado en una solicitud abierta que tenga un identificador abierto, ya que esto provocaría la siguiente infracción de uso compartido: ERROR_SHARING_VIOLATION. Para más información, consulte Crear y abrir archivos.
Para permitir que un proceso comparta un objeto mientras otro proceso tiene abierto el objeto, use una combinación de uno o varios de los valores siguientes para especificar el modo de acceso que pueden solicitar para abrir el objeto.
[in, optional] lpSecurityAttributes
Puntero a una estructura de SECURITY_ATTRIBUTES que contiene un descriptor de seguridad opcional y también determina si los procesos secundarios pueden heredar o no el identificador devuelto. El parámetro puede ser NULL.
Si el parámetro lpSecurityAttributes es NULL, el identificador devuelto por CreateFileTransacted no se puede heredar por ningún proceso secundario que la aplicación pueda crear y el objeto asociado al identificador devuelto obtiene un descriptor de seguridad predeterminado.
El miembro bInheritHandle de la estructura especifica si se puede heredar el identificador devuelto.
El miembro lpSecurityDescriptor de la estructura especifica un descriptor de seguridad para un objeto, pero también puede ser NULL.
Si el miembro lpSecurityDescriptor es NULL, al objeto asociado al identificador devuelto se le asigna un descriptor de seguridad predeterminado.
CreateFileTransacted omite el miembro lpSecurityDescriptor al abrir un archivo existente, pero sigue usando el miembro bInheritHandle .
Para obtener más información, vea la sección Comentarios.
[in] dwCreationDisposition
Acción que se va a hacer en los archivos que existen y que no.
Para obtener más información, vea la sección Comentarios.
Este parámetro debe ser uno de los valores siguientes, que no se pueden combinar.
[in] dwFlagsAndAttributes
Los atributos y marcas de archivo, FILE_ATTRIBUTE_NORMAL siendo el valor predeterminado más común.
Este parámetro puede incluir cualquier combinación de los atributos de archivo disponibles (FILE_ATTRIBUTE_*). Todos los demás atributos de archivo invalidan FILE_ATTRIBUTE_NORMAL.
Este parámetro también puede contener combinaciones de marcas (FILE_FLAG_) para controlar el comportamiento de almacenamiento en búfer, los modos de acceso y otras marcas de propósito especial. Se combinan con cualquier valor de FILE_ATTRIBUTE_ .
Este parámetro también puede contener información de calidad de servicio (SQOS) de seguridad especificando la marca SECURITY_SQOS_PRESENT . En la tabla se presenta información adicional sobre marcas relacionadas con SQOS siguiendo los atributos y las tablas de marcas.
Cuando CreateFileTransacted abre un archivo existente, generalmente combina las marcas de archivo con los atributos de archivo del archivo existente y omite los atributos de archivo proporcionados como parte de dwFlagsAndAttributes. Los casos especiales se detallan en Crear y abrir archivos.
| Atributo | Significado |
|---|---|
|
El archivo debe archivarse. Las aplicaciones usan este atributo para marcar los archivos para crear una copia de seguridad o quitarlos. |
|
El archivo o directorio está cifrado. Para un archivo, esto significa que todos los datos del archivo están cifrados. Para un directorio, esto significa que el cifrado es el valor predeterminado para los archivos y subdirectorios recién creados. Para obtener más información, vea Cifrado de archivos.
Esta marca no tiene ningún efecto si también se especifica FILE_ATTRIBUTE_SYSTEM . |
|
El archivo está oculto. No lo incluya en una lista de directorios normal. |
|
El archivo no tiene otros atributos establecidos. Este atributo solo es válido si se usa por sí solo. |
|
Los datos de un archivo no están disponibles inmediatamente. Este atributo indica que los datos de archivo se mueven físicamente al almacenamiento sin conexión. Este atributo lo usa El almacenamiento remoto, el software de administración de almacenamiento jerárquico. Las aplicaciones no deben cambiar arbitrariamente este atributo. |
|
El archivo es de solo lectura. Las aplicaciones pueden leer el archivo, pero no pueden escribir en él ni eliminarlo. |
|
El archivo forma parte o se usa exclusivamente por un sistema operativo. |
|
El archivo se usa para el almacenamiento temporal. Los sistemas de archivos evitan volver a escribir datos en almacenamiento masivo si hay suficiente memoria caché disponible, ya que una aplicación elimina un archivo temporal después de cerrar un identificador. En ese caso, el sistema puede evitar completamente escribir los datos. De lo contrario, los datos se escriben después de cerrar el identificador. |
| Marca | Significado |
|---|---|
|
El archivo se abre o se crea para una operación de copia de seguridad o restauración. El sistema garantiza que el proceso de llamada invalide las comprobaciones de seguridad de archivos cuando el proceso tiene privilegios de SE_BACKUP_NAME y SE_RESTORE_NAME . Para obtener más información, consulte Cambio de privilegios en un token.
Debe establecer esta marca para obtener un identificador en un directorio. Un identificador de directorio se puede pasar a algunas funciones en lugar de a un identificador de archivo. Para obtener más información, vea Identificadores de directorio. |
|
El archivo se va a eliminar inmediatamente después de que se cierre el último identificador del escritor de transacciones en el archivo, siempre que la transacción todavía esté activa. Si un archivo se ha marcado para su eliminación y un identificador de escritor de transacciones sigue abierto una vez completada la transacción, el archivo no se eliminará.
Si hay identificadores abiertos existentes en un archivo, se produce un error en la llamada a menos que todos se hayan abierto con el modo de recurso compartido de FILE_SHARE_DELETE . Se producirá un error en las solicitudes de apertura posteriores del archivo, a menos que se especifique el modo de recurso compartido FILE_SHARE_DELETE. |
|
El archivo se está abriendo sin almacenamiento en caché del sistema. Esta marca no afecta al almacenamiento en caché del disco duro ni a los archivos asignados a memoria. Cuando se combina con FILE_FLAG_OVERLAPPED, la marca proporciona un rendimiento asincrónico máximo, ya que la E/S no se basa en las operaciones sincrónicas del administrador de memoria.
Sin embargo, algunas operaciones de E/S tardan más tiempo, ya que los datos no se mantienen en la memoria caché. Además, es posible que los metadatos del archivo se sigan almacenando en caché. Para vaciar los metadatos en el disco, use la función FlushFileBuffers.
Una aplicación debe cumplir ciertos requisitos al trabajar con archivos abiertos con FILE_FLAG_NO_BUFFERING:
Una aplicación puede determinar un tamaño de sector de volumen llamando a la función GetDiskFreeSpace . |
|
Se solicitan los datos del archivo, pero deben seguir estando ubicados en el almacenamiento remoto. No se debe transportar de vuelta al almacenamiento local. Esta marca la usan los sistemas de almacenamiento remoto. |
|
No se producirá el procesamiento normal del punto de reanálisis ; CreateFileTransacted intentará abrir el punto de reanálisis. Cuando se abre un archivo, se devuelve un identificador de archivo, independientemente de si el filtro que controla el punto de reanálisis está operativo. Esta marca no se puede usar con la marca CREATE_ALWAYS . Si el archivo no es un punto de reanálisis, se omite esta marca. |
|
El archivo se abre o se crea para E/S asincrónica. Una vez completada la operación, el evento especificado en la estructura SUPERPUESTA se establece en el estado señalado. Las operaciones que tardan mucho tiempo en procesar la devolución ERROR_IO_PENDING.
Si se especifica esta marca, el archivo se puede usar para operaciones simultáneas de lectura y escritura. El sistema no mantiene el puntero de archivo, por lo tanto, debe pasar la posición del archivo a las funciones de lectura y escritura en la estructura SUPERPUESTA o actualizar el puntero de archivo. Si no se especifica esta marca, las operaciones de E/S se serializan, incluso si las llamadas a las funciones de lectura y escritura especifican una estructura SUPERPUESTA . |
|
Se tiene acceso al archivo según las reglas POSIX. Esto incluye permitir varios archivos con nombres, que solo difieren en el caso de los sistemas de archivos que admiten esa nomenclatura. Use cuidado al usar esta opción, ya que es posible que las aplicaciones escritas para MS-DOS o Windows de 16 bits no puedan acceder a los archivos creados con esta marca. |
|
Se va a tener acceso al archivo de forma aleatoria. El sistema puede considerar que esto es una sugerencia para optimizar el almacenamiento en caché del archivo. |
|
El archivo o dispositivo se está abriendo con reconocimiento de sesión. Si no se especifica esta marca, los procesos que se ejecutan en la sesión 0 no pueden abrir los dispositivos por sesión (por ejemplo, un dispositivo que usa el redireccionamiento USB de RemoteFX).
Esta marca no tiene ningún efecto para los llamadores que no están en la sesión 0. Esta marca solo se admite en las ediciones de servidor de Windows.
Windows Server 2008 R2 y Windows Server 2008: Esta marca no se admite antes de Windows Server 2012. |
|
Se va a acceder al archivo secuencialmente de principio a fin. El sistema puede considerar que esto es una sugerencia para optimizar el almacenamiento en caché del archivo. Si una aplicación mueve el puntero de archivo para el acceso aleatorio, es posible que no se produzca un almacenamiento en caché óptimo. Sin embargo, todavía se garantiza la operación correcta.
Especificar esta marca puede aumentar el rendimiento de las aplicaciones que leen archivos grandes mediante el acceso secuencial. Las mejoras de rendimiento pueden ser aún más notables para las aplicaciones que leen archivos grandes principalmente secuencialmente, pero ocasionalmente omiten intervalos pequeños de bytes. Esta marca no tiene ningún efecto si el sistema de archivos no admite la E/S almacenada en caché y FILE_FLAG_NO_BUFFERING. |
|
Las operaciones de escritura no pasarán por ninguna memoria caché intermedia, y pasarán directamente al disco.
Si no se especifica también FILE_FLAG_NO_BUFFERING , de modo que el almacenamiento en caché del sistema esté en vigor, los datos se escriben en la memoria caché del sistema, pero se vacían en el disco sin demora. Si también se especifica FILE_FLAG_NO_BUFFERING, para que el almacenamiento en caché del sistema no esté en vigor, los datos se vacían inmediatamente en el disco sin pasar por la memoria caché del sistema. El sistema operativo también solicita una escritura a través de la memoria caché del disco duro a medios persistentes. Sin embargo, no todo el hardware admite esta funcionalidad de escritura a través. |
El parámetro dwFlagsAndAttributes también puede especificar la información de calidad de servicio de seguridad. Para obtener más información, vea Niveles de suplantación. Cuando la aplicación que realiza la llamada especifica la marca SECURITY_SQOS_PRESENT como parte de dwFlagsAndAttributes, también puede contener uno o varios de los valores siguientes.
[in, optional] hTemplateFile
Identificador válido para un archivo de plantilla con el derecho de acceso GENERIC_READ . El archivo de plantilla proporciona atributos extendidos y atributos de archivo para el archivo que se va a crear. Este parámetro puede ser NULL.
Al abrir un archivo existente, CreateFileTransacted omite el archivo de plantilla.
Al abrir un nuevo archivo cifrado con EFS, el archivo hereda la DACL de su directorio primario.
[in] hTransaction
Identificador de la transacción. La función CreateTransaction devuelve este identificador.
[in, optional] pusMiniVersion
Miniversion que se va a abrir. Si la transacción especificada en hTransaction no es la transacción que modifica el archivo, este parámetro debe ser NULL. De lo contrario, este parámetro puede ser un identificador de miniversion devuelto por el código de control FSCTL_TXFS_CREATE_MINIVERSION o uno de los valores siguientes.
lpExtendedParameter
Este parámetro está reservado y debe ser NULL.
Valor devuelto
Si la función se realiza correctamente, el valor devuelto es un identificador abierto para el archivo, dispositivo, canalización con nombre o ranura de correo especificados.
Si se produce un error en la función, el valor devuelto es INVALID_HANDLE_VALUE. Para obtener información de error extendida, llame a GetLastError.
Comentarios
Cuando use el identificador devuelto por CreateFileTransacted, use la versión transaccionada de las funciones de E/S de archivo en lugar de las funciones de E/S de archivo estándar cuando corresponda. Para obtener más información, vea Consideraciones de programación para NTFS transaccional.
Al abrir un identificador de transacción en un directorio, ese identificador debe tener permisos FILE_WRITE_DATA (FILE_ADD_FILE) y FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY). Estos se incluyen en los permisos de FILE_GENERIC_WRITE . Debe abrir directorios con menos permisos si simplemente usa el identificador para crear archivos o subdirectorios; de lo contrario, se pueden producir infracciones de uso compartido.
No se puede abrir un archivo con FILE_EXECUTE nivel de acceso cuando ese archivo forma parte de otra transacción (es decir, otra aplicación la abrió llamando a CreateFileTransacted). Esto significa que Se produce un error en CreateFileTransacted si se especifica el nivel de acceso FILE_EXECUTE o FILE_ALL_ACCESS
Cuando una aplicación no transaccionada llama a CreateFileTransacted con MAXIMUM_ALLOWED especificado para lpSecurityAttributes, se abre un identificador con el mismo nivel de acceso cada vez. Cuando una aplicación con transacciones llama a CreateFileTransacted con MAXIMUM_ALLOWED especificado para lpSecurityAttributes, se abre un identificador con una cantidad de acceso diferente en función de si el archivo está bloqueado por una transacción. Por ejemplo, si la aplicación que realiza la llamada tiene FILE_EXECUTE nivel de acceso para un archivo, la aplicación solo obtiene este acceso si el archivo que está abierto no está bloqueado por una transacción o está bloqueado por una transacción y la aplicación ya es un lector de transacciones para ese archivo.
Consulte NTFS transaccional para obtener una descripción completa de las operaciones de transacción.
Use la función CloseHandle para cerrar un identificador de objeto devuelto por CreateFileTransacted cuando el identificador ya no sea necesario y antes de confirmar o revertir la transacción.
Algunos sistemas de archivos, como el sistema de archivos NTFS, admiten la compresión o el cifrado para archivos y directorios individuales. En volúmenes con formato para ese tipo de sistema de archivos, un nuevo archivo hereda los atributos de compresión y cifrado de su directorio.
No se puede usar CreateFileTransacted para controlar la compresión en un archivo o directorio. Para obtener más información, vea Compresión y descompresión de archivos y Cifrado de archivos.
Comportamiento de vínculo simbólico: si la llamada a esta función crea un nuevo archivo, no hay ningún cambio en el comportamiento.
Si se especifica FILE_FLAG_OPEN_REPARSE_POINT :
- Se abre un archivo existente y es un vínculo simbólico, el identificador devuelto será un identificador para el vínculo simbólico.
- Si se especifican TRUNCATE_EXISTING o FILE_FLAG_DELETE_ON_CLOSE , el archivo afectado es un vínculo simbólico.
- Se abre un archivo existente y es un vínculo simbólico, el identificador devuelto será un identificador para el destino.
- Si se especifica CREATE_ALWAYS, TRUNCATE_EXISTING o FILE_FLAG_DELETE_ON_CLOSE, el archivo afectado será el destino.
Como se indicó anteriormente, si el parámetro lpSecurityAttributes es NULL, cualquier proceso secundario puede crear el identificador devuelto por CreateFileTransacted . También se aplica la siguiente información sobre este parámetro:
- Si bInheritHandle no es FALSE, que es cualquier valor distinto de cero, se puede heredar el identificador. Por lo tanto, es fundamental que este miembro de estructura se inicialice correctamente en FALSE si no pretende que el identificador se pueda heredar.
- Las listas de control de acceso (ACL) del descriptor de seguridad predeterminado para un archivo o directorio se heredan de su directorio primario.
- El sistema de archivos de destino debe admitir la seguridad en los archivos y directorios para que el lpSecurityDescriptor tenga un efecto sobre ellos, que se puede determinar mediante GetVolumeInformation
| 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 |
Tenga en cuenta que SMB 3.0 no admite TxF.
Archivos
Si intenta crear un archivo en una unidad de disquete que no tiene un disquete o una unidad de CD-ROM que no tiene un CD, el sistema muestra un mensaje para que el usuario inserte un disco o un CD. Para evitar que el sistema muestre este mensaje, llame a la función SetErrorMode con SEM_FAILCRITICALERRORS.Para más información, consulte Crear y abrir archivos.
Si cambia el nombre o elimina un archivo y, a continuación, lo restaura poco después, el sistema busca en la memoria caché la información del archivo que se va a restaurar. La información almacenada en caché incluye su par de nombres cortos y largos y el tiempo de creación.
Si llama a CreateFileTransacted en un archivo que está pendiente de eliminación como resultado de una llamada anterior a DeleteFile, se produce un error en la función. El sistema operativo retrasa la eliminación de archivos hasta que se cierran todos los identificadores del archivo. GetLastError devuelve ERROR_ACCESS_DENIED.
El parámetro dwDesiredAccess puede ser cero, lo que permite a la aplicación consultar atributos de archivo sin tener acceso al archivo si la aplicación se ejecuta con una configuración de seguridad adecuada. Esto resulta útil para probar la existencia de un archivo sin abrirlo para el acceso de lectura o escritura, o para obtener otras estadísticas sobre el archivo o directorio. Vea Obtener y establecer información de archivo y GetFileInformationByHandle.
Cuando una aplicación crea un archivo a través de una red, es mejor usar GENERIC_READ GENERIC_WRITE | que usar solo GENERIC_WRITE. El código resultante es más rápido, ya que el redirector puede usar el administrador de caché y enviar menos SMB con más datos. Esta combinación también evita un problema por el que la escritura en un archivo a través de una red puede devolver ocasionalmente ERROR_ACCESS_DENIED.
Secuencias de archivos
En los sistemas de archivos NTFS, puede usar CreateFileTransacted para crear secuencias independientes dentro de un archivo.Para obtener más información, vea Secuencias de archivos.
Directorios
Una aplicación no puede crear un directorio mediante CreateFileTransacted, por lo que solo el valor de OPEN_EXISTING es válido para dwCreationDisposition para este caso de uso. Para crear un directorio, la aplicación debe llamar a CreateDirectoryTransacted, CreateDirectory o CreateDirectoryEx.Para abrir un directorio mediante CreateFileTransacted, especifique la marca FILE_FLAG_BACKUP_SEMANTICS como parte de dwFlagsAndAttributes. Las comprobaciones de seguridad adecuadas se siguen aplicando cuando se usa esta marca sin privilegios de SE_BACKUP_NAME y SE_RESTORE_NAME .
Al usar CreateFileTransacted para abrir un directorio durante la desfragmentación de un volumen del sistema de archivos FAT o FAT32, no especifique el derecho de acceso MAXIMUM_ALLOWED . Si se hace esto, se deniega el acceso al directorio. Especifique el derecho de acceso GENERIC_READ en su lugar.
Para obtener más información, consulte Acerca de la administración de directorios.
Nota
El encabezado winbase.h define CreateFileTransacted 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
| Requisito | Value |
|---|---|
| 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 |
Vea también
Compresión y descompresión de archivos
Funciones de administración de archivos
Seguridad y derechos de acceso de los archivos
Funciones
Temas de introducción
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de