Función CreateFileFromAppW (fileapifromapp.h)
Crea o abre un archivo o 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 la 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 Archivos de nomenclatura, 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, consulte 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 Archivos de nomenclatura, rutas de acceso y espacios de nombres para obtener más información.
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.
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 el acceso de eliminación. De lo contrario, otros procesos no pueden abrir el archivo o el dispositivo si solicitan el 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 Acceso eliminar 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 se puede heredar 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.
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 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:
| 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 ejecuta 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 ejecuta correctamente y el código de último error se establece en cero. Para obtener más información, vea la sección Comentarios de este tema. |
| 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 código de último 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 código de último 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 conjunto de bits 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 FILE_ATTRIBUTE_* valores.
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.
| Atributo | Significado |
|---|---|
| FILE_ATTRIBUTE_ARCHIVE 32 (0x20) | El archivo debe archivarse. Las aplicaciones usan este atributo para marcar los archivos de copia de seguridad o eliminación. |
| 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 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 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. |
| Bandera | Significado |
|---|---|
| FILE_FLAG_BACKUP_SEMANTICS 0x02000000 | 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. |
| FILE_FLAG_DELETE_ON_CLOSE 0x04000000 | 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. |
| FILE_FLAG_NO_BUFFERING 0x20000000 | 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 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 | 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. |
| FILE_FLAG_OPEN_REPARSE_POINT 0x00200000 | No se producirá el procesamiento normal 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 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 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. |
| 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, 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. |
| FILE_FLAG_RANDOM_ACCESS 0x10000000 | 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 del almacenamiento en caché de este tema. |
| FILE_FLAG_SESSION_AWARE 0x00800000 | 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. |
| FILE_FLAG_SEQUENTIAL_SCAN 0x08000000 | 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 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 a través de ninguna caché intermedia, 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, 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.
| 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 de archivo y atributos extendidos para el archivo que se está creando.
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, consulte 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
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows 10, versión 1803 |
| encabezado de |
fileapifromapp.h |