Función OpenFileById (winbase.h)

Artículo
08/27/2023

Abre el archivo que coincide con el identificador especificado.

Sintaxis

HANDLE OpenFileById(
  [in]           HANDLE                hVolumeHint,
  [in]           LPFILE_ID_DESCRIPTOR  lpFileId,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwFlagsAndAttributes
);

Parámetros

[in] hVolumeHint

Identificador de cualquier archivo de un volumen o recurso compartido en el que se almacena el archivo que se va a abrir.

[in] lpFileId

Puntero a un FILE_ID_DESCRIPTOR que identifica el archivo que se va a abrir.

[in] dwDesiredAccess

Acceso al objeto . El acceso se puede leer, escribir o ambos.

Para obtener más información, vea Derechos de acceso y seguridad de archivos. No se puede solicitar un modo de acceso que entre en conflicto con el modo de uso compartido especificado en una solicitud abierta que tenga un identificador abierto.

Si este parámetro es cero (0), la aplicación puede consultar atributos de archivo y dispositivo sin tener acceso a un dispositivo. Esto es útil para que una aplicación determine el tamaño de una unidad de disco de disquete y los formatos que admite sin necesidad de un disquete en una unidad. También se puede usar para probar la existencia de un archivo o directorio sin abrirlos para el acceso de lectura o escritura.

[in] dwShareMode

Modo de uso compartido de un objeto, que se puede leer, escribir, ambos o ninguno.

No se puede solicitar un modo de uso compartido que entre en conflicto con el modo de acceso especificado en una solicitud abierta que tenga un identificador abierto, ya que esto provocaría la siguiente infracción de uso compartido: (ERROR_SHARING_VIOLATION). Para más información, consulte Crear y abrir archivos.

Si este parámetro es cero (0) y OpenFileById se ejecuta correctamente, el objeto no se puede compartir y no se puede volver a abrir hasta que se cierre el identificador. Para obtener más información, vea la sección Comentarios.

Las opciones de uso compartido permanecen en vigor hasta que se cierra el identificador de un objeto.

Para permitir que un proceso comparta un objeto mientras otro proceso tiene abierto el objeto, use una combinación de uno o varios de los valores siguientes para especificar el modo de acceso que pueden solicitar para abrir el objeto.

Value	Significado
FILE_SHARE_DELETE 0x00000004	Permite que las operaciones abiertas posteriores en un objeto soliciten el acceso de eliminación. De lo contrario, otros procesos no pueden abrir el objeto si solicitan acceso de eliminación. Si no se especifica esta marca, pero el objeto se ha abierto para el acceso de eliminación, se produce un error en la función.
FILE_SHARE_READ 0x00000001	Permite que las operaciones abiertas posteriores en un objeto soliciten acceso de lectura. De lo contrario, otros procesos no pueden abrir el objeto si solicitan acceso de lectura. Si no se especifica esta marca, pero el objeto se ha abierto para el acceso de lectura, se produce un error en la función.
FILE_SHARE_WRITE 0x00000002	Permite que las operaciones abiertas posteriores en un objeto soliciten acceso de escritura. De lo contrario, otros procesos no pueden abrir el objeto si solicitan acceso de escritura. Si no se especifica esta marca, pero el objeto 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.

Value

Significado

FILE_SHARE_DELETE
0x00000004

Permite que las operaciones abiertas posteriores en un objeto soliciten el acceso de eliminación.

De lo contrario, otros procesos no pueden abrir el objeto si solicitan acceso de eliminación.

Si no se especifica esta marca, pero el objeto se ha abierto para el acceso de eliminación, se produce un error en la función.

FILE_SHARE_READ
0x00000001

Permite que las operaciones abiertas posteriores en un objeto soliciten acceso de lectura.

De lo contrario, otros procesos no pueden abrir el objeto si solicitan acceso de lectura.

Si no se especifica esta marca, pero el objeto se ha abierto para el acceso de lectura, se produce un error en la función.

FILE_SHARE_WRITE
0x00000002

Permite que las operaciones abiertas posteriores en un objeto soliciten acceso de escritura.

De lo contrario, otros procesos no pueden abrir el objeto si solicitan acceso de escritura.

Si no se especifica esta marca, pero el objeto 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.

[in, optional] lpSecurityAttributes

Reservado.

[in] dwFlagsAndAttributes

Marcas de archivo.

Cuando OpenFileById abre un archivo, combina las marcas de archivo con atributos de archivo existentes y omite los atributos de archivo proporcionados. Este parámetro puede incluir cualquier combinación de las marcas siguientes.

Value	Significado
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	Se abre un archivo 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 Identificadores de directorio.
FILE_FLAG_NO_BUFFERING 0x20000000	El sistema abre un archivo sin almacenamiento en caché del sistema. Esta marca no afecta al almacenamiento en caché del disco duro. Cuando se combina con FILE_FLAG_OVERLAPPED, la marca proporciona 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 sigan almacenando en caché. Para vaciar los metadatos en el disco, use la función FlushFileBuffers. Una aplicación debe cumplir ciertos requisitos al trabajar con archivos que se abren con FILE_FLAG_NO_BUFFERING: El acceso a archivos debe comenzar en desplazamientos de bytes dentro de un archivo que sea múltiplo entero del tamaño del sector del volumen. El acceso a archivos debe ser para los números de bytes que son múltiplo enteros del tamaño del sector del volumen. Por ejemplo, si el tamaño del sector es de 512 bytes, una aplicación puede solicitar lecturas y escrituras de 512, 1024, 1536 o 2048 bytes, pero no de 335, 981 o 7171 bytes. Las direcciones de búfer para las operaciones de lectura y escritura deben estar alineadas por sectores, lo que significa que se alinean en direcciones en memoria que son múltiplos enteros del tamaño del sector del volumen. Dependiendo del disco, es posible que este requisito no se aplique. Una manera de alinear los búferes en múltiplos enteros del tamaño del sector de volumen es usar VirtualAlloc para asignar los búferes. Asigna memoria alineada en direcciones que son múltiplos enteros del tamaño de página de memoria del sistema operativo. Dado que tanto los tamaños de página de memoria como de sector de volumen son potencias de 2, esta memoria también se alinea en direcciones que son múltiplos enteros de un tamaño de sector de volumen. Las páginas de memoria tienen un tamaño de 4 a 8 KB; los sectores son 512 bytes (discos duros) o 2048 bytes (CD) y, por lo tanto, los sectores de volumen nunca pueden ser mayores que las páginas de memoria. Una aplicación puede determinar un tamaño de sector de volumen llamando a la función GetDiskFreeSpace .
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 es para que la usen los sistemas de almacenamiento remoto.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	Cuando se usa esta marca, no se produce el procesamiento normal del punto de reanálisis y OpenFileById intenta 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.
FILE_FLAG_OVERLAPPED 0x40000000	El archivo se abre o se crea para E/S asincrónica. Una vez completada la operación, el evento especificado en la llamada en la estructura SUPERPUESTA se establece en el estado señalado. Las operaciones que tardan mucho tiempo en procesar la devolución ERROR_IO_PENDING. Si se especifica esta marca, el archivo se puede usar para operaciones simultáneas de lectura y escritura. El sistema no mantiene el puntero de archivo, por lo tanto, debe pasar la posición del archivo a las funciones de lectura y escritura en la estructura SUPERPUESTA o actualizar el puntero de archivo. 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 .
FILE_FLAG_RANDOM_ACCESS 0x10000000	Se tiene acceso a un archivo de forma aleatoria. El sistema puede considerar que esto es una sugerencia para optimizar el almacenamiento en caché del archivo.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	Se tiene acceso a un archivo de forma secuencial, desde el principio hasta el final. El sistema puede considerar que esto es una sugerencia para optimizar el almacenamiento en caché del archivo. Si una aplicación mueve el puntero de archivo para el acceso aleatorio, es posible que no se produzca un almacenamiento en caché óptimo. Sin embargo, todavía se garantiza la operación correcta. Especificar esta marca 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 ocasionalmente omiten intervalos pequeños de bytes.
FILE_FLAG_WRITE_THROUGH 0x80000000	El sistema escribe a través de cualquier caché intermedia y va directamente al disco. Si 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 también se especifica 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. El sistema operativo también solicita una escritura a través de la memoria caché del disco duro a medios persistentes. Sin embargo, no todo el hardware admite esta funcionalidad de escritura a través.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador abierto para un archivo especificado.

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.

Comentarios

Use la función CloseHandle para cerrar un identificador de objeto que Devuelve OpenFileById .

Si llama a OpenFileById 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.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	No
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 a errores (ReFS)	Sí

Requisitos


Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbase.h (incluye Windows.h)
Library	Kernel32.lib; FileExtd.lib en Windows Server 2003 y Windows XP
Archivo DLL	Kernel32.dll
Redistribuible	Windows SDK en Windows Server 2003 y Windows XP.