ClfsCreateLogFile function

The ClfsCreateLogFile routine creates or opens a CLFS stream. If necessary, ClfsCreateLogFile also creates the underlying physical log that holds the stream's records.

Syntax

CLFSUSER_API NTSTATUS ClfsCreateLogFile(
  PPLOG_FILE_OBJECT    pplfoLog,
  PUNICODE_STRING      puszLogFileName,
  ACCESS_MASK          fDesiredAccess,
  ULONG                dwShareMode,
  PSECURITY_DESCRIPTOR psdLogFile,
  ULONG                fCreateDisposition,
  ULONG                fCreateOptions,
  ULONG                fFlagsAndAttributes,
  ULONG                fLogOptionFlag,
  PVOID                pvContext,
  ULONG                cbContext
);

Parameters

pplfoLog

A pointer to a variable that receives a pointer to a LOG_FILE_OBJECT structure that represents an open instance of the stream.

puszLogFileName

A pointer to a UNICODE_STRING structure that supplies the name of the stream or the underlying physical log.

If the stream already exists and is the only stream of a dedicated log, the name has the form log:physical log name, where physical log name is the path name, on the underlying file system, of the existing physical log that contains the stream's records.

If the stream does not already exist and is to become the only stream of a dedicated log (that does not yet exist), the name has the form log:physical log name, where physical log name is the path name, on the underlying file system, of the physical log that will be created to hold the stream's records.

If the stream is (or is to become) one of the streams of a multiplexed log, the name has the form log:physical log name::stream name, where physical log name is the path name, on the underlying file system, of the physical log that holds the stream's records, and stream name is the name of a stream that shares (or will share) that physical log.

If you want to create a multiplexed log that has no streams for the moment, use a name of the form log:physical log name::, where physical log name is the path name, on the underlying file system, of the physical log to be created.

The following list gives some examples of valid names.

  • "Log:c:\myLog" creates or opens a dedicated log and its one stream.
  • "Log:c:\myCommonLog::" creates a multiplexed log that does not yet have any streams.
  • "Log:c:\myCommonLog::Stream1" creates or opens one of the streams (Stream1) of a multiplexed log.

fDesiredAccess

An ACCESS_MASK that supplies the type of access the client will have (by using the pointer returned in pplfoLog) to the stream. If this parameter is zero, clients can query the stream for its attributes, but cannot read from or write to the stream. This parameter can be zero or any combination of the following flags:

Flag Meaning
GENERIC_READ The client has read access to the stream.
GENERIC_WRITE The client has write access to the stream.
DELETE The client can mark the stream for deletion.

dwShareMode

The sharing mode of the stream, which can be zero (not shared) or any combination of the following flags:

Flag Meaning
FILE_SHARE_DELETE Subsequent requests to open the stream with delete access will succeed.
FILE_SHARE_READ Subsequent requests to open the stream with read access will succeed.
FILE_SHARE_WRITE Subsequent requests to open the stream with write access will succeed.

psdLogFile

A pointer to a SECURITY_DESCRIPTOR structure that supplies security attributes for the stream. This parameter can be NULL.

fCreateDisposition

The action to take that depends on whether the stream already exists. This parameter must be set to one of the following values:

Value Meaning
CREATE_NEW Create a new stream if the stream does not already exits. Fail if the stream already exists.
OPEN_EXISTING Open an existing stream. Fail if the stream does not already exist.
OPEN_ALWAYS Open an existing stream. Create the stream if it does not already exist.

fCreateOptions

A set of flags that specify options to apply when creating or opening the stream. This parameter can be zero or a compatible combination of the following flags:

Flag Meaning
FILE_NO_INTERMEDIATE_BUFFERING The stream's records cannot be cached in a driver's internal buffers.
FILE_SYNCHRONOUS_IO_ALERT All operations on the stream are performed synchronously. Any wait on behalf of the caller is subject to premature termination from alerts. If this flag is set, the FILE_SYNCHRONOUS_IO_NONALERT flag must be cleared.
FILE_SYNCHRONOUS_IO_NONALERT All operations on the stream are performed synchronously. Waits in the system that synchronize I/O queuing and completion are not subject to alerts. If this flag is set, the FILE_SYNCHRONOUS_IO_ALERT flag must be cleared.

fFlagsAndAttributes

A value that specifies whether the stream is opened for normal or read-only access. This parameter must be set to either

FILE_ATTRIBUTE_NORMAL or FILE_ATTRIBUTE_READONLY.

fLogOptionFlag

A hint about the relationship between CLFS and the component creating or opening the stream. This parameter must be set to one of the following values:

Value Meaning
CLFS_FLAG_NO_FLAGS CLFS and the creating component have the standard, normal relationship. Kernel-mode components use this value unless they fall into one of the three other categories listed in this table. If pvContext is not NULL, CLFS verifies that cbContext is greater than zero. Otherwise, pvContext and cbContext are ignored.
CLFS_FLAG_REENTRANT_FILE_SYSTEM The creating component is the file system that provides the underlying storage for CLFS. CLFS uses the file system for allocating containers, and the file system uses CLFS streams. In this case, it is possible for the file system to call CLFS and for CLFS to make calls back into the file system on the same thread or different threads. If pvContext is not NULL, CLFS verifies that cbContext is greater than zero. Otherwise, pvContext and cbContext are ignored.
CLFS_FLAG_NON_REENTRANT_FILTER The creating component is a file system filter driver that sends all of its CLFS I/O to a specified level below itself on the filter stack. This option allows a filter driver to create a CLFS log without seeing its own logging I/O. The caller passes the non-NULL target device object in the pvContext parameter with cbContext set to the appropriate size. CLFS uses the IoCreateFileSpecifyDeviceObjectHint routine to create containers at a targeted level in the I/O filter stack specified by the device object.
CLFS_FLAG_REENTRANT_FILTER The creating component is a file system filter driver that sends all of its CLFS I/O to the top of the filter stack. The filter has a recursive relationship with CLFS because it filters its own logging I/O when CLFS performs any file system operation on its containers. The pvContext parameter provides a means for filters to associate a recognizable context with its CLFS containers as log I/O comes down the filter stack. The cbContext parameter specifies the size of the opaque context in bytes.
CLFS_FLAG_MINIFILTER_LEVEL The creating component is a file system minifilter driver that sends all of its CLFS I/O to a specified level below itself on the filter stack. This option allows a minifilter to create a CLFS log without seeing its own logging I/O. The caller passes the non-NULL minifilter context object in the pvContext parameter with cbContext set to the appropriate size. CLFS uses the IoCreateFileSpecifyDeviceObjectHint routine to create containers at an altitude (specified within the minifilter context) in the filter manager's minifilter stack.

pvContext

A pointer to a context. The way the context is interpreted depends on the value passed to fLogOptionsFlag.

cbContext

The size, in bytes, of the context pointed to by pvContext. If pvContext is not NULL, this parameter must be greater than zero.

Return Value

ClfsCreateLogFile returns STATUS_SUCCESS if it succeeds; otherwise, it returns one of the error codes defined in Ntstatus.h.

Remarks

When you create a CLFS stream, it is backed by an underlying physical CLFS log. The underlying log can be either dedicated (backs only one stream) or multiplexed (backs several streams). A dedicated log cannot be converted to a multiplexed log, and a multiplexed log cannot be converted to a dedicated log.

A physical CLFS log name does not include the .blf extension.

For an explanation of CLFS concepts and terminology, see Common Log File System.

Requirements

   
Windows version Available in Windows Server 2003 R2, Windows Vista, and later versions of Windows.
Target Platform Desktop
Header wdm.h (include Wdm.h)
Library Clfs.lib
DLL Clfs.sys
IRQL "<= APC_LEVEL"

See Also

ClfsCloseAndResetLogFile

ClfsCloseLogFileObject

ClfsDeleteLogByPointer

ClfsDeleteLogFile