Discuss this help topic in CBFS Forum

OnOpenFile 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 open event.

Declaration

[Pascal]
    property OnOpenFile : TCbFsOpenFileEvent;
    TCbFsOpenFileEvent = 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 *CbFsOpenFileEvent)(void* Sender, wchar_t* FileName, unsigned long DesiredAccess, unsigned long FileAttributes, unsigned long ShareMode, CbFsFileInfo* FileInfo, CbFsHandleInfo* HandleInfo );

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

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

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

[VB.NET]
    Sub CbFsOpenFileEvent( 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.onOpenFile( CallbackFileSystem sender, String fileName, long desiredAccess, 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 open
  • DesiredAccess - desired mode of access to the created file
  • FileAttributes - additional file attributes
  • 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 open an existing file or directory with given name and attributes. The directory can be opened, for example, in order to change its attributes or to enumerate its contents.

If the file name contains semicolon (":"), this means that the request is made to open 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, FileAttributes and ShareMode parameters correspond to values passed to CreateFile() WinAPI function. FileAttributes parameter can be used to make additional processing for such attributes as FILE_FLAG_SEQUENTIAL_SCAN, FILE_FLAG_WRITE_THROUGH, FILE_FLAG_RANDOM_ACCESS, etc. For example it can be used in order to decide whether it's necessary to do some local caching of remote "backend files".

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 OnOpenFile is fired for a file which doesn't already exist. 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 are created and deleted from outside, a race condition can happen and the file will disappear but will still be known to the OS and to CBFS. In this case you need to report ERROR_FILE_NOT_FOUND error.

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