Discuss this help topic in CBFS Forum

OnCreateFile event/delegate/callback

Filter:

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

CallbackFileSystem     See also    

Overview

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

Declaration

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

[C++ (Lib)]
    void (__stdcall *CbFsCreateFileEvent)(void* Sender, wchar_t* FileName, unsigned long DesiredAccess, unsigned long FileAttributes, unsigned long ShareMode, CbFsFileInfo* FileInfo, CbFsHandleInfo* HandleInfo );

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

[C++ (.NET)]
    public __delegate void CbFsCreateFileEvent( CallbackFileSystem^ Sender, String^ FileName, UInt32 DesiredAccess, UInt32 FileAttributes, UInt32 ShareMode, CbFsFileInfo^ FileInfo, CbFsHandleInfo^ HandleInfo );

[C#]
    public void CbFsCreateFileEvent( CallbackFileSystem Sender, string FileName, UInt32 DesiredAccess, UInt32 FileAttributes, UInt32 ShareMode, CbFsFileInfo FileInfo, CbFsHandleInfo HandleInfo );

[VB.NET]
    Sub CbFsCreateFileEvent( ByVal Sender As CallbackFileSystem, ByVal FileName As String, ByVal DesiredAccess As UInt32, ByVal FileAttributes As UInt32, ByVal ShareMode As UInt32, ByVal FileInfo As TCbFsFileInfo, ByVal HandleInfo As TCbFsHandleInfo )

[Java]
    void ICbFsFileEvents.onCreateFile( CallbackFileSystem sender, String fileName, long desiredAccess, long fileAttributes, long shareMode, CbFsFileInfo FileInfo, CbFsHandleInfo 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 Callback File System.

See also

CallAllOpenCloseCallbacks property     RouteToFile method     OnCleanupFile event     OnCloseFile event     OnEnumerateNamedStreams event    

Discuss this help topic in CBFS Forum