Función CreateFileFromAppW (fileapifromapp.h)

Artículo
03/09/2023

Crea o abre un archivo o un dispositivo de E/S. El comportamiento de esta función es idéntico a CreateFile, salvo que esta función se adhiere al modelo de seguridad de aplicaciones de Plataforma universal de Windows.

Sintaxis

WINSTORAGEAPI HANDLE CreateFileFromAppW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
) noexcept;

Parámetros

lpFileName

Nombre del archivo o dispositivo que se va a crear o abrir. Puede usar barras diagonales (/) o barras diagonales inversas (\) en este nombre.

En la versión ANSI de esta función, el nombre se limita a MAX_PATH caracteres. Para ampliar este límite a 32 767 caracteres anchos, llame a la versión Unicode de la función y anteponga "\\?\" a la ruta de acceso. Para obtener más información, vea Nomenclatura de archivos, rutas de acceso y espacios de nombres.

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, vea Secuencias de archivos.

Para la versión unicode de esta función (CreateFileFromAppW), 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.

dwDesiredAccess

El acceso solicitado al archivo o dispositivo, 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, Seguridad de archivos y Derechos de acceso, Constantes de derechos de acceso de archivos y 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 GENERIC_READ acceso.

No se puede solicitar un modo de acceso que entre en conflicto con el modo de uso compartido especificado por el parámetro dwShareMode en una solicitud abierta que ya tenga un identificador abierto.

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.

Valor	Significado
0 0x00000000	Impide que otros procesos abran un archivo o dispositivo si solicitan acceso de eliminación, lectura o escritura.
FILE_SHARE_DELETE 0x00000004	Habilita las operaciones abiertas posteriores en un archivo o dispositivo para solicitar acceso de eliminación. De lo contrario, otros procesos no pueden abrir el archivo o el dispositivo si solicitan acceso de eliminación. Si no se especifica esta marca, pero se ha abierto el archivo o el dispositivo para el acceso de eliminación, se produce un error en la función. Nota El acceso de eliminación permite las operaciones de eliminación y cambio de nombre.
FILE_SHARE_READ 0x00000001	Habilita las operaciones abiertas posteriores en un archivo o dispositivo para solicitar acceso de lectura. De lo contrario, otros procesos no pueden abrir el archivo o el dispositivo si solicitan acceso de lectura. Si no se especifica esta marca, pero se ha abierto el archivo o el dispositivo para el acceso de lectura, se produce un error en la función.
FILE_SHARE_WRITE 0x00000002	Habilita las operaciones abiertas posteriores en un archivo o dispositivo para solicitar acceso de escritura. De lo contrario, otros procesos no pueden abrir el archivo o el dispositivo si solicitan acceso de escritura. Si no se especifica esta marca, pero el archivo o dispositivo se ha abierto para el acceso de escritura o tiene una asignación de archivos con acceso de escritura, se produce un error en la funció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 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, se asigna un descriptor de seguridad predeterminado al archivo o dispositivo asociado al identificador devuelto.

Esta función 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.

dwCreationDisposition

Acción que se debe realizar en un archivo o dispositivo que existe o no existe.

En el caso de los dispositivos distintos de los archivos, este parámetro suele establecerse 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:

Valor	Significado
CREATE_ALWAYS 2	Crea un nuevo archivo, siempre. Si el archivo especificado existe y se puede escribir, la función trunca el archivo, la función se realiza correctamente y el código de último error se establece en ERROR_ALREADY_EXISTS (183). Si el archivo especificado no existe y es una ruta de acceso válida, se crea un nuevo archivo, la función se realiza correctamente y el último código de error se establece en cero. Para obtener más información, vea la sección Comentarios.
CREATE_NEW 1	Crea un nuevo archivo, solo si aún no existe. Si el archivo especificado existe, se produce un error en la función y el último código de error se establece en ERROR_FILE_EXISTS (80). Si el archivo especificado no existe y es una ruta de acceso válida a una ubicación grabable, se crea un nuevo archivo.
OPEN_ALWAYS 4	Abre un archivo, siempre. Si el archivo especificado existe, la función se realiza correctamente y el último código de error se establece en ERROR_ALREADY_EXISTS (183). Si el archivo especificado no existe y es una ruta de acceso válida a una ubicación grabable, la función crea un archivo y el último código de error se establece en cero.
OPEN_EXISTING 3	Abre un archivo o dispositivo, solo si existe. Si el archivo o dispositivo especificados no existe, se produce un error en la función y el último código de error se establece en ERROR_FILE_NOT_FOUND (2). Para obtener más información sobre los dispositivos, consulte la sección Comentarios.
TRUNCATE_EXISTING 5	Abre un archivo y lo trunca para que su tamaño sea cero bytes, solo si existe. Si el archivo especificado no existe, se produce un error en la función y el último código de error se establece en ERROR_FILE_NOT_FOUND (2). El proceso de llamada debe abrir el archivo con el GENERIC_WRITE bit establecido como parte del parámetro dwDesiredAccess .

dwFlagsAndAttributes

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.

Este parámetro también 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. 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.

Atributo	Significado
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	El archivo debe archivarse. Las aplicaciones usan este atributo para marcar los archivos para crear una copia de seguridad o quitarlos.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	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.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	El archivo está oculto. No lo incluya en una lista de directorios normal.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	El archivo no tiene otros atributos establecidos. Este atributo solo es válido si se usa por sí solo.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	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.
FILE_ATTRIBUTE_READONLY 1 (0x1)	El archivo es de solo lectura. Las aplicaciones pueden leer el archivo, pero no pueden escribir en él ni eliminarlo.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	El archivo forma parte o se usa exclusivamente por un sistema operativo.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	El archivo se usa para el almacenamiento temporal. Para obtener más información, consulte la sección Comportamiento del almacenamiento en caché de este tema.

Marca	Significado
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	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 la sección Comentarios.
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	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 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.
FILE_FLAG_NO_BUFFERING 0x20000000	El archivo o dispositivo se abre 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 los archivos abiertos con esta función mediante la marca FILE_FLAG_NO_BUFFERING , para obtener más información, consulte Almacenamiento en búfer de archivos.
FILE_FLAG_OPEN_NO_RECALL 0x00100000	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.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	No se producirá el procesamiento normal del punto de reanálisis ; esta función 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.
FILE_FLAG_OVERLAPPED 0x40000000	El archivo o dispositivo se abre o se crea 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, se serializan las operaciones de E/S, 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, vea la sección Identificadores de E/S sincrónicos y asincrónicos de este tema.
FILE_FLAG_POSIX_SEMANTICS 0x0100000	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.
FILE_FLAG_RANDOM_ACCESS 0x10000000	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, consulte la sección Comportamiento del almacenamiento en caché de este tema.
FILE_FLAG_SESSION_AWARE 0x00800000	El archivo o dispositivo se abre 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 mediante el redireccionamiento USB de 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.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	El acceso está pensado para ser secuencial desde el principio hasta el final. 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 inversos). 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 del almacenamiento en caché de este tema.
FILE_FLAG_WRITE_THROUGH 0x80000000	Las operaciones de escritura no pasarán por ninguna memoria caché intermedia, que pasarán directamente al disco. Para obtener más información, consulte la sección Comportamiento del almacenamiento en caché de este tema.

El parámetro dwFlagsAndAttributestambién puede especificar información de SQOS. 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.

Marca de seguridad	Significado
SECURITY_ANONYMOUS	Suplanta a un cliente en el nivel de suplantación anónima.
SECURITY_CONTEXT_TRACKING	El modo de seguimiento de seguridad es dinámico. Si no se especifica esta marca, el modo de seguimiento de seguridad es estático.
SECURITY_DELEGATION	Suplanta a un cliente en el nivel de suplantación de delegación.
SECURITY_EFFECTIVE_ONLY	Solo los aspectos habilitados del contexto de seguridad del cliente están disponibles para el servidor. Si no especifica esta marca, todos los aspectos del contexto de seguridad del cliente están disponibles. Esto permite al cliente limitar los grupos y privilegios que un servidor puede usar al suplantar al cliente.
SECURITY_IDENTIFICATION	Suplanta a un cliente en el nivel de suplantación de identificación.
SECURITY_IMPERSONATION	Suplantar a un cliente en el nivel de suplantación. Este es el comportamiento predeterminado si no se especifica ninguna otra marca junto con la marca SECURITY_SQOS_PRESENT .

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, este parámetro se omite.

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, vea Cifrado de archivos.

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.

Requisitos


Cliente mínimo compatible	Windows 10, versión 1803
Encabezado	fileapifromapp.h