OnCreateFile event/delegate/callback

Filter:

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

CBFSConnect     See also    

Overview

This event is fired when the OS handles file or directory creation event.

Declaration

[Pascal]
    property OnCreateFile : TCBCreateFileEvent;
    TCBCreateFileEvent = procedure( Sender : TObject; FileName: TCBString; DesiredAccess: LongWord; FileAttributes: LongWord; ShareMode: LongWord; FileInfo: TCBFileInfo; HandleInfo: TCBHandleInfo ) of object;
    type TCBString = {$ifdef UNICODE}UnicodeString{$else}WideString{$endif};

[C++ (Lib)]
    void (__stdcall *CBCreateFileEvent)(void* Sender, wchar_t* FileName, unsigned long DesiredAccess, unsigned long FileAttributes, unsigned long ShareMode, CBFileInfo* FileInfo, CBHandleInfo* HandleInfo );

[C++ (VCL)]
    typedef void (__closure *TCBCreateFileEvent)( System::TObject* Sender, TCBString FileName, unsigned long DesiredAccess, unsigned long FileAttributes, unsigned long ShareMode, TCBFileInfo* FileInfo, TCBHandleInfo* HandleInfo );

[C++ (.NET)]
    public __delegate void CBCreateFileEvent( CBFSConnect^ Sender, String^ FileName, UInt32 DesiredAccess, UInt32 FileAttributes, UInt32 ShareMode, CBFileInfo^ FileInfo, CBHandleInfo^ HandleInfo );

[C#]
    public void CBCreateFileEvent( CBFSConnect Sender, string FileName, UInt32 DesiredAccess, UInt32 FileAttributes, UInt32 ShareMode, CBFileInfo FileInfo, CBHandleInfo HandleInfo );

[VB.NET]
    Sub CBCreateFileEvent( ByVal Sender As CBFSConnect, ByVal FileName As String, ByVal DesiredAccess As UInt32, ByVal FileAttributes As UInt32, ByVal ShareMode As UInt32, ByVal FileInfo As TCBFileInfo, ByVal HandleInfo As TCBHandleInfo )

[Java]
    void ICbFsFileEvents.onCreateFile( CBFSConnect sender, String fileName, long desiredAccess, long fileAttributes, long shareMode, CBFileInfo FileInfo, CBHandleInfo HandleInfo );

Parameters

  • Sender - reference to the class that called the delegate/event handler
  • FileName - the name of the file to create
  • DesiredAccess - desired mode of access to the created file
  • FileAttributes - the attributes to be set for the newly created file
  • ShareMode - desired share mode
  • FileInfo - a structure which contains information about the file and a user-defined context common to all concurrent file create/open operations
  • HandleInfo - a structure which contains information about the particular file create/open operation and a user-defined context individual to each file create/open operation

Description

This event is fired when the OS wants to create a file or directory with given name and attributes. The directories are created with this call.
To check, what should be created (file or directory), check FileAttributes as follows (C++ / C# notation): Directory = FileAttributes & FILE_ATTRIBUTE_DIRECTORY == FILE_ATTRIBUTE_DIRECTORY;

If the file name contains semicolon (":"), this means that the request is made to create a named stream in a file. The part before the semicolon is the name of the file itself and the name after the semicolon is the name of the named stream. If you don't want to deal with named streams, don't implement the handler for OnEnumerateNamedStreams event. In this case CBFS API will tell the OS that the named streams are not supported by the file system.

DesiredAccess, ShareMode and Attributes are passed as they were specified in the call to CreateFile() Windows API function.

CBFS internally processes CreateDisposition parameter and acts accordingly. If you need to obtain the original value (in NT format, i.e. as passed in ZwCreateFile() API function), you can read CreateDisposition property of HandleInfo parameter.

The application can use FileInfo's and HandleInfo's UserContext property to store the reference to some information, identifying the file or directory (such as file/directory handle or database record ID or reference to the stream class etc). The value, set in the event handler, is later passed to all operations, related to this file, together with file/directory name and attributes.
Read more about contexts.

Note, that if CallAllOpenCloseCallbacks property is set to false (default value), then this event is fired only when the first handle to the file is opened.

If you have a local file with data (for example cached for speed), which you want CBFS to access directly instead of via callbacks / events, call RouteToFile() method from the callback / event handler.

Sometimes it can happen that OnCreateFile is fired for a file which already exists. Normally such situation will not happen, as the OS knows which files exist before creating or opening files (this information is requested via OnGetFileInfo and OnEnumerateDirectory). However, if your files come from outside, a race condition can happen and the file will exist externally but will not be known to the OS and to CBFS yet. In this case you need to decide based on your application logic - you can either truncate an existing file or report the error. ERROR_ALREADY_EXISTS is a proper error code in this situation.

Security checks

Your code is responsible for checking access rights of the process, which accesses the file system object. See Security checks topic for detailed information about how to check security.

Error handling

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

See also

CallAllOpenCloseCallbacks property     RouteToFile method     OnCleanupFile event     OnCloseFile event     OnEnumerateNamedStreams event