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 a través de técnicas más sencillas y disponibles con mayor facilidad. Además, es posible que TxF no esté disponible en versiones futuras de Microsoft Windows. Para obtener 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 transcretada 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 se limita 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 Archivos de nomenclatura, rutas de acceso y espacios de nombres.
Propina
A partir de Windows 10, versión 1607, puedes optar por quitar la limitación del MAX_PATH sin tener que prepending "\\?\". Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Archivos de nomenclatura, 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, consulte 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_WRITEo ambos (GENERIC_READ | GENERIC_WRITE). Para obtener más información, vea de derechos de acceso genéricos y derechos de acceso y seguridad de archivos de .
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 de este tema.
No se puede solicitar un modo de acceso que entra en conflicto con el modo de uso compartido especificado en una solicitud abierta que tenga un identificador abierto. Para obtener más información, vea Crear y abrir archivos.
[in] dwShareMode
Modo de uso compartido de un objeto, que se puede leer, escribir, ambos, eliminar, todos o ninguno (consulte la tabla siguiente).
Si este parámetro es cero y CreateFileTransacted se realiza 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 de este tema.
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 obtener más información, vea 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
El miembro bInheritHandle de la estructura especifica si se puede heredar el identificador devuelto.
El
Si miembro lpSecurityDescriptor es NULL, al objeto asociado con el identificador devuelto se le asigna un descriptor de seguridad predeterminado.
Para obtener más información, vea la sección Comentarios de este tema.
[in] dwCreationDisposition
Acción que se va a realizar en los archivos que existen y que no existen.
Para obtener más información, vea la sección Comentarios de este tema.
Este parámetro debe ser uno de los siguientes valores, 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 seguridad del servicio (SQOS) especificando la marca SECURITY_SQOS_PRESENT. La información adicional sobre marcas relacionadas con SQOS se presenta en la tabla siguiendo los atributos y las tablas de marcas.
Cuando CreateFileTransacted abre un archivo existente, normalmente 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 de copia de seguridad o eliminación. |
|
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, consulte 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 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 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 por completo escribir los datos. De lo contrario, los datos se escriben después de cerrar el identificador. |
| Bandera | Significado |
|---|---|
|
El archivo se abre o crea para una operación de copia de seguridad o restauración. El sistema garantiza que el proceso de llamada invalida las comprobaciones de seguridad de archivos cuando el proceso tiene privilegios 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 un identificador de archivo. Para obtener más información, consulte identificadores de directorio. |
|
El archivo se eliminará inmediatamente después de que se cierre el último identificador del escritor de transacciones en el archivo, siempre que la transacción siga activa. Si se ha marcado un archivo 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 se hayan abierto con el modo de recurso compartido de FILE_SHARE_DELETE. Se produce un error en las solicitudes abiertas posteriores del archivo, a menos que se especifique el modo de recurso compartido de FILE_SHARE_DELETE. |
|
El archivo se abre 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 depende de 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 almacenen en caché. Para vaciar los metadatos en el disco, use la función 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 |
|
Los datos del archivo se solicitan, pero deben seguir estando ubicados en el almacenamiento remoto. No debe transportarse de vuelta al almacenamiento local. Esta marca la usan los sistemas de almacenamiento remoto. |
|
No se producirá el procesamiento normal 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 crea para E/S asincrónica. Una vez completada la operación, el evento especificado en la estructura 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 superpuesta estructura 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 va a acceder al archivo según las reglas POSIX. Esto incluye permitir varios archivos con nombres, que solo difieren en el caso, para 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 acceder al archivo de forma aleatoria. El sistema puede usarlo como sugerencia para optimizar el almacenamiento en caché de archivos. |
|
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 redirección USB remoteFX).
Esta marca no tiene ningún efecto para los autores de llamadas 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 usarlo como sugerencia para optimizar el almacenamiento en caché de archivos. 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 una operación correcta.
Especificar esta marca puede aumentar el rendimiento de las aplicaciones que leen archivos grandes mediante 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 pequeños intervalos 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 a través de ninguna caché intermedia, pasarán directamente al disco.
Si no se especifica FILE_FLAG_NO_BUFFERING también, de modo que el almacenamiento en caché del sistema esté en vigor, los datos se escriben en la caché del sistema, pero se vacían en el disco sin demora. Si también se especifica FILE_FLAG_NO_BUFFERING, de modo que el almacenamiento en caché del sistema no esté en vigor, los datos se vacían inmediatamente en el disco sin pasar por la 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, consulte 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 de archivo y atributos extendidos para el archivo que se está creando. 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. El 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 está modificando 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 ejecuta 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.
Observaciones
Cuando se usa 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 laNTFS 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 FILE_GENERIC_WRITE permisos. Debe abrir directorios con menos permisos si solo 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 CreateFileTransacted produce un error si se especifica el nivel de acceso FILE_EXECUTE o FILE_ALL_ACCESS.
Cuando una aplicación no transaccionada llama CreateFileTransacted con MAXIMUM_ALLOWED especificado para lpSecurityAttributes, se abre un identificador con el mismo nivel de acceso cada vez. Cuando una aplicación transaccionada 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 se abre 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 compresión o cifrado para archivos y directorios individuales. En los 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 puede usar CreateFileTransacted para controlar la compresión en un archivo o directorio. Para obtener más información, vea de compresión y descompresión de archivos, y cifrado de archivos.
Comportamiento simbólico del vínculo: 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:
- Si se abre un archivo existente y es un vínculo simbólico, el identificador devuelto es un identificador del vínculo simbólico.
- Si se especifican TRUNCATE_EXISTING o FILE_FLAG_DELETE_ON_CLOSE, el archivo afectado es un vínculo simbólico.
- Si se abre un archivo existente y es un vínculo simbólico, el identificador devuelto es un identificador para el destino.
- Si se especifican CREATE_ALWAYS, TRUNCATE_EXISTINGo FILE_FLAG_DELETE_ON_CLOSE, el archivo afectado es el destino.
Como se indicó anteriormente, si el parámetro lpSecurityAttributes es NULL, el identificador devuelto por createFileTransacted no puede ser heredado por ningún proceso secundario que pueda crear la aplicación. 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 para 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 archivos y directorios para que el lpSecurityDescriptor de
tenga un efecto en ellos, que se puede determinar mediante GetVolumeInformation
| Tecnología | Soportado |
|---|---|
| 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 (ReFS) | No |
Tenga en cuenta que SMB 3.0 no admite TxF.
archivos de
Si intenta crear un archivo en una unidad de disquete que no tiene un disco de 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ónPara obtener más información, vea 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 corto/largo 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. Consulte 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.
flujos de archivos de
En los sistemas de archivos NTFS, puede usar CreateFileTransacted para crear secuencias independientes dentro de un archivo.Para obtener más información, consulte secuencias de archivos.
directorios de
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 de 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 GENERIC_READ derecho de acceso 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 Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows Vista [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows Server 2008 [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
winbase.h (incluya Windows.h) |
| biblioteca de |
Kernel32.lib |
| DLL de |
Kernel32.dll |
Consulte también
de compresión y descompresión de archivos
de cifrado de archivos de
funciones de administración de archivos
derechos de acceso y seguridad de archivos
flujos de archivos de
funciones de
Temas de información general de
consideraciones de programación para la NTFS transaccional