TElSFTPServer.OnOpenFile event

TElSFTPServer.OnOpenFile

This event is fired when your software has to open file.

Declaration

[C#]
event TElSFTPServerOpenFileEvent OnOpenFile;
delegate void TElSFTPServerOpenFileEvent(Object Sender, string Path, TSBSftpFileOpenModes Modes, TSBSftpFileOpenAccess Access, uint DesiredAccess, TElSftpFileAttributes Attributes, ref Object Data, ref int ErrorCode, ref string Comment);

[VB.NET]
Event OnOpenFile As TElSFTPServerOpenFileEvent
Delegate Sub TElSFTPServerOpenFileEvent(ByVal Sender As Object, ByVal Path As String, ByVal Modes As TSBSftpFileOpenModes, ByVal Access As TSBSftpFileOpenAccess, ByVal DesiredAccess As UInt32, ByVal Attributes As TElSftpFileAttributes, ByRef Data As Object, ByRef ErrorCode As Integer, ByRef Comment As String)

[Pascal]
    property OnOpenFile: TSBSFTPServerOpenFileEvent;
    TSBSFTPServerOpenFileEvent = procedure(Sender : TObject; const Path : string; Modes: TSBSftpFileOpenModes; Access : TSBSftpFileOpenAccess; DesiredAccess : Cardinal; Attributes : TElSftpFileAttributes; var Data : pointer; var ErrorCode : integer; var Comment : string) of object;

    TSBSftpFileOpenModes = set of TSBSftpFileOpenMode;
    TSBSftpFileOpenAccess = set of TSBSftpFileOpenAccessItem;

[C++]
    void get_OnOpenFile(TElSFTPServerOpenFileEvent &pMethodOutResult, void * &pDataOutResult);
    void set_OnOpenFile(TElSFTPServerOpenFileEvent pMethodValue, void * pDataValue);
    typedef void (SB_CALLBACK *TElSFTPServerOpenFileEvent)(void * _ObjectData, TObjectHandle Sender, const char * pcPath, int32_t szPath, TSBSftpFileOpenModesRaw Modes, TSBSftpFileOpenAccessRaw Access, uint32_t DesiredAccess, TElSftpFileAttributesHandle Attributes, void * (* Data), int32_t &ErrorCode, char * pcComment, int32_t &szComment);

[PHP]
    TElSFTPServerOpenFileEvent|callable|NULL get_OnOpenFile()
    void set_OnOpenFile(TElSFTPServerOpenFileEvent|callable|NULL $Value)
    callable TElSFTPServerOpenFileEvent(TObject $Sender, string $Path, integer $Modes, integer $Access, integer $DesiredAccess, TElSftpFileAttributes $Attributes, TSBPointer $Data, integer &$ErrorCode, string &$Comment)

[Java]
    TElSFTPServerOpenFileEvent getOnOpenFile();
    void setOnOpenFile(TElSFTPServerOpenFileEvent Value);
    TElSFTPServerOpenFileEvent.Callback OnOpenFile = new TElSFTPServerOpenFileEvent.Callback() {
        public void TElSFTPServerOpenFileEventCallback(TObject Sender, String Path, int Modes, int Access, int DesiredAccess, TElSftpFileAttributes Attributes, TSBObject Data, TSBInteger ErrorCode, TSBString Comment) {
            //...
        }
    }

Parameters

Path - specifies the path to a file to open
Modes - specifies the file opening mode
Access - specifies if file must be blocked for reading, writing or deleting while opened.
DesiredAccess - specifies desired file access mode
Attributes - specifies the initial attributes for the file
Data - user data that will be associated with the file to be opened
ErrorCode - the error code, see values below
Comment - server comment
pcPath - specifies the path to a file to open
szPath - the length of pcPath.
pcComment - server comment
szComment - the length of pcComment.

TSBSftpFileOpenMode values:

[.NET]	[Pascal]	[C++]	Description
fmRead = 1	fmRead	f_fmRead = 1	Open file for reading
fmWrite = 2	fmWrite	f_fmWrite = 2	Open file for writing
fmAppend = 4	fmAppend	f_fmAppend = 4	Data is always written at the end of the file
fmCreate = 8	fmCreate	f_fmCreate = 8	New file is created; if the file already exists, operation will fail
fmTruncate = 16	fmTruncate	f_fmTruncate = 16	A new file is created; if the file already exists, it is opened and truncated
fmExcl = 32	fmExcl	f_fmExcl = 32	Specifies exclusive file opening mode.In this mode only one thread is allowed to access the file at a time,and if another process will try to open the file, an exception will be raised
fmText = 64	fmText	f_fmText = 64	Indicates that the file will be opened as text andconverted to the canonical newline convention in use
fmOpenOrCreate = 128	fmOpenOrCreate	f_fmOpenOrCreate = 128	If the file exists, it will be opened.If the file does not exist, it will be created
fmAppendAtomic = 256	fmAppendAtomic	f_fmAppendAtomic = 256	Data will be always written at the end of the file,and data will be written atomically so that there is no chance thatmultiple appenders can collide and result in data being lost
fmNoFollow = 512	fmNoFollow	f_fmNoFollow = 256	If the final component of the path is a symlink, then the open will fail
fmDeleteOnClose = 1024	fmDeleteOnClose	f_fmDeleteOnClose = 1024	The file will be deleted when the last handle to it is closed.(The last handle may not be an sftp-handle)

TSBSftpFileOpenModesRaw values

[.NET][C++]	[Pascal]	[PHP]	Description
f_fmRead = 1	fmRead	fmRead = 1	...
f_fmWrite = 2	fmWrite	fmWrite = 2	...
f_fmAppend = 4	fmAppend	fmAppend = 4	...
f_sfmCreate = 8	sfmCreate	sfmCreate = 8	...
f_fmTruncate = 16	fmTruncate	fmTruncate = 16	...
f_fmExcl = 32	fmExcl	fmExcl = 32	...
f_fmText = 64	fmText	fmText = 64	...
f_fmOpenOrCreate = 128	fmOpenOrCreate	fmOpenOrCreate = 128	...
f_fmAppendAtomic = 256	fmAppendAtomic	fmAppendAtomic = 256	...
f_fmNoFollow = 512	fmNoFollow	fmNoFollow = 512	...
f_fmDeleteOnClose = 1024	fmDeleteOnClose	fmDeleteOnClose = 1024	...

TSBSftpFileOpenAccess values:

[.NET]	[Pascal]	[C++]	Description
faReadLock = 1	faReadLock	f_faReadLock = 1	No other handle has been opened for reading andno other handle will be opened for reading until the client closes the handle.However other handle can be opened for any other access but reading
faWriteLock = 2	faWriteLock	f_faWriteLock = 2	No other handle has been opened for writing or appending andno other handle will be opened for writing or appending until the client closes the handle.However other handle can be opened for any other access but writing or appending
faDeleteLock = 4	faDeleteLock	f_faDeleteLock = 4	No other handle has been opened for deleting or with delete on close flag andno other handle will be opened deleting or with delete on close flag until the client closes the handle
faBlockAdvisory = 8	faBlockAdvisory	f_faBlockAdvisory = 8	If this bit is set, the above block modes are advisory.In advisory mode, only other accesses that specify a block mode need to be consideredwhen determining whether the block access can be granted

TSBSftpFileOpenAccessRaw values

[.NET][C++]	[Pascal]	[PHP]	Description
f_faReadLock = 1	faReadLock	faReadLock = 1	...
f_faWriteLock = 2	faWriteLock	faWriteLock = 2	...
f_faDeleteLock = 4	faDeleteLock	faDeleteLock = 4	...
f_faBlockAdvisory = 8	faBlockAdvisory	faBlockAdvisory = 8	...

DesiredAccess values:

Definition	Value	Description
ACE4_READ_DATA	1 (0x0001)	Permission to read the data of the file
ACE4_LIST_DIRECTORY	1 (0x0001)	Permission to list the contents of a directory
ACE4_WRITE_DATA	2 (0x0002)	Permission to modify the file’s data
ACE4_ADD_FILE	2 (0x0002)	Permission to add a new file to a directory
ACE4_APPEND_DATA	4 (0x0004)	Permission to append data to a file
ACE4_ADD_SUBDIRECTORY	4 (0x0004)	Permission to create a subdirectory to a directory
ACE4_READ_NAMED_ATTRS	8 (0x0008)	Permission to read the named attributes of a file
ACE4_WRITE_NAMED_ATTRS	16 (0x0010)	Permission to write the named attributes of a file
ACE4_EXECUTE	32 (0x0020)	Permission to execute a file
ACE4_DELETE_CHILD	64 (0x0040)	Permission to delete a file or directory within a directory
ACE4_READ_ATTRIBUTES	128 (0x0080)	The ability to read basic attributes (non-acls) of a file
ACE4_WRITE_ATTRIBUTES	256 (0x0100)	Permission to change basic attributes (non-acls) of a file
ACE4_DELETE	65536 (0x00010000)	Permission to Delete the file
ACE4_READ_ACL	131072 (0x00020000)	Permission to Read the ACL
ACE4_WRITE_ACL	262144 (0x00040000)	Permission to Write the ACL
ACE4_WRITE_OWNER	524288 (0x00080000)	Permission to change the owner
ACE4_SYNCHRONIZE	1048576 (0x00100000)	Permission to access file locally at the server with synchronous reads and writes

Error codes values:

Definition	Value	Description
SSH_ERROR_WRONG_MODE	-1 (0xFFFFFFFF)	Attempt to call synchronous method in asynchronous mode and vice versa
SSH_ERROR_OK	0 (0x0000)	Indicates successful completion of the operation
SSH_ERROR_EOF	1 (0x0001)	indicates end-of-file condition; Read: no more data is available in the file; ReadDirectory: no more files are contained in the directory
SSH_ERROR_NO_SUCH_FILE	2 (0x0002)	A reference is made to a file which does not exist
SSH_ERROR_PERMISSION_DENIED	3 (0x0003)	the authenticated user does not have sufficient permissions to perform the operation
SSH_ERROR_FAILURE	4 (0x0004)	An error occurred for which there is no more specific error code defined
SSH_ERROR_BAD_MESSAGE	5 (0x0005)	A badly formatted packet or protocol incompatibility is detected
SSH_ERROR_NO_CONNECTION	6 (0x0006)	A pseudo-error which indicates that the client has no connection to the server
SSH_ERROR_CONNECTION_LOST	7 (0x0007)	A pseudo-error which indicates that the connection to the server has been lost
SSH_ERROR_OP_UNSUPPORTED	8 (0x0008)	An attempt was made to perform an operation which is not supported for the server
SSH_ERROR_INVALID_HANDLE	9 (0x0009)	The handle value was invalid
SSH_ERROR_NO_SUCH_PATH	10 (0x000A)	The file path does not exist or is invalid
SSH_ERROR_FILE_ALREADY_EXISTS	11 (0x000B)	The file already exists
SSH_ERROR_WRITE_PROTECT	12 (0x000C)	The file is on read only media, or the media is write protected
SSH_ERROR_NO_MEDIA	13 (0x000D)	The requested operation can not be completed because there is no media available in the drive
SSH_ERROR_NO_SPACE_ON_FILESYSTEM	14 (0x000E)	The requested operation cannot be completed because there is no free space on the filesystem
SSH_ERROR_QUOTA_EXCEEDED	15 (0x000F)	The operation cannot be completed because it would exceed the user's storage quota
SSH_ERROR_UNKNOWN_PRINCIPAL	16 (0x0010)	A principal referenced by the request (either the ‘owner’,‘group’, or ‘who’ field of an ACL), was unknown
SSH_ERROR_LOCK_CONFLICT	17 (0x0011)	The file could not be opened because it is locked by another process
SSH_ERROR_DIR_NOT_EMPTY	18 (0x0012)	The directory is not empty
SSH_ERROR_NOT_A_DIRECTORY	19 (0x0013)	The specified file is not a directory
SSH_ERROR_INVALID_FILENAME	20 (0x0014)	The filename is not valid
SSH_ERROR_LINK_LOOP	21 (0x0015)	Too many symbolic links encountered
SSH_ERROR_CANNOT_DELETE	22 (0x0016)	The file cannot be deleted. One possible reason is that the advisory READONLY attribute-bit is set
SSH_ERROR_INVALID_PARAMETER	23 (0x0017)	On of the parameters was out of range, or the parameters specified cannot be used together
SSH_ERROR_FILE_IS_A_DIRECTORY	24 (0x0018)	The specified file was a directory in a context where a directory cannot be used
SSH_ERROR_BYTE_RANGE_LOCK_CONFLICT	25 (0x0019)	A read or write operation failed because another process's mandatory byte-range lock overlaps with the request
SSH_ERROR_BYTE_RANGE_LOCK_REFUSED	26 (0x001A)	A request for a byte range lock was refused
SSH_ERROR_DELETE_PENDING	27 (0x001B)	An operation was attempted on a file for which a delete operation is pending
SSH_ERROR_FILE_CORRUPT	28 (0x001C)	The file is corrupt; an filesystem integrity check should be run
SSH_ERROR_OWNER_INVALID	29 (0x001D)	The principal specified can not be assigned as an owner of a file
SSH_ERROR_GROUP_INVALID	30 (0x001E)	The principal specified can not be assigned as the primary group of a file
SSH_ERROR_UNSUPPORTED_VERSION	100 (0x0064)	Sets of supported by client and server versions has no intersection
SSH_ERROR_INVALID_PACKET	101 (0x0065)	Invalid packet was received
SSH_ERROR_TUNNEL_ERROR	102 (0x0066)	Error is on the SSH-protocol level. The connection is closed because of SSH error
SSH_ERROR_CONNECTION_CLOSED	103 (0x0067)	Connection is closed
SSH_ERROR_UNSUPPORTED_ACTION	104 (0x0068)	…
SSH_ERROR_NOT_A_TEXT_HANDLE	105 (0x0069)	…
SSH_ERROR_CANCELLED_BY_USER	106 (0x006A)	…

Description

This event is fired when the file has to be opened.

Note, the Access parameter has meaning only for SFTPv5 and will be ignored for earlier versions.
The application can return the error code in ErrorCode parameter and textual comment in Comment parameter.

Discuss this help topic in SecureBlackbox Forum