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 todos los demás tipos de dispositivos que CreateFile2 pueden abrir. Para obtener más información, vea la sección Comentarios de la CreateFile2 página de referencia y Crear y abrir archivos.
Para obtener acceso más avanzado a los atributos de archivo, vea SetFileAttributes. Para obtener una lista completa de todos los atributos de archivo con sus valores y descripciones, vea Constantes de atributo de archivo.
| 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 . 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 normales. |
|
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 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. El almacenamiento remoto usa este atributo, 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 utiliza exclusivamente por un sistema operativo. |
|
El archivo se usa para el almacenamiento temporal.
Para obtener más información, vea la sección Comportamiento del almacenamiento en caché de este tema. |
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.
| Marca | Significado |
|---|---|
|
El archivo se está abriendo o creando 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 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 la sección Comentarios. |
|
El archivo se eliminará inmediatamente después de que se cierren todos sus identificadores, lo 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 FILE_SHARE_DELETE recurso compartido. 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. |
|
Un mapa de dispositivos es una asignación entre los nombres de dispositivo y los dispositivos dos del sistema y se usa al resolver los nombres de DOS. Existen asignaciones 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 del dispositivo del usuario del proceso. |
|
El archivo o dispositivo se abre sin almacenamiento en caché del sistema para las 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 FILE_FLAG_NO_BUFFERING , para obtener más información, consulte File Buffering. |
|
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 es para que la usen los sistemas de almacenamiento remoto. |
|
No se producirá el procesamiento normal del 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 está abriendo y se solicita un bloqueo oportunista (oplock) en el archivo como una única 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 se devuelve correctamente, la primera operación que debe realizar en el identificador de archivo es solicitar un interbloqueo llamando a la función DeviceIOControl y, a continuación, pasar FSCTL_REQUEST_OPLOCK o una de las otras operaciones de bloqueo oportunista. Si realiza otras operaciones del sistema de archivos con el identificador de archivo antes de solicitar un interbloqueo, podría producirse un interbloqueo. Nota 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 al usar 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 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. |
|
El acceso está pensado para ser aleatorio. El sistema puede considerar que esto es una sugerencia para optimizar el almacenamiento en caché del archivo.
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, vea la sección Comportamiento del almacenamiento en caché de este tema. |
|
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. |
|
El acceso está pensado para ser secuencial de principio a fin. El sistema puede considerar que esto es una sugerencia para optimizar el almacenamiento en caché del archivo.
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, vea la sección Comportamiento del almacenamiento en caché de este tema. |
|
Las operaciones de escritura no pasarán por ninguna memoria caché intermedia, y pasarán directamente al disco.
Para obtener más información, consulte la sección Comportamiento del almacenamiento en caché de este tema. |
dwSecurityQosFlags
El parámetro dwSecurityQosFlags especifica información de SQOS. Para obtener más información, vea 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.
CreateFile2 omite el miembro lpSecurityDescriptor al abrir un archivo o dispositivo existente, pero sigue usando el miembro bInheritHandle .
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 extendidos y atributos de archivo para el archivo que se va a crear.
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 Cifrado de archivos.
Comentarios
Para compilar una aplicación que usa la estructura CREATEFILE2_EXTENDED_PARAMETERS , defina la macro _WIN32_WINNT como 0x0602 o posterior. Para obtener más información, vea Usar los encabezados de Windows.
Comportamiento de almacenamiento en caché
Se usan varios de los valores posibles para el miembro dwFileFlags para controlar o afectar a cómo el sistema almacena en caché los datos asociados al identificador. Son las siguientes:
- 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, la combinación de FILE_FLAG_RANDOM_ACCESS con FILE_FLAG_SEQUENTIAL_SCAN es la auto-derrota.
Especificar la marca FILE_FLAG_SEQUENTIAL_SCAN 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 en ocasiones omiten hacia delante en intervalos pequeños 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 la 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 memoria caché del sistema, pero se vacían en el disco sin demora.
Si se especifican FILE_FLAG_WRITE_THROUGH y 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 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 de 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, vea File Buffering.
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, que resulta del procesamiento de 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 de rendimiento innecesarias. El uso de estas marcas conjuntamente evita esas penalizaciones. Para obtener información general sobre el almacenamiento en caché de archivos y metadatos, vea 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 todavía 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 FlushFileBuffers .
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 la escritura de 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 lo tanto, puede ser de preocupación para determinadas aplicaciones.
Identificadores de E/S sincrónicos y asincrónicos
CreateFile2 proporciona la creación de 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 completan, 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 miembro dwFileFlags de la estructura de CREATEFILE2_EXTENDED_PARAMETERS pasada en el parámetro pCreateExParams . Hay varias complejidades y posibles dificultades al usar E/S asincrónica; para obtener más información, vea E/S sincrónica y asincrónica.
Requisitos
| Cliente mínimo compatible | Windows 8 [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2012 [aplicaciones de escritorio | Aplicaciones para UWP] |
| Encabezado | fileapi.h (incluye Windows.h) |