CreateFileDirectAsStream Method

Creates or opens a file by passing the request directly to the filesystem.

Syntax

cbfilter.createFileDirectAsStream(fileName, synchronize, desiredAccess, creationDisposition, flagsAndAttributes, [callback])

Callback

The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).

The callback for this method is defined as:

function(err, data){ }

'err' is the error that occurred. If there was no error, then 'err' is 'null'.

'data' is the value returned by the method.

'err' has 2 properties which hold detailed information:

err.code
err.message

Remarks

This method should be used instead of the Windows API's CreateFile function to create or open a file when an application needs to access it without sending requests through the filesystem filter driver stack. If the file is created or opened successfully, this method returns a stream object that provides access to its data; otherwise, it returns null.

Since all requests against the file are routed directly to the filesystem (bypassing all filter drivers, including the class's), applications can use the returned stream within filesystem-related events without causing a system deadlock. (However, pay special attention to the Synchronize parameter's documentation, below.)

The FileName, DesiredAccess, CreationDisposition, and FlagsAndAttributes parameters correspond to the lpFileName, dwDesiredAccess, dwCreationDisposition, and dwFlagsAndAttributes parameters of the Windows API's CreateFile function (respectively). Please refer to Microsoft's documentation for more information on how to set these parameters appropriately.

The file is opened with a sharing mode that allows other processes open the file for any kind of operation.

The Synchronize parameter specifies whether this method should be synchronized with the external thread that originated the underlying filesystem request associated with the current event (i.e., the event that this method was called from).

If Synchronize is true, this method will execute in the context of the request thread (which is important for on-the-fly file data modification like encryption, etc.), and the following restrictions will apply:

• The method may only be called within the AfterCreateFile and AfterOpenFile events, and only for the file or directory that the event fired for.
• The DesiredAccess, CreationDisposition, and FlagsAndAttributes parameters are ignored.
• Files will be opened without buffering, which means that applications must comply with all restrictions imposed by the FILE_FLAG_NO_BUFFERING flag when reading and writing file data. Please refer to Microsoft's File Buffering article for more information.

If Synchronize is false, this method is not synchronized with the request thread, and the restrictions described above do not apply. This provides applications with greater flexibility since the returned file handle can be used in any event (so long as its handler complies with the general restrictions described by the Avoiding Deadlocks and Recursive Calls topics).

In both cases, the class must be active, i.e., it must be started using a call to the StartFilter method.