CreateFileDirect Method

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

Syntax

ANSI (Cross Platform)
int64 CreateFileDirect(const char* lpszFileName, int bSynchronize, int iDesiredAccess, int iCreationDisposition, int iFlagsAndAttributes, int bCloseImmediately);

Unicode (Windows)
LONG64 CreateFileDirect(LPCWSTR lpszFileName, BOOL bSynchronize, INT iDesiredAccess, INT iCreationDisposition, INT iFlagsAndAttributes, BOOL bCloseImmediately);
#define MID_CBFILTER_CREATEFILEDIRECT 13

CBFSFILTER_EXTERNAL int CBFSFILTER_CALL CBFSFilter_CBFilter_Do(void *lpObj, int methid, int cparam, void *param[], int cbparam[], int64 *lpllVal);

Remarks

This method should be used instead of the Windows API's CreateFile function to create or open a file or directory when an application needs to access it without sending requests through the filesystem filter driver stack (unless DirectRequestsDownTheStack configuration setting is set to true). If the file or directory is created or opened successfully, this method returns a file handle for it; otherwise, it returns INVALID_HANDLE_VALUE. The returned handle, if valid, must be closed using the Windows API's CloseHandle function when the application is finished with it.

If CloseImmediately is true, this method will create or open the specified file or directory and then immediately close the resulting handle. In this case, the handle will still be returned to indicate success of the operation, but it will not be usable in any file operations.

Since all requests against the returned file handle are routed directly to the filesystem (bypassing all filter drivers, including the class's), applications can use it to call Windows File API functions (ReadFile, WriteFile, etc.) within filesystem-related events without causing a system deadlock. (However, pay special attention to the Synchronize parameter's documentation, below.)

The returned handle can be used with some of the Windows API functions that accept a file handle as a parameter. Support may vary depending on the internal implementation of each function. The following Windows API functions have been tested and proven to work:

Other functions may work as well but have not been tested.

When calling the GetFileInformationByHandleEx function, note that only the following information classes are currently supported:

  • FileAttributeTagInfo
  • FileBasicInfo
  • FileStandardInfo
  • FileStreamInfo
  • FileIdInfo
Support for other information classes depends on the class and OS capabilities.

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 and operations with the resulting handle should be synchronized with the thread that originated the underlying filesystem request associated with the current event (i.e., the event that this method was called from).

The parameter is applicable only when a caller uses it to open the file, for which the event was fired. Also, the parameter should not be set to true when this method is called from the AfterCloseFile event - when the event is fired, there's no open file to synchronize operations with.

If Synchronize is true, this method and all operations with the resulting handle will be execute in the context of the external thread that originated the underlying filesystem request associated with the current event (which is important for on-the-fly file data modification like encryption, etc.), and the following restrictions will apply:

  • The method may be called from any event handles with the exception of AfterCloseFile and CleanupContext. Note: to be able to call the method from the BeforeCreateFile and BeforeOpenFile event handlers, set the AllowFileAccessInBeforeOpen configuration setting to true.
  • The method should be called only for the file or directory that the event fired for.
  • A file 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.
  • The DesiredAccess, CreationDisposition, and FlagsAndAttributes parameters are ignored.

If Synchronize is false, this method and operations with the resulting handle are executed in the context of the thread in hich the corresponding call is made, 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.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Copyright (c) 2022 Callback Technologies, Inc. - All rights reserved.
CBFS Filter 2020 C++ Edition - Version 20.0 [Build 8317]