CallbackFilter

Instant control over file and folder operations in Windows and .NET applications

OnCreateFileC event/delegate/callback

Filter:

Pascal    C++ (Lib)    C++ (VCL)    C++ (.NET)    C#    VB.NET   

CallbackFilter     See also    

Overview

This callback is called when the OS handles file or directory creation request.

Declaration

[Pascal]
    property OnCreateFileC : TCbFltCreateFileEventC;
    TCbFltCreateFileEventC = procedure(Sender : TObject; FileName: TCBString; var DesiredAccess: DWORD; var FileAttributes: DWORD; var ShareMode: WORD; var Options: DWORD; var CreateDisposition: WORD; var VirtualFile : boolean; var ProcessRequest: boolean) of object;
    type TCBString = {$ifdef UNICODE}UnicodeString{$else}WideString{$endif};

[C++ (Lib)]
    typedef void (*CbFltCreateFileEventC)(CallbackFilter* Sender, LPWSTR FileName, DWORD* DesiredAccess, DWORD* FileAttributes, WORD* ShareMode, DWORD* Options, WORD* CreateDisposition, LPBOOL VirtualFile, LPBOOL RequestAccepted);

[C++ (VCL)]
    typedef void __fastcall (__closure *TCbFltCreateFileEventC)(System::TObject* Sender, TCBString FileName, unsigned long &DesiredAccess, unsigned long &FileAttributes, unsigned short &ShareMode, unsigned long &Options, unsigned short &CreateDisposition, bool &VirtualFile, bool &ProcessRequest);
    #ifdef UNICODE
    typedef UnicodeString TCBString;
    #else
    typedef WideString TCBString;
    #endif

[C++ (.NET)]
    public delegate void CbFltCreateFileEventC(CallbackFilter^ Sender, String^ FileName, UInt32% DesiredAccess, UInt32% FileAttributes, UInt16% ShareMode, UInt32% Options, UInt32% CreateDisposition, bool% VirtualFile, bool% ProcessRequest);

[C#]
    delegate void CbFltCreateFileEventC(CallbackFilter Sender, string FileName, ref UInt32 DesiredAccess, ref UInt32 FileAttributes, ref UInt16 ShareMode, ref UInt32 Options, ref UInt16 CreateDisposition, ref bool VirtualFile, ref bool ProcessRequest);

[VB.NET]
    Delegate Sub CbFltCreateFileEventC(ByVal Sender As CallbackFilter, ByVal FileName As String, ByRef DesiredAccess As UInt32, ByRef FileAttributes As UInt32, ByRef ShareMode As UInt16, ByRef Options As UInt32, ByRef CreateDisposition As UInt16, ByRef VirtualFile As Boolean, ByRef ProcessRequest As Boolean)

Parameters

  • Sender - reference to the class that called the delegate/event handler
  • FileName - contains the name of the file to create
  • DesiredAccess - desired mode of access to the created file (dwDesiredAccess parameter of CreateFile() Windows API function)
  • FileAttributes - the attributes to be set for the newly created file
  • ShareMode - desired share mode (dwShareMode parameter of CreateFile() Windows API function)
  • Options - requested FILE_FLAG_xxx options (dwFlagsAndAttributes parameter of CreateFile() Windows API function)
  • CreateDisposition - requested creation disposition (dwCreationDisposition parameter of CreateFile() Windows API function)
  • VirtualFile - when set, indicates that the virtual file is being created
  • ProcessRequest (RequestAccepted) - specifies, whether the request must be passed further to the underlying filters and the file system

Description

This callback is called when the OS wants to create a file or directory with given name and attributes.

DesiredAccess, FileAttributes, ShareMode, Options and CreateDisposition are passed as they were specified in the call to CreateFile() Windows API function. For more details check MSDN library shipped with your development tool and also available online.

To check, whether it's file or directory that should be opened, check FileAttributes as follows (C++ / C# notation): Directory = FileAttributes & FILE_ATTRIBUTE_DIRECTORY == FILE_ATTRIBUTE_DIRECTORY;

This callback is called before the file has been opened. It can happen that the file will not be opened by the underlying file system. If you want to be notified when the file is already opened, use OnPostCreateFileC event.

If your application initiates file create/open operation AND filters such requests at the same time (eg. for debugging or testing purposes), you need to set OwnProcessFiltered property to true.

Setting ProcessRequest parameter to false has the same effect as throwing an exception with the error code of ACCESS_DENIED. When ProcessRequest is set to false, the opening operation fails and the error is returned to the OS.

Read more about when excatly On*CreateFile* and On*OpenFile* callbacks are called.

Set VirtualFile parameter to true if the file to be created is virtual (and doesn't exist on the disk or should not be used from the disk). If the file is already known to be virtual, VirtualFile parameter can be set to true when the callback / event handler is called. For description of virtual file support, read Virtual Files topic.

Error handling

See Error handling topic for detailed information about how to report errors, which occur in the event handlers, back to CallbackFilter.

See also

OwnProcessFiltered     OnCreateFileN     OnPostCreateFileC

Back to top