Función ClfsCreateLogFile (wdm.h)
La rutina ClfsCreateLogFile crea o abre una secuencia CLFS. Si es necesario, ClfsCreateLogFile también crea el registro físico subyacente que contiene los registros de la secuencia.
Sintaxis
CLFSUSER_API NTSTATUS ClfsCreateLogFile(
[out] PPLOG_FILE_OBJECT pplfoLog,
[in] PUNICODE_STRING puszLogFileName,
[in] ACCESS_MASK fDesiredAccess,
[in] ULONG dwShareMode,
[in, optional] PSECURITY_DESCRIPTOR psdLogFile,
[in] ULONG fCreateDisposition,
[in] ULONG fCreateOptions,
[in] ULONG fFlagsAndAttributes,
[in] ULONG fLogOptionFlag,
[in, optional] PVOID pvContext,
[in] ULONG cbContext
);
Parámetros
[out] pplfoLog
Puntero a una variable que recibe un puntero a una estructura LOG_FILE_OBJECT que representa una instancia abierta de la secuencia.
[in] puszLogFileName
Puntero a una estructura de UNICODE_STRING que proporciona el nombre de la secuencia o el registro físico subyacente.
Si la secuencia ya existe y es la única secuencia de un registro dedicado, el nombre tiene el formato log:physical log name, donde physical log name es el nombre de la ruta de acceso, en el sistema de archivos subyacente, del registro físico existente que contiene los registros de la secuencia.
Si la secuencia aún no existe y se va a convertir en la única secuencia de un registro dedicado (que aún no existe), el nombre tiene el formato log:physical log name, donde physical log name es el nombre de ruta de acceso, en el sistema de archivos subyacente, del registro físico que se creará para contener los registros de la secuencia.
Si la secuencia es (o se va a convertir) en una de las secuencias de un registro multiplexado, el nombre tiene el formato log:physical log name::stream name, donde physical log name es el nombre de ruta de acceso, en el sistema de archivos subyacente, del registro físico que contiene los registros de la secuencia y el nombre de la secuencia es el nombre de una secuencia que comparte (o compartirá) ese registro físico.
Si desea crear un registro multiplexado que no tenga secuencias por el momento, use un nombre del formulario log:physical log name::, donde physical log name es el nombre de ruta de acceso, en el sistema de archivos subyacente, del registro físico que se va a crear.
En la lista siguiente se proporcionan algunos ejemplos de nombres válidos.
- "Log:c:\myLog" crea o abre un registro dedicado y su una secuencia.
- "Log:c:\myCommonLog::" crea un registro multiplexado que aún no tiene secuencias.
- "Log:c:\myCommonLog::Stream1" crea o abre una de las secuencias (Stream1) de un registro multiplexado.
[in] fDesiredAccess
Un ACCESS_MASK que proporciona el tipo de acceso que tendrá el cliente (mediante el puntero devuelto en pplfoLog) a la secuencia. Si este parámetro es cero, los clientes pueden consultar la secuencia de sus atributos, pero no pueden leer ni escribir en la secuencia. Este parámetro puede ser cero o cualquier combinación de las marcas siguientes:
| Marca | Significado |
|---|---|
| GENERIC_READ | El cliente tiene acceso de lectura a la secuencia. |
| GENERIC_WRITE | El cliente tiene acceso de escritura a la secuencia. |
| Delete | El cliente puede marcar la secuencia para su eliminación. |
[in] dwShareMode
Modo de uso compartido de la secuencia, que puede ser cero (no compartido) o cualquier combinación de las marcas siguientes:
| Marca | Significado |
|---|---|
| FILE_SHARE_DELETE | Las solicitudes posteriores para abrir la secuencia con acceso de eliminación se realizarán correctamente. |
| FILE_SHARE_READ | Las solicitudes posteriores para abrir la secuencia con acceso de lectura se realizarán correctamente. |
| FILE_SHARE_WRITE | Las solicitudes posteriores para abrir la secuencia con acceso de escritura se realizarán correctamente. |
[in, optional] psdLogFile
Puntero a una estructura de SECURITY_DESCRIPTOR que proporciona atributos de seguridad para la secuencia. Este parámetro puede ser NULL.
[in] fCreateDisposition
La acción que se va a realizar depende de si la secuencia ya existe. Este parámetro debe establecerse en uno de los siguientes valores:
| Valor | Significado |
|---|---|
| CREATE_NEW | Cree una nueva secuencia si la secuencia aún no se cierra. Se produce un error si la secuencia ya existe. |
| OPEN_EXISTING | Abra una secuencia existente. Se produce un error si la secuencia aún no existe. |
| OPEN_ALWAYS | Abra una secuencia existente. Cree la secuencia si aún no existe. |
[in] fCreateOptions
Conjunto de marcas que especifican opciones que se aplicarán al crear o abrir la secuencia. Este parámetro puede ser cero o una combinación compatible de las marcas siguientes:
| Marca | Significado |
|---|---|
| FILE_NO_INTERMEDIATE_BUFFERING | Los registros de la secuencia no se pueden almacenar en caché en los búferes internos de un controlador. |
| FILE_SYNCHRONOUS_IO_ALERT | Todas las operaciones de la secuencia se realizan de forma sincrónica. Cualquier espera en nombre del autor de la llamada está sujeta a la terminación prematura de las alertas. Si se establece esta marca, se debe borrar la marca FILE_SYNCHRONOUS_IO_NONALERT. |
| FILE_SYNCHRONOUS_IO_NONALERT | Todas las operaciones de la secuencia se realizan de forma sincrónica. Las esperas en el sistema que sincronizan la cola de E/S y la finalización no están sujetas a alertas. Si se establece esta marca, se debe borrar la marca FILE_SYNCHRONOUS_IO_ALERT. |
[in] fFlagsAndAttributes
Valor que especifica si la secuencia se abre para el acceso normal o de solo lectura. Este parámetro debe establecerse en cualquiera de los dos
FILE_ATTRIBUTE_NORMAL o FILE_ATTRIBUTE_READONLY.
[in] fLogOptionFlag
Sugerencia sobre la relación entre CLFS y el componente que crea o abre la secuencia. Este parámetro debe establecerse en uno de los siguientes valores:
| Valor | Significado |
|---|---|
| CLFS_FLAG_NO_FLAGS | CLFS y el componente de creación tienen la relación estándar y normal. Los componentes en modo kernel usan este valor a menos que se dividen en una de las tres otras categorías enumeradas en esta tabla. Si pvContext no es NULL, CLFS comprueba que cbContext es mayor que cero. De lo contrario, se omiten pvContext y cbContext . |
| CLFS_FLAG_REENTRANT_FILE_SYSTEM | El componente de creación es el sistema de archivos que proporciona el almacenamiento subyacente para CLFS. CLFS usa el sistema de archivos para asignar contenedores y el sistema de archivos usa secuencias CLFS. En este caso, es posible que el sistema de archivos llame a CLFS y que CLFS vuelva a realizar llamadas al sistema de archivos en el mismo subproceso o subprocesos diferentes. Si pvContext no es NULL, CLFS comprueba que cbContext es mayor que cero. De lo contrario, se omiten pvContext y cbContext . |
| CLFS_FLAG_NON_REENTRANT_FILTER | El componente de creación es un controlador de filtro del sistema de archivos que envía todas sus E/S de CLFS a un nivel especificado por debajo de sí mismo en la pila de filtros. Esta opción permite que un controlador de filtro cree un registro CLFS sin ver su propia E/S de registro. El autor de la llamada pasa el objeto de dispositivo de destino distinto de NULL en el parámetro pvContext con cbContext establecido en el tamaño adecuado. CLFS usa la rutina IoCreateFileSpecifyDeviceObjectHint para crear contenedores en un nivel de destino en la pila de filtros de E/S especificada por el objeto de dispositivo. |
| CLFS_FLAG_REENTRANT_FILTER | El componente de creación es un controlador de filtro del sistema de archivos que envía todas sus E/S de CLFS a la parte superior de la pila de filtros. El filtro tiene una relación recursiva con CLFS porque filtra su propia E/S de registro cuando CLFS realiza cualquier operación del sistema de archivos en sus contenedores. El parámetro pvContext proporciona un medio para que los filtros asocien un contexto reconocible con sus contenedores CLFS a medida que la E/S de registro baja la pila de filtros. El parámetro cbContext especifica el tamaño del contexto opaco en bytes. |
| CLFS_FLAG_MINIFILTER_LEVEL | El componente de creación es un controlador de minifiltro del sistema de archivos que envía todas sus E/S de CLFS a un nivel especificado por debajo de sí mismo en la pila de filtros. Esta opción permite que un minifiltro cree un registro CLFS sin ver su propia E/S de registro. El autor de la llamada pasa el objeto de contexto de minifiltro distinto de NULL en el parámetro pvContext con cbContext establecido en el tamaño adecuado. CLFS usa la rutina IoCreateFileSpecifyDeviceObjectHint para crear contenedores a una altitud (especificada dentro del contexto de minifiltro) en la pila de minifiltros del administrador de filtros. |
[in, optional] pvContext
Puntero a un contexto. La forma en que se interpreta el contexto depende del valor pasado a fLogOptionsFlag.
[in] cbContext
Tamaño, en bytes, del contexto al que apunta pvContext. Si pvContext no es NULL, este parámetro debe ser mayor que cero.
Valor devuelto
ClfsCreateLogFile devuelve STATUS_SUCCESS si se realiza correctamente; de lo contrario, devuelve uno de los códigos de error definidos en Ntstatus.h.
Comentarios
Al crear una secuencia CLFS, está respaldada por un registro CLFS físico subyacente. El registro subyacente puede ser dedicado (solo una secuencia) o multiplexado (hace una copia de seguridad de varias secuencias). No se puede convertir un registro dedicado en un registro multiplexado y no se puede convertir un registro multiplexado en un registro dedicado.
Un nombre de registro CLFS físico no incluye la extensión .blf.
Para obtener una explicación de los conceptos y la terminología de CLFS, consulte Common Log File System.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Disponible en Windows Server 2003 R2, Windows Vista y versiones posteriores de Windows. |
| Plataforma de destino | Escritorio |
| Encabezado | wdm.h (incluya Wdm.h) |
| Library | Clfs.lib |
| Archivo DLL | Clfs.sys |
| IRQL | <= APC_LEVEL |