estructura CREATEFILE2_EXTENDED_PARAMETERS (fileapi.h)
Contiene parámetros extendidos opcionales para CreateFile2.
Sintaxis
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
Miembros
dwSize
Contiene el tamaño de esta estructura, sizeof(CREATEFILE2_EXTENDED_PARAMETERS).
dwFileAttributes
Los atributos y marcas de archivo o dispositivo, FILE_ATTRIBUTE_NORMAL siendo el valor predeterminado más común para los archivos.
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.
Nota
Cuando createFile2 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.
Algunos de los siguientes atributos y marcas de archivo solo se pueden aplicar a los archivos y no necesariamente a todos los demás tipos de dispositivos que CreateFile2 pueden abrirse. Para obtener más información, vea la sección comentarios de de la página de referencia de CreateFile2 y crear y abrir archivos.
Para obtener acceso más avanzado a los atributos de archivo, consulte SetFileAttributes. Para obtener una lista completa de todos los atributos de archivo con sus valores y descripciones, vea constantes de atributos de archivo.
| 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. Esta marca no se admite en las ediciones Home, Home Premium, Starter o ARM de Windows. Esta marca no se admite cuando se llama desde una aplicación de la Tienda Windows. |
|
El archivo está oculto. No lo incluya en una lista de directorios normal. |
|
Un archivo o directorio configurado con integridad. Para un archivo, todos los flujos de datos del archivo tienen integridad. Para un directorio, la integridad es el valor predeterminado para los archivos y subdirectorios recién creados, a menos que el autor de la llamada especifique lo contrario.
Esta marca solo se admite en el sistema de archivos ReFS. |
|
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.
Para obtener más información, consulte la sección comportamiento de almacenamiento en caché de |
dwFileFlags
Este parámetro puede contener combinaciones de marcas (FILE_FLAG_*) para controlar el comportamiento del almacenamiento en caché de archivos o dispositivos, los modos de acceso y otras marcas de propósito especial.
| 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, vea la sección Comentarios. |
|
El archivo se va a eliminar inmediatamente después de que se cierren todos sus identificadores, que incluye el identificador especificado y cualquier otro identificador abierto o duplicado.
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. |
|
Un mapa de dispositivos es una asignación entre los nombres de dispositivo DOS y los dispositivos del sistema, y se usa al resolver los nombres de DOS. Existen mapas de dispositivos independientes para cada usuario del sistema y los usuarios pueden administrar sus propios mapas de dispositivos. Normalmente durante la suplantación, se usaría el mapa de dispositivos del usuario suplantado. Sin embargo, cuando se establece esta marca, se usa en su lugar el mapa de dispositivos del usuario del proceso. |
|
El archivo o dispositivo se está abriendo sin almacenamiento en caché del sistema para lecturas y escrituras de datos. Esta marca no afecta al almacenamiento en caché del disco duro ni a los archivos asignados a memoria.
Hay requisitos estrictos para trabajar correctamente con archivos abiertos con CreateFile2 mediante la marca de FILE_FLAG_NO_BUFFERING, para obtener más información, consulte de almacenamiento en búfer de archivos . |
|
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; CreateFile2 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. Para obtener más información, vea la sección Comentarios. |
|
El archivo se abre y se solicita un bloqueo oportunista (oplock) en el archivo como una sola operación atómica. El sistema de archivos comprueba si hay interbloqueos antes de realizar la operación de creación y producirá un error en la creación con un último código de error de ERROR_CANNOT_BREAK_OPLOCK si el resultado sería interrumpir un interbloqueo existente.
Si usa esta marca y la llamada a la función CreateFile2 de
Note Puede llamar de forma segura a la función CloseHandle en el identificador de archivo sin solicitar primero un interbloqueo.
|
|
El archivo o dispositivo se está abriendo o creando para E/S asincrónica.
Cuando se completen las operaciones de E/S posteriores en este identificador, el evento especificado en la estructura SUPERPUESTA se establecerá en el estado señalado. Si se especifica esta marca, el archivo se puede usar para operaciones simultáneas de lectura y escritura. 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. Para obtener información sobre las consideraciones sobre el uso de un identificador de archivo creado con esta marca, consulte la sección identificadores de E/S sincrónicos y asincrónicos de este tema. |
|
El acceso se producirá 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. |
|
El acceso está pensado para ser aleatorio. El sistema puede usarlo como sugerencia para optimizar el almacenamiento en caché de archivos.
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. Para obtener más información, consulte la sección comportamiento de almacenamiento en caché de |
|
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. |
|
El acceso está pensado para ser secuencial desde el principio hasta el final. El sistema puede usarlo como sugerencia para optimizar el almacenamiento en caché de archivos.
Esta marca no se debe usar si se usará lectura subyacente (es decir, exámenes hacia atrás). 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. Para obtener más información, consulte la sección comportamiento de almacenamiento en caché de |
|
Las operaciones de escritura no pasarán a través de ninguna caché intermedia, pasarán directamente al disco.
Para obtener más información, consulte la sección comportamiento de almacenamiento en caché de |
dwSecurityQosFlags
El parámetro dwSecurityQosFlags especifica información de SQOS. Para obtener más información, consulte Niveles de suplantación.
lpSecurityAttributes
Puntero a una estructura de SECURITY_ATTRIBUTES que contiene dos miembros de datos independientes pero relacionados: un descriptor de seguridad opcional y un valor booleano que determina si los procesos secundarios pueden heredar el identificador devuelto.
Este parámetro puede ser null.
Si este parámetro es null, el identificador devuelto por CreateFile2 no puede ser heredado por ningún proceso secundario que la aplicación pueda crear y el archivo o dispositivo asociado al identificador devuelto obtiene un descriptor de seguridad predeterminado.
El miembro lpSecurityDescriptor de la estructura especifica un SECURITY_DESCRIPTOR para un archivo o dispositivo. Si este miembro es NULL, al archivo o dispositivo asociado al identificador devuelto se le asigna un descriptor de seguridad predeterminado.
El miembro bInheritHandle de la estructura especifica si se puede heredar el identificador devuelto.
Para obtener más información, vea la sección Comentarios del tema CreateFile2.
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, CreateFile2 omite este parámetro.
Al abrir un nuevo archivo cifrado, el archivo hereda la lista de control de acceso discrecional de su directorio primario. Para obtener más información, consulte de cifrado de archivos .
Observaciones
Para compilar una aplicación que use la estructura CREATEFILE2_EXTENDED_PARAMETERS, defina la macro _WIN32_WINNT como 0x0602 o posterior. Para obtener más información, vea Using the Windows Headers.
Comportamiento de almacenamiento en caché
Varios de los valores posibles para el dwFileFlags miembro se usan para controlar o afectar a cómo el sistema almacena en caché los datos asociados con el identificador. Son:
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Si no se especifica ninguna de estas marcas, el sistema usa un esquema de almacenamiento en caché de uso general predeterminado. De lo contrario, el almacenamiento en caché del sistema se comporta como se especifica para cada marca.
Algunas de estas marcas no deben combinarse. Por ejemplo, combinar FILE_FLAG_RANDOM_ACCESS con FILE_FLAG_SEQUENTIAL_SCAN es la auto-derrota.
La especificación de la marca FILE_FLAG_SEQUENTIAL_SCAN 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 hacia delante en pequeños intervalos de bytes. Si una aplicación mueve el puntero de archivo para el acceso aleatorio, lo más probable es que no se produzca un rendimiento óptimo del almacenamiento en caché. Sin embargo, todavía se garantiza una operación correcta.
Las marcas FILE_FLAG_WRITE_THROUGH y FILE_FLAG_NO_BUFFERING son independientes y se pueden combinar.
Si se usa FILE_FLAG_WRITE_THROUGH pero 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 caché del sistema, pero se vacían en el disco sin demora.
Si se especifican FILE_FLAG_WRITE_THROUGH y 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 de Windows. El sistema operativo también solicita una escritura a través de la caché de hardware local del disco duro a medios persistentes.
Nota
No todo el hardware del disco duro admite esta funcionalidad de escritura a través.
El uso adecuado de la marca FILE_FLAG_NO_BUFFERING requiere consideraciones especiales sobre la aplicación. Para obtener más información, consulte de almacenamiento en búfer de archivos.
Una solicitud de escritura a través de FILE_FLAG_WRITE_THROUGH también hace que NTFS vacíe los cambios de metadatos, como una actualización de marca de tiempo o una operación de cambio de nombre, lo que resulta de procesar la solicitud. Por este motivo, la marca FILE_FLAG_WRITE_THROUGH se usa a menudo con la marca FILE_FLAG_NO_BUFFERING como reemplazo de llamar a la función FlushFileBuffers después de cada escritura, lo que puede provocar penalizaciones innecesarias de rendimiento. El uso de estas marcas conjuntamente evita esas penalizaciones. Para obtener información general sobre el almacenamiento en caché de archivos y metadatos, consulte almacenamiento en caché de archivos.
Cuando FILE_FLAG_NO_BUFFERING se combina con FILE_FLAG_OVERLAPPED, las marcas proporcionan 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 almacenen en caché (por ejemplo, al crear un archivo vacío). Para asegurarse de que los metadatos se vacían en el disco, use la función
Especificar el atributo FILE_ATTRIBUTE_TEMPORARY hace que los sistemas de archivos eviten 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. Aunque no controla directamente el almacenamiento en caché de datos de la misma manera que las marcas mencionadas anteriormente, el atributo FILE_ATTRIBUTE_TEMPORARY indica al sistema que contenga tanto como sea posible en la memoria caché del sistema sin escribir y, por tanto, puede ser de preocupación para determinadas aplicaciones.
Identificadores de E/S sincrónicos y asincrónicos
createFile2 proporciona para crear un identificador de archivo o dispositivo que sea sincrónico o asincrónico. Un identificador sincrónico se comporta de forma que las llamadas de función de E/S que usan ese identificador se bloquean hasta que se completen, mientras que un identificador de archivo asincrónico permite que el sistema devuelva inmediatamente de las llamadas de función de E/S, tanto si han completado la operación de E/S como si no. Como se indicó anteriormente, este comportamiento sincrónico frente a asincrónico se determina especificando FILE_FLAG_OVERLAPPED dentro del dwFileFlags miembro de la estructura de CREATEFILE2_EXTENDED_PARAMETERS pasada en el parámetro pCreateExParams. Hay varias complejidades y posibles problemas al usar E/S asincrónica; para obtener más información, vea de E/S sincrónica y asincrónica.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows 8 [aplicaciones de escritorio | Aplicaciones para UWP] |
| servidor mínimo admitido | Windows Server 2012 [aplicaciones de escritorio | Aplicaciones para UWP] |
| encabezado de |
fileapi.h (incluya Windows.h) |