Función CreateFile2 (fileapi.h)
Crea o abre un archivo o dispositivo de E/S. Los dispositivos de E/S más usados son los siguientes: archivo, secuencia de archivos, directorio, disco físico, volumen, búfer de consola, unidad de cinta, recurso de comunicaciones, mailslot y canalización. La función devuelve un identificador que se puede usar para tener acceso al archivo o dispositivo para varios tipos de E/S según el archivo o dispositivo y las marcas y atributos especificados.
Cuando se llama desde una aplicación de la Tienda Windows, se simplifica createFile2. Solo puede abrir archivos o directorios dentro de los directorios ApplicationData.LocalFolder o Package.InstalledLocation. No se pueden abrir canalizaciones con nombre ni gráficos de correo ni crear archivos cifrados (FILE_ATTRIBUTE_ENCRYPTED).
Sintaxis
HANDLE CreateFile2(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in] DWORD dwCreationDisposition,
[in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);
Parámetros
[in] lpFileName
Nombre del archivo o dispositivo que se va a crear o abrir.
Para obtener información sobre los nombres de dispositivo especiales, consulte Definición de un nombre de dispositivo MS-DOS.
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 solicitado al archivo o dispositivo, que se puede resumir como lectura, escritura, ambos o ninguno ninguno).
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, derechos de acceso y seguridad de archivos, constantes de derechos de acceso a archivosy ACCESS_MASK.
Si este parámetro es cero, la aplicación puede consultar determinados metadatos, como los atributos de archivo, directorio o dispositivo sin tener acceso a ese archivo o dispositivo, incluso si se hubiera denegado el acceso GENERIC_READ.
No se puede solicitar un modo de acceso que entra en conflicto con el modo de uso compartido especificado por el parámetro dwShareMode en una solicitud abierta que ya tiene un identificador abierto.
Para obtener más información, vea la sección Comentarios de este tema y crear y abrir archivos.
[in] dwShareMode
Modo de uso compartido solicitado del archivo o dispositivo, que se puede leer, escribir, eliminar, todos o ninguno (consulte la tabla siguiente). Las solicitudes de acceso a atributos o atributos extendidos no se ven afectadas por esta marca.
Si este parámetro es cero y CreateFile2 se realiza correctamente, el archivo o el dispositivo no se pueden compartir y no se pueden volver a abrir hasta que se cierre el identificador del archivo o dispositivo. 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 existente que tenga un identificador abierto.
Para habilitar un proceso para compartir un archivo o dispositivo mientras otro proceso tiene abierto el archivo o dispositivo, use una combinación compatible de uno o varios de los valores siguientes. Para obtener más información sobre las combinaciones válidas de este parámetro con el parámetro dwDesiredAccess, vea Crear y abrir archivos.
[in] dwCreationDisposition
Acción que se va a realizar en un archivo o dispositivo que existe o no existe.
En el caso de los dispositivos que no sean archivos, este parámetro normalmente se establece en OPEN_EXISTING.
Para obtener más información, vea la sección Comentarios.
Este parámetro debe ser uno de los siguientes valores, que no se pueden combinar:
[in, optional] pCreateExParams
Puntero a una estructura de CREATEFILE2_EXTENDED_PARAMETERS opcional.
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
Para compilar una aplicación que use la función CreateFile2, defina la macro _WIN32_WINNT como 0x0602 o posterior. Para obtener más información, vea Using the Windows Headers.
CreateFile2 admite la interacción de archivos y la mayoría de otros tipos de dispositivos y mecanismos de E/S disponibles para los desarrolladores de Windows. En esta sección se intentan tratar los diversos problemas que pueden experimentar los desarrolladores al usar createFile2 en contextos diferentes y con diferentes tipos de E/S. El texto intenta usar la palabra archivo solo cuando se hace referencia específicamente a los datos almacenados en un archivo real en un sistema de archivos. Sin embargo, algunos usos de archivo pueden referirse más generalmente a un objeto de E/S que admita mecanismos similares a archivos. Este uso liberal del término archivo es especialmente frecuente en nombres constantes y nombres de parámetros debido a las razones históricas mencionadas anteriormente.
Cuando una aplicación termine de usar el identificador de objeto devuelto por CreateFile2, use la función CloseHandle para cerrar el identificador. Esto no solo libera los recursos del sistema, pero puede tener una influencia más amplia en cosas como compartir el archivo o el dispositivo y confirmar datos en el disco. Los detalles se indican en este tema según corresponda.
Algunos sistemas de archivos, como el sistema de archivos NTFS, admiten compresión o cifrado para archivos y directorios individuales. En los volúmenes que tienen un sistema de archivos montado con esta compatibilidad, un nuevo archivo hereda los atributos de compresión y cifrado de su directorio.
No se puede usar CreateFile2 para controlar la compresión, descompresión o descifrado en un archivo o directorio. Para obtener más información, vea crear y abrir archivos, compresión y descompresión de archivosy cifrado de archivos .
Si el lpSecurityAttributes miembro de la estructura de CREATEFILE2_EXTENDED_PARAMETERS pasado en el parámetro pCreateExParams es NULL, el identificador devuelto por createFile2 no se puede heredar por ningún proceso secundario que cree la aplicación. También se aplica la siguiente información relacionada con este miembro:
- Si la variable miembro
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 el miembro lpSecurityDescriptor para que tenga un efecto en ellos, que se puede determinar mediante GetVolumeInformation.
| Tecnología | Soportado |
|---|---|
| Protocolo bloque de mensajes del servidor (SMB) 3.0 | Sí |
| 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) | Sí |
| Sistema de archivos resistente (ReFS) | Sí |
comportamiento de vínculo simbólico de
Si la llamada a esta función crea un archivo, no hay ningún cambio en el comportamiento. Además, tenga en cuenta la siguiente información relacionada con la marca FILE_FLAG_OPEN_REPARSE_POINT para el dwFileFlags miembro de la estructura de CREATEFILE2_EXTENDED_PARAMETERS pasada en el parámetro pCreateExParams:-
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 no 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 para el destino.
- Si se especifican CREATE_ALWAYS, TRUNCATE_EXISTINGo FILE_FLAG_DELETE_ON_CLOSE, el archivo afectado es el destino.
archivos de
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 CreateFile2 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 para dwDesiredAccess 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.
Para obtener más información, vea Crear y abrir archivos.
flujos de archivos de
En los sistemas de archivos NTFS, puede usar CreateFile2 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 CreateFile2, 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 CreateDirectory o CreateDirectoryEx.Para abrir un directorio mediante CreateFile2, especifique la marca FILE_FLAG_BACKUP_SEMANTICS como parte de dwFileFlags miembro de la estructura CREATEFILE2_EXTENDED_PARAMETERS pasada en el parámetro pCreateExParams. 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 CreateFile2 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.
discos físicos y volúmenes
El acceso directo al disco o a un volumen está restringido.Puede usar la función createFile2
Se deben cumplir los siguientes requisitos para que dicha llamada se realice correctamente:
- El autor de la llamada debe tener privilegios administrativos. Para obtener más información, vea En ejecución con privilegios especiales.
- El parámetro dwCreationDisposition debe tener la marca OPEN_EXISTING.
- Al abrir un volumen o un disquete, el parámetro dwShareMode debe tener la marca FILE_SHARE_WRITE.
| Cuerda | Significado |
|---|---|
| "\\.\PhysicalDrive0" | Abre la primera unidad física. |
| "\\.\PhysicalDrive2" | Abre la tercera unidad física. |
Para obtener el identificador de unidad física de un volumen, abra un identificador en el volumen y llame a la función DeviceIoControl
Para obtener un ejemplo de apertura de una unidad física, consulte Llamada a DeviceIoControl.
Al abrir un volumen o una unidad multimedia extraíble (por ejemplo, una unidad de disco de disquete o una unidad de memoria flash), el lpFileName cadena debe ser la siguiente forma: "\\.\X:". No use una barra diagonal inversa final (\), que indica el directorio raíz de una unidad. En la tabla siguiente se muestran algunos ejemplos de cadenas de unidad.
| Cuerda | Significado |
|---|---|
| "\\.\A:" | Abre la unidad de disco A. |
| "\\.\C:" | Abre el volumen C: . |
| "\\.\C:\" | Abre el sistema de archivos del volumen C: . |
También puede abrir un volumen haciendo referencia a su nombre de volumen. Para obtener más información, vea Asignar nombre a un volumen.
Un volumen contiene uno o varios sistemas de archivos montados. Los identificadores de volumen se pueden abrir como no almacenados en caché a discreción del sistema de archivos concreto, incluso cuando la opción no almacenada en caché no se especifica en CreateFile2. Debe suponer que todos los sistemas de archivos de Microsoft abren los identificadores de volumen como no almacenados en caché. Las restricciones de E/S no almacenadas en caché para los archivos también se aplican a los volúmenes.
Un sistema de archivos puede requerir o no alineación del búfer aunque los datos no se almacenen en caché. Sin embargo, si se especifica la opción no almacenada en caché al abrir un volumen, se aplica la alineación del búfer independientemente del sistema de archivos del volumen. Se recomienda en todos los sistemas de archivos que abra los identificadores de volumen como no almacenados en caché y siga las restricciones de E/S no almacenadas en caché.
dispositivo de Changer
Los códigos de control IOCTL_CHANGER_* para DeviceIoControl aceptan un identificador para un dispositivo de modificador. Para abrir un dispositivo de modificador, use un nombre de archivo con el siguiente formato: "\\.\Changerx" donde x es un número que indica qué dispositivo se va a abrir, empezando por cero. Para abrir el dispositivo de modificador cero en una aplicación escrita en C o C++, use el siguiente nombre de archivo: "\\\\.\\Changer0".unidades de cinta de
Puede abrir unidades de cinta con un nombre de archivo de la siguiente forma: "\\.\TAPEx" donde x es un número que indica qué unidad se va a abrir, empezando por la unidad de cinta cero. Para abrir la unidad de cinta cero en una aplicación escrita en C o C++, use el siguiente nombre de archivo: "\\\\.\\TAPE0".Para obtener más información, vea backup.
Recursos de comunicaciones de
La función CreateFile2 puede crear un identificador para un recurso de comunicaciones, como el puerto serie COM1. Para los recursos de comunicaciones, el parámetro dwCreationDisposition debe ser OPEN_EXISTING, el parámetro dwShareMode debe ser cero (acceso exclusivo) y el parámetro hTemplateFile debe ser NULL. Se puede especificar el acceso de lectura, escritura o lectura y escritura, y el identificador se puede abrir para E/S superpuesta.Para especificar un número de puerto COM mayor que 9, use la sintaxis siguiente: "\.\COM10". Esta sintaxis funciona para todos los números de puerto y hardware que permite especificar números de puerto COM.
Para obtener más información sobre las comunicaciones, vea Communications.
Consolas de
La función CreateFile2 puede crear un identificador para la entrada de la consola (CONIN$). Si el proceso tiene un identificador abierto para él como resultado de la herencia o duplicación, también puede crear un identificador para el búfer de pantalla activo (CONOUT$). El proceso de llamada debe asociarse a una consola heredada o a una asignada por la función AllocConsole. En el caso de los identificadores de consola, establezca los parámetros CreateFile2 como se indica a continuación.| Parámetros | Valor |
|---|---|
| lpFileName |
Use el valor CONIN$ para especificar la entrada de la consola.
Use el valor CONOUT$ para especificar la salida de la consola. CONIN$ obtiene un identificador del búfer de entrada de la consola, incluso si la función SetStdHandle redirige el identificador de entrada estándar. Para obtener el identificador de entrada estándar, use la función getStdHandle. CONOUT$ obtiene un identificador del búfer de pantalla activo, incluso si setStdHandle redirige el identificador de salida estándar. Para obtener el identificador de salida estándar, use GetStdHandle. |
| dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE es preferible, pero cualquiera de ellos puede limitar el acceso.
|
| dwShareMode |
Al abrir CONIN$, especifique FILE_SHARE_READ. Al abrir CONOUT$, especifique FILE_SHARE_WRITE.
Si el proceso de llamada hereda la consola o si un proceso secundario debe poder acceder a la consola, este parámetro debe ser |
| dwCreationDisposition |
Debe especificar |
Establezca los miembros de la estructura de CREATEFILE2_EXTENDED_PARAMETERS pasados en el parámetro pCreateExParams como se indica a continuación.
| Miembros | Valor |
|---|---|
| lpSecurityAttributes |
Si desea que se herede la consola, el miembro |
|
dwFileAttributes
dwFileFlags dwSecurityQosFlags hTemplateFile |
Ignorado. |
En la tabla siguiente se muestran varios valores de dwDesiredAccess y lpFileName.
Mailslots
Si CreateFile2 abre el final del cliente de un mailslot, la función devuelve INVALID_HANDLE_VALUE si el cliente mailslot intenta abrir un mailslot local antes de que el servidor mailslot lo haya creado con la función CreateMailSlot.Para obtener más información, vea Mailslots.
canalizaciones de
Si createFile2 abre el final del cliente de una canalización con nombre, la función usa cualquier instancia de la canalización con nombre que esté en estado de escucha. El proceso de apertura puede duplicar el identificador tantas veces como sea necesario, pero después de abrirlo, otro cliente no puede abrir la instancia de canalización con nombre. El acceso especificado cuando se abre una canalización debe ser compatible con el acceso especificado en el parámetro dwOpenMode de la función CreateNamedPipe.Si la función CreateNamedPipe no se llamó correctamente en el servidor antes de esta operación, no existirá una canalización y CreateFile2 producirá un error con ERROR_FILE_NOT_FOUND.
Si hay al menos una instancia de canalización activa, pero no hay canalizaciones de agente de escucha disponibles en el servidor, lo que significa que todas las instancias de canalización están conectadas actualmente, CreateFile2 produce un error con ERROR_PIPE_BUSY.
Para obtener más información, consulte Canalizaciones.
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] |
| de la plataforma de destino de |
Windows |
| encabezado de |
fileapi.h (incluya Windows.h) |
| biblioteca de |
Kernel32.lib |
| DLL de |
Kernel32.dll |
Consulte también
Acerca de la administración de directorios
Acerca de la administración de volúmenes
de copia de seguridad de
de comunicaciones de
crear, eliminar y mantener archivos
de entrada y salida (IOCTL) del dispositivo
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
de puertos de finalización de E/S de
obtener y establecer información de archivo
Temas de información general de
canalizaciones de