CkSFtp Perl Programming
Reference Documentation
CkSFtp
SFTP implementation for file transfer and remote file management over SSH.
Object Creation
$obj = new chilkat::CkSFtp();
Properties
# data is a CkByteData object (output)
get_AccumulateBuffer( data )
Contains the bytes downloaded from a remote file via the AccumulateBytes method call. Each call to AccumulateBytes appends to this buffer. To clear this buffer, call the ClearAccumulateBuffer method.
# str is a CkString object (output)
get_ClientIdentifier( str )
# newVal is a string (input)
put_ClientIdentifier( newVal )
The client-identifier string to be used when connecting to an SSH/SFTP server. Defaults to "SSH-2.0-PuTTY_Local:_Jun_27_2008_16:28:58". (This string is used to mimic PuTTY because some servers are known to disconnect from clients with unknown client identifiers.)
# str is a CkString object (output)
get_ClientIpAddress( str )
# newVal is a string (input)
put_ClientIpAddress( newVal )
The IP address to use for computers with multiple network interfaces or IP addresses.
For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.
The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124".
# Returns an integer value
get_ConnectTimeoutMs( )
# newVal is an integer (input)
put_ConnectTimeoutMs( newVal )
Maximum number of milliseconds to wait when connecting to an SSH server.
# str is a CkString object (output)
get_DebugLogFilePath( str )
# newVal is a string (input)
put_DebugLogFilePath( newVal )
Used for debugging in cases where a Chilkat method call hangs and never returns. This should generally never happen. The only causes for this are (1) a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired, (2) the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or (3) there is an internal problem (bug) in the Chilkat code that causes the hang.
This property allows one to specifiy a debug file path that will be created (or appended if it already exists) and information will be logged to it as the Chilkat methods are called. If a hang occurs, the log file may be viewed to get information about what happened.
# Returns an integer value
get_DisconnectCode( )
If the SSH/SFTP server sent a DISCONNECT message when closing the connection, this property contains the "reason code" as specified in RFC 4253:
Symbolic name reason code
------------- -----------
SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1
SSH_DISCONNECT_PROTOCOL_ERROR 2
SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3
SSH_DISCONNECT_RESERVED 4
SSH_DISCONNECT_MAC_ERROR 5
SSH_DISCONNECT_COMPRESSION_ERROR 6
SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7
SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8
SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9
SSH_DISCONNECT_CONNECTION_LOST 10
SSH_DISCONNECT_BY_APPLICATION 11
SSH_DISCONNECT_TOO_MANY_CONNECTIONS 12
SSH_DISCONNECT_AUTH_CANCELLED_BY_USER 13
SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE 14
SSH_DISCONNECT_ILLEGAL_USER_NAME 15
# str is a CkString object (output)
get_DisconnectReason( str )
If the SSH/SFTP server sent a DISCONNECT message when closing the connection, this property contains a descriptive string for the "reason code" as specified in RFC 4253.
# Returns a boolean value
get_EnableCache( )
# newVal is a boolean (input)
put_EnableCache( newVal )
Controls whether the component keeps an internal file size & attribute cache. The cache affects the following methods: GetFileSize32, GetFileSize64, GetFileSizeStr, GetFileCreateTime, GetFileLastAccess, GetFileLastModified, GetFileOwner, GetFileGroup, and GetFilePermissions.
The file attribute cache exists to minimize communications with the SFTP server. If the cache is enabled, then a request for any single attribute will cause all of the attributes to be cached. A subsequent request for a different attribute of the same file will be fulfilled from cache, eliminating the need for a message to be sent to the SFTP server.
Note: Caching only occurs when filenames are used, not handles.
# str is a CkString object (output)
get_FilenameCharset( str )
# newVal is a string (input)
put_FilenameCharset( newVal )
Automatically set during the InitializeSftp method if the server sends a filename-charset name-value extension. Otherwise, may be set directly to the name of a charset, such as "utf-8", "iso-8859-1", "windows-1252", etc. ("ansi" is also a valid choice.) Incoming filenames are interpreted as utf-8 if no FilenameCharset is set. Outgoing filenames are sent using utf-8 by default. Otherwise, incoming and outgoing filenames use the charset specified by this property.
# str is a CkString object (output)
get_ForceCipher( str )
# newVal is a string (input)
put_ForceCipher( newVal )
Set to one of the following encryption algorithms to force that cipher to be used. By default, the component will automatically choose the first cipher supported by the server in the order listed here: "aes256-cbc", "aes128-cbc", "twofish256-cbc", "twofish128-cbc", "blowfish-cbc", "3des-cbc", "arcfour128", "arcfour256". (If blowfish is chosen, the encryption strength is 128 bits.)
Important: If this is property is set and the server does NOT support then encryption algorithm, then the Connect will fail.
# Returns a boolean value
get_ForceV3( )
# newVal is a boolean (input)
put_ForceV3( newVal )
If set to 1, forces the client to choose version 3 of the SFTP protocol, even if the server supports a higher version. The default value of this property is 0.
# Returns an integer value
get_HeartbeatMs( )
# newVal is an integer (input)
put_HeartbeatMs( newVal )
This is the number of milliseconds between each AbortCheck event callback. The AbortCheck callback allows an application to abort any SFTP operation prior to completion. If HeartbeatMs is 0 (the default), no AbortCheck event callbacks will fire.
# str is a CkString object (output)
get_HostKeyFingerprint( str )
Set after connecting to an SSH/SFTP server. The format of the fingerprint looks like this: "ssh-rsa 1024 68:ff:d1:4e:6c:ff:d7:b0:d6:58:73:85:07:bc:2e:d5"
# str is a CkString object (output)
get_HttpProxyAuthMethod( str )
# newVal is a string (input)
put_HttpProxyAuthMethod( newVal )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy authentication method name. Valid choices are "LOGIN" or "NTLM".
# str is a CkString object (output)
get_HttpProxyHostname( str )
# newVal is a string (input)
put_HttpProxyHostname( newVal )
If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or IPv4 address (in dotted decimal notation).
# str is a CkString object (output)
get_HttpProxyPassword( str )
# newVal is a string (input)
put_HttpProxyPassword( newVal )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy password.
# Returns an integer value
get_HttpProxyPort( )
# newVal is an integer (input)
put_HttpProxyPort( newVal )
If an HTTP proxy is to be used, set this property to the HTTP proxy port number. (Two commonly used HTTP proxy ports are 8080 and 3128.)
# str is a CkString object (output)
get_HttpProxyUsername( str )
# newVal is a string (input)
put_HttpProxyUsername( newVal )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy login name.
# Returns an integer value
get_IdleTimeoutMs( )
# newVal is an integer (input)
put_IdleTimeoutMs( newVal )
Causes SFTP operations to fail when progress for sending or receiving data halts for more than this number of milliseconds. Setting IdleTimeoutMs = 0 allows the application to wait indefinitely. The default value of this property is 30000 (which equals 30 seconds).
# Returns an integer value
get_InitializeFailCode( )
The InitializeSftp method call opens a channel for the SFTP session. If the request to open a channel fails, this property contains a code that identifies the reason for failure. The reason codes are defined in RFC 4254 and are reproduced here:
Symbolic name reason code
------------- -----------
SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
SSH_OPEN_CONNECT_FAILED 2
SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
SSH_OPEN_RESOURCE_SHORTAGE 4
# str is a CkString object (output)
get_InitializeFailReason( str )
The InitializeSftp method call opens a channel for the SFTP session. If the request to open a channel fails, this property contains a description of the reason for failure. (It contains descriptive text matching the InitializeFailCode property.)
# Returns a boolean value
get_IsConnected( )
Returns 1 if connected to the SSH server. Note: This does not mean authentication has happened or InitializeSftp has already succeeded. It only means that the connection has been established by calling Connect.
# Returns a boolean value
get_KeepSessionLog( )
# newVal is a boolean (input)
put_KeepSessionLog( newVal )
Controls whether communications to/from the SFTP server are saved to the SessionLog property. The default value is 0. If this property is set to 1, the contents of the SessionLog property will continuously grow as SFTP activity transpires. The purpose of the KeepSessionLog / SessionLog properties is to help in debugging any future problems that may arise.
# str is a CkString object (output)
LastErrorHtml( str )
Error information in HTML format for the last method called.
# str is a CkString object (output)
LastErrorText( str )
Error information in plain-text format for the last method called.
# str is a CkString object (output)
LastErrorXml( str )
Error information in XML format for the last method called.
# Returns an integer value
get_MaxPacketSize( )
# newVal is an integer (input)
put_MaxPacketSize( newVal )
The maximum packet length to be used in the underlying SSH transport protocol. The default value is 32768. (This should generally be left unchanged.)
# Returns a boolean value
get_PasswordChangeRequested( )
Set by the AuthenticatePw and AuthenticatePwPk methods. If the authenticate method returns a failed status, and this property is set to 1, then it indicates the server requested a password change. In this case, re-call the authenticate method, but provide both the old and new passwords in the following format, where vertical bar characters encapsulate the old and new passwords:
|oldPassword|newPassword|
# Returns a boolean value
get_PreserveDate( )
# newVal is a boolean (input)
put_PreserveDate( newVal )
If 1, then the file last-modified and create date/time will be preserved for downloaded files. The default value is 0.
# Returns an integer value
get_ProtocolVersion( )
The negotiated SFTP protocol version, which should be a value between 3 and 6 inclusive. When the InitializeSftp method is called, the Chilkat SFTP client sends it's highest supported protocol version to the server, and the server sends it's SFTP protocol version in response. The negotiated protocol (i.e. the protocol version used for the session) is the lower of the two numbers. If the SFTP server's protocol version is lower than 6, some file date/attributes are not supported because they are not supported by the earlier protocol version. These exceptions are noted throughout the reference documentation.
# str is a CkString object (output)
get_SessionLog( str )
Contains a log of the messages sent to/from the SFTP server. To enable session logging, set the KeepSessionLog property = 1. Note: This property is not a filename -- it is a string property that contains the session log data.
# str is a CkString object (output)
get_SocksHostname( str )
# newVal is a string (input)
put_SocksHostname( newVal )
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).
# str is a CkString object (output)
get_SocksPassword( str )
# newVal is a string (input)
put_SocksPassword( newVal )
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.
# Returns an integer value
get_SocksPort( )
# newVal is an integer (input)
put_SocksPort( newVal )
The SOCKS4/SOCKS5 proxy port. The default value is 1080.
This property only applies if a SOCKS proxy is used (if the SocksVersion property is set to 4 or 5).
# str is a CkString object (output)
get_SocksUsername( str )
# newVal is a string (input)
put_SocksUsername( newVal )
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).
# Returns an integer value
get_SocksVersion( )
# newVal is an integer (input)
put_SocksVersion( newVal )
SocksVersion
May be set to one of the following integer values:
0 - No SOCKS proxy is used. This is the default.
4 - Connect via a SOCKS4 proxy.
5 - Connect via a SOCKS5 proxy.
# Returns a boolean value
get_TcpNoDelay( )
# newVal is a boolean (input)
put_TcpNoDelay( newVal )
This property controls the use of the internal TCP_NODELAY socket option (which disables the Nagle algorithm). The default value of this property is 0. Setting this value to 1 disables the delay of sending successive small packets on the network.
# Returns a boolean value
get_UtcMode( )
# newVal is a boolean (input)
put_UtcMode( newVal )
If 1, then date/times are returned as UTC times. If 0 (the default) then date/times are returned as local times.
# Returns a boolean value
get_Utf8( )
# b is a boolean (input)
put_Utf8( b )
To be documented soon...
# Returns a boolean value
get_VerboseLogging( )
# newVal is a boolean (input)
put_VerboseLogging( newVal )
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0.
# str is a CkString object (output)
get_Version( str )
The version of the SFTP component, such as "2.3.0".
Methods
# handle is a string (input)
# maxBytes is an integer (input)
# Returns an integer value
AccumulateBytes( handle, maxBytes )
Downloads bytes from an open file and appends them to the AccumulateBuffer. The handle is a file handle returned by the OpenFile method. The maxBytes is the maximum number of bytes to read. If the end-of-file is reached prior to reading the number of requested bytes, then fewer bytes may be returned.
Returns the number of bytes downloaded and appended to AccumulateBuffer. Returns -1 on error.
# n1 is a string (input)
# n2 is a string (input)
# outStr is a CkString object (output)
Add64( n1, n2, outStr )
Convenience method for 64-bit addition. Allows for two 64-bit integers to be passed as decimal strings and returns the sum in a decimal sting. Returns 1 for success, 0 for failure.
# username is a string (input)
# Returns a boolean value
AuthenticatePk( username, privateKey )
Authenticates with the SSH server using public-key authentication. The corresponding public key must have been installed on the SSH server for the username. Authentication will succeed if the matching privateKey is provided.
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com. Returns 1 for success, 0 for failure.
# login is a string (input)
# password is a string (input)
# Returns a boolean value
AuthenticatePw( login, password )
Authenticates with the SSH server using a login and password.
An SFTP session always begins by first calling Connect to connect to the SSH server, then calling either AuthenticatePw or AuthenticatePk to login, and finally calling InitializeSftp.
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com.
Note: To learn about how to handle password change requests, see the PasswordChangeRequested property (above). Returns 1 for success, 0 for failure.
# username is a string (input)
# password is a string (input)
# Returns a boolean value
AuthenticatePwPk( username, password, privateKey )
Authentication for SSH servers that require both a password and private key. (Most SSH servers are configured to require one or the other, but not both.)
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com. Returns 1 for success, 0 for failure.
ClearAccumulateBuffer( )
Clears the contents of the AccumulateBuffer property.
ClearCache( )
Clears the internal file attribute cache. (Please refer to the EnableCache property for more information about the file attribute cache.)
ClearSessionLog( )
Clears the contents of the SessionLog property.
# handle is a string (input)
# Returns a boolean value
CloseHandle( handle )
Closes a file on the SSH/SFTP server. handle is a file handle returned from a previous call to OpenFile. Returns 1 for success, 0 for failure.
# domainName is a string (input)
# port is an integer (input)
# Returns a boolean value
Connect( domainName, port )
Connects to an SSH/SFTP server. The domainName may be a domain name or an IP address (example: 192.168.1.10). Both IPv4 and IPv6 addresses are supported. The port is typically 22, which is the standard port for SSH servers.
An SFTP session always begins by first calling Connect to connect to the SSH server, then calling either AuthenticatePw or AuthenticatePk to login, and finally calling InitializeSftp.
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com. Returns 1 for success, 0 for failure.
# localFilename is a string (input)
# remoteFilename is a string (input)
# isHandle is a boolean (input)
# Returns a boolean value
CopyFileAttr( localFilename, remoteFilename, isHandle )
Sets the date/time and other attributes of a remote file to be equal to that of a local file.
The attributes copied depend on the SFTP version of the server:
SFTP v3 (and below)
Last-Modified Date/Time
Last-Access Date/Time
SFTP v4, v5
Last-Modified Date/Time
Last-Access Date/Time
Create Date/Time
SFTP v6 (and above)
Last-Modified Date/Time
Last-Access Date/Time
Create Date/Time
Read-Only Flag
Hidden Flag
Archive Flag
Compressed Flag
Encrypted Flag
Notes:
(1) The Last-Access date/time may or may not be set. Chilkat has found that the Last-Access time is set to the current date/time, which is probably a result of the operating system setting it based on when the SFTP server is touching the file.
(2) At the time of this writing, it is unknown whether the compressed/encryption settings for a local file are transferred to the remote file. For example, does the remote file become compressed and/or encrypted just by setting the flags? It may depend on the SFTP server and/or the remote filesystem.
(3) Dates/times are sent in GMT. SFTP servers should convert GMT times to local time zones.Returns 1 for success, 0 for failure.
# path is a string (input)
# Returns a boolean value
CreateDir( path )
Creates a directory on the SFTP server. Returns 1 for success, 0 for failure.
Disconnect( )
Disconnects from the SSH server.
# handle is a string (input)
# toFilename is a string (input)
# Returns a boolean value
DownloadFile( handle, toFilename )
Downloads a file from the SSH server to the local filesystem. There are no limitations on file size and the data is streamed from SSH server to the local file. handle is a file handle returned by a previous call to OpenFile. Returns 1 for success, 0 for failure.
# remoteFilePath is a string (input)
# localFilePath is a string (input)
# Returns a boolean value
DownloadFileByName( remoteFilePath, localFilePath )
Simplified method for downloading files. Returns 1 for success, 0 for failure. Understanding SFTP Absolute FilePaths
# handle is a string (input)
# Returns a boolean value
Eof( handle )
Returns 1 if the last read operation for a handle reached the end of file. Otherwise returns 0.
If an invalid handle is passed, a value of 1 is returned.
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# sysTime is a SYSTEMTIME object (output)
# Returns a boolean value
GetFileCreateTime( filenameOrHandle, bFollowLinks, bIsHandle, sysTime )
Returns the create date/time for a file. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server.
Note: Servers running the SFTP v3 protocol or lower do not have the ability to return a file's creation date/time. More information about using SYSTEMTIME in Perl
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# outStr is a CkString object (output)
# Returns a boolean value
GetFileGroup( filenameOrHandle, bFollowLinks, bIsHandle, outStr )
Returns the group of a file. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server.
Note: Servers running the SFTP v3 protocol or lower do not have the ability to return a file's group name. Instead, the decimal GID of the file is returned. Returns 1 for success, 0 for failure.
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# sysTime is a SYSTEMTIME object (output)
# Returns a boolean value
GetFileLastAccess( filenameOrHandle, bFollowLinks, bIsHandle, sysTime )
Returns the last-access date/time for a file. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server. More information about using SYSTEMTIME in Perl
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# sysTime is a SYSTEMTIME object (output)
# Returns a boolean value
GetFileLastModified( filenameOrHandle, bFollowLinks, bIsHandle, sysTime )
Returns the last-modified date/time for a file. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server. More information about using SYSTEMTIME in Perl
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# outStr is a CkString object (output)
# Returns a boolean value
GetFileOwner( filenameOrHandle, bFollowLinks, bIsHandle, outStr )
Returns the owner of a file. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server.
Note: Servers running the SFTP v3 protocol or lower do not have the ability to return a file's owner name. Instead, the decimal UID of the file is returned. Returns 1 for success, 0 for failure.
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# Returns an integer value
GetFilePermissions( filenameOrHandle, bFollowLinks, bIsHandle )
Returns the access permisssions flags of a file. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server.
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# Returns an integer value
GetFileSize32( filenameOrHandle, bFollowLinks, bIsHandle )
Returns the size in bytes of a file on the SSH server. If the file size exceeds what can be represented in 32-bits, a value of -1 is returned. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server.
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# outStr is a CkString object (output)
# Returns a boolean value
GetFileSizeStr( filenameOrHandle, bFollowLinks, bIsHandle, outStr )
Returns the size in bytes (in decimal string form) of a file on the SSH server. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server.
Note: This method exists for environments that do not have 64-bit integer support. The Add64 method is provided for 64-bit addition, and other methods such as ReadFileBytes64s allow for 64-bit values to be passed as strings. Returns 1 for success, 0 for failure.
# Returns a boolean value
InitializeSftp( )
Intializes the SFTP subsystem. This should be called after connecting and authenticating. An SFTP session always begins by first calling Connect to connect to the SSH server, then calling either AuthenticatePw or AuthenticatePk to login, and finally calling InitializeSftp.
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com.
If this method fails, the reason may be present in the InitializeFailCode and InitializeFailReason properties (assuming the failure occurred when trying to open the SFTP session channel). Returns 1 for success, 0 for failure. Error Explained: Received FAILURE response to subsystem request.
# handle is a string (input)
# Returns a boolean value
LastReadFailed( handle )
Returns 1 if the last read on the specified handle failed. Otherwise returns 0.
# handle is a string (input)
# Returns an integer value
LastReadNumBytes( handle )
Returns the number of bytes received by the last read on a specified channel.
# path is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
OpenDir( path, outStr )
Opens a directory for reading. To get a directory listing, first open the directory by calling this method, then call ReadDir to read the directory, and finally call CloseHandle to close the directory.
The SFTP protocol represents file names as strings. File names are
assumed to use the slash ('/') character as a directory separator.
File names starting with a slash are "absolute", and are relative to
the root of the file system. Names starting with any other character
are relative to the user's default directory (home directory). Note
that identifying the user is assumed to take place outside of this
protocol.
Servers SHOULD interpret a path name component ".." as
referring to the parent directory, and "." as referring to the
current directory.
An empty path name is valid, and it refers to the user's default
directory (usually the user's home directory). Returns 1 for success, 0 for failure. Understanding SFTP Absolute FilePaths
# remotePath is a string (input)
# access is a string (input)
# createDisposition is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
OpenFile( remotePath, access, createDisposition, outStr )
Opens or creates a file on the remote system. Returns a handle which may be passed to methods for reading and/or writing the file.
access should be one of the following strings: "readOnly", "writeOnly", or "readWrite". createDisposition is a comma-separated list of keywords to provide more control over how the file is opened or created. One of the following keywords must be present: "createNew", "createTruncate", "openExisting", "openOrCreate", or "truncateExisting". All other keywords are optional. The list of keywords and their meanings are shown here:
createNew
A new file is created; if the file already exists the method fails.
createTruncate
A new file is created; if the file already exists, it is opened and truncated.
openExisting
An existing file is opened. If the file does not exist the method fails.
openOrCreate
If the file exists, it is opened. If the file does not exist,
it is created.
truncateExisting
An existing file is opened and truncated. If the file does not
exist the method fails.
appendData
Data is always written at the end of the file.
Data is not required to be appended atomically. This means that
if multiple writers attempt to append data simultaneously, data
from the first may be lost.
appendDataAtomic
Data is always written at the end of the file.
Data MUST be written atomically so that there is no chance that
multiple appenders can collide and result in data being lost.
textMode
Indicates that the server should treat the file as text and
convert it to the canonical newline convention in use.
When a file is opened with this flag, data is always appended to the end of the file.
Servers MUST process multiple, parallel reads and writes correctly
in this mode.
blockRead
The server MUST guarantee that no other handle has been opened
with read access, and that no other handle will be
opened with read access until the client closes the
handle. (This MUST apply both to other clients and to other
processes on the server.) In a nutshell, this opens the file
in non-sharing mode.
blockWrite
The server MUST guarantee that no other handle has been opened
with write access, and that no other
handle will be opened with write
access until the client closes the handle. (This MUST apply both
to other clients and to other processes on the server.)
In a nutshell, this opens the file
in non-sharing mode.
blockDelete
The server MUST guarantee that the
file itself is not deleted in any other way until the client
closes the handle. No other client or process is allowed to open the file with delete access.
blockAdvisory
If set, the above "block" modes are advisory. In
advisory mode, only other accesses that specify a "block" mode need
be considered when determining whether the "block" can be granted,
and the server need not prevent I/O operations that violate the
block mode.
The server MAY perform mandatory locking even if the
blockAdvisory flag is set.
noFollow
If the final component of the path is a symlink, then the open
MUST fail.
deleteOnClose
The file should be deleted when the last handle to it is closed.
(The last handle may not be an sftp-handle.) This MAY be emulated
by a server if the OS doesn't support it by deleting the file when
this handle is closed.
accessAuditAlarmInfo
The client wishes the server to enable any privileges or extra
capabilities that the user may have in to allow the reading and
writing of AUDIT or ALARM access control entries.
accessBackup
The client wishes the server to enable any privileges or extra
capabilities that the user may have in order to bypass normal
access checks for the purpose of backing up or restoring files.
backupStream
This flag indicates that the client wishes to read or write a
backup stream. A backup stream is a system dependent structured
data stream that encodes all the information that must be
preserved in order to restore the file from backup medium.
The only well defined use for backup stream data read in this
fashion is to write it to the same server to a file also opened
using the backupStream flag. However, if the server has a well
defined backup stream format, there may be other uses for this
data outside the scope of this protocol.
IMPORANT: If remotePath is a filename with no path, such as "test.txt", and the server responds with a "Folder not found" error, then try prepending "./" to the remotePath. For example, instead of passing "test.txt", try "./test.txt". Returns 1 for success, 0 for failure. Understanding SFTP Absolute FilePaths SFTP Where Did My Upload Go?
# handle is a string (input)
# Returns a CkSFtpDir object
ReadDir( handle )
Reads the contents of a directory and returns the directory listing (as an object). The handle returned by OpenDir should be passed to this method.
# handle is a string (input)
# numBytes is an integer (input)
# outBytes is a CkByteData object (output)
# Returns a boolean value
ReadFileBytes( handle, numBytes, outBytes )
Reads file data from a remote file on the SSH server. The handle is a file handle returned by the OpenFile method. The numBytes is the maximum number of bytes to read. If the end-of-file is reached prior to reading the number of requested bytes, then fewer bytes may be returned.
To read an entire file, one may call ReadFileBytes repeatedly until Eof(handle) returns 1.
# handle is a string (input)
# offset is an integer (input)
# numBytes is an integer (input)
# outBytes is a CkByteData object (output)
# Returns a boolean value
ReadFileBytes32( handle, offset, numBytes, outBytes )
Reads file data from a remote file on the SSH server. The handle is a file handle returned by the OpenFile method. The offset is measured in bytes relative to the beginning of the file. (64-bit offsets are supported via the ReadFileBytes64 and ReadFileBytes64s methods.) The offset is ignored if the "textMode" flag was specified during the OpenFile. The numBytes is the maximum number of bytes to read. If the end-of-file is reached prior to reading the number of requested bytes, then fewer bytes may be returned.
# handle is a string (input)
# offset is a string (input)
# numBytes is an integer (input)
# outBytes is a CkByteData object (output)
# Returns a boolean value
ReadFileBytes64s( handle, offset, numBytes, outBytes )
(This method exists for systems that do not support 64-bit integers. The 64-bit integer offset is passed as a decimal string instead.)
Reads file data from a remote file on the SSH server. The handle is a file handle returned by the OpenFile method. The offset is a 64-bit integer represented as a decimal string. It represents an offset in bytes from the beginning of the file. The offset is ignored if the "textMode" flag was specified during the OpenFile. The numBytes is the maximum number of bytes to read. If the end-of-file is reached prior to reading the number of requested bytes, then fewer bytes may be returned.
# handle is a string (input)
# numBytes is an integer (input)
# charset is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
ReadFileText( handle, numBytes, charset, outStr )
This method is identical to ReadFileBytes except for one thing: The bytes are interpreted according to the specified charset (i.e. the character encoding) and returned as a string. A list of supported charset values may be found on this page: Supported Charsets.
Note: If the charset is an encoding where a single character might be represented in multiple bytes (such as utf-8, Shift_JIS, etc.) then there is a risk that the very last character may be partially read. This is because the method specifies the number of bytes to read, not the number of characters. This is never a problem with character encodings that use a single byte per character, such as all of the iso-8859-* encodings, or the Windows-* encodings.
To read an entire file, one may call ReadFileText repeatedly until Eof(handle) returns 1. Returns 1 for success, 0 for failure.
# handle is a string (input)
# offset is an integer (input)
# numBytes is an integer (input)
# charset is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
ReadFileText32( handle, offset, numBytes, charset, outStr )
This method is identical to ReadFileBytes32 except for one thing: The bytes are interpreted according to the specified charset (i.e. the character encoding) and returned as a string. A list of supported charset values may be found on this page: Supported Charsets.
Note: If the charset is an encoding where a single character might be represented in multiple bytes (such as utf-8, Shift_JIS, etc.) then there is a risk that the very last character may be partially read. This is because the method specifies the number of bytes to read, not the number of characters. This is never a problem with character encodings that use a single byte per character, such as all of the iso-8859-* encodings, or the Windows-* encodings. Returns 1 for success, 0 for failure.
# handle is a string (input)
# offset is a string (input)
# numBytes is an integer (input)
# charset is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
ReadFileText64s( handle, offset, numBytes, charset, outStr )
This method is identical to ReadFileBytes64s except for one thing: The bytes are interpreted according to the specified charset (i.e. the character encoding) and returned as a string. A list of supported charset values may be found on this page: Supported Charsets.
Note: If the charset is an encoding where a single character might be represented in multiple bytes (such as utf-8, Shift_JIS, etc.) then there is a risk that the very last character may be partially read. This is because the method specifies the number of bytes to read, not the number of characters. This is never a problem with character encodings that use a single byte per character, such as all of the iso-8859-* encodings, or the Windows-* encodings. Returns 1 for success, 0 for failure.
# originalPath is a string (input)
# composePath is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
RealPath( originalPath, composePath, outStr )
This method can be used to have the server
canonicalize any given path name to an absolute path. This is useful
for converting path names containing ".." components or relative
pathnames without a leading slash into absolute paths. The absolute path is returned by this method.
originalPath is the first component of the path which the client wishes resolved
into a absolute canonical path. This may be the entire path.
The composePath is a path which the client wishes the server to compose with the
original path to form the new path. This field is optional and may be set to a zero-length string.
The server will take the originalPath and apply the composePath
as a modification to it. composePath may be relative to originalPath or may be an absolute path, in which case originalPath will
be discarded. The composePath may be zero length.
Note: Servers running SFTP v4 and below do not support composePath. Returns 1 for success, 0 for failure.
# path is a string (input)
# Returns a boolean value
RemoveDir( path )
Deletes a directory on the remote server. Most (if not all) SFTP servers require that the directorybe empty of files before it may be deleted. Returns 1 for success, 0 for failure.
# filename is a string (input)
# Returns a boolean value
RemoveFile( filename )
Deletes a file on the SFTP server. Returns 1 for success, 0 for failure. Understanding SFTP Absolute FilePaths
# oldPath is a string (input)
# newPath is a string (input)
# Returns a boolean value
RenameFileOrDir( oldPath, newPath )
Renames a file or directory on the SFTP server. Returns 1 for success, 0 for failure.
# remoteFilePath is a string (input)
# localFilePath is a string (input)
# Returns a boolean value
ResumeDownloadFileByName( remoteFilePath, localFilePath )
Resumes an SFTP download. The size of the localFilePath is checked and the download begins at the appropriate position in the remoteFilePath. If localFilePath is empty or non-existent, then this method is identical to DownloadFileByName. If the localFilePath is already fully downloaded, then no additional data is downloaded and the method will return 1. Returns 1 for success, 0 for failure. SFTP Resume Download Example
# remoteFilePath is a string (input)
# localFilePath is a string (input)
# Returns a boolean value
ResumeUploadFileByName( remoteFilePath, localFilePath )
Resumes a file upload to the SFTP/SSH server. The size of the remoteFilePath is first checked to determine the starting offset for the upload. If remoteFilePath is empty or does not exist, this method is equivalent to UploadFileByName. If remoteFilePath is already fully uploaded (i.e. it's size is equal to localFilePath), then no additional bytes are uploaded and 1 is returned. Returns 1 for success, 0 for failure. SFTP Resume Upload Example
# filename is a string (input)
# Returns a boolean value
SaveLastError( filename )
Saves the last error information to an XML formatted file.
# pathOrHandle is a string (input)
# isHandle is a boolean (input)
# createDateTime is a SYSTEMTIME object (output)
# Returns a boolean value
SetCreateTime( pathOrHandle, isHandle, createDateTime )
Sets the create date/time for a file on the server. The pathOrHandle may be a filepath or the handle of a currently open file. isHandle should be set to 1 if the pathOrHandle is a handle, otherwise set isHandle to 0.
Note: Servers running version 3 or lower of the SFTP protocol do not support setting the create date/time. Returns 1 for success, 0 for failure.
# pathOrHandle is a string (input)
# isHandle is a boolean (input)
# accessDateTime is a SYSTEMTIME object (output)
# Returns a boolean value
SetLastAccessTime( pathOrHandle, isHandle, accessDateTime )
Sets the last-access date/time for a file on the server. The pathOrHandle may be a filepath or the handle of a currently open file. isHandle should be set to 1 if the pathOrHandle is a handle, otherwise set isHandle to 0. Returns 1 for success, 0 for failure.
# pathOrHandle is a string (input)
# isHandle is a boolean (input)
# modifiedDateTime is a SYSTEMTIME object (output)
# Returns a boolean value
SetLastModifiedTime( pathOrHandle, isHandle, modifiedDateTime )
Sets the last-modified date/time for a file on the server. The pathOrHandle may be a filepath or the handle of a currently open file. isHandle should be set to 1 if the pathOrHandle is a handle, otherwise set isHandle to 0. Returns 1 for success, 0 for failure.
# pathOrHandle is a string (input)
# isHandle is a boolean (input)
# owner is a string (input)
# group is a string (input)
# Returns a boolean value
SetOwnerAndGroup( pathOrHandle, isHandle, owner, group )
Sets the owner and group for a file on the server. The pathOrHandle may be a filepath or the handle of a currently open file. isHandle should be set to 1 if the pathOrHandle is a handle, otherwise set isHandle to 0.
Note: Servers running version 3 or lower of the SFTP protocol do not support setting the owner and group. Returns 1 for success, 0 for failure.
# pathOrHandle is a string (input)
# isHandle is a boolean (input)
# permissions is an integer (input)
# Returns a boolean value
SetPermissions( pathOrHandle, isHandle, permissions )
Sets the permissions for a file on the server. The pathOrHandle may be a filepath or the handle of a currently open file. isHandle should be set to 1 if the pathOrHandle is a handle, otherwise set isHandle to 0. Returns 1 for success, 0 for failure.
# unlockCode is a string (input)
# Returns a boolean value
UnlockComponent( unlockCode )
Unlocks the component. This must be called once prior to calling any other method. A fully-functional 30-day trial is automatically started when an arbitrary string is passed to this method. For example, passing "Hello", or "abc123" will unlock the component for the 1st thirty days after the initial install.
A permanent unlock code for SFTP should contain the substring "SSH" because SFTP is the Secure File Transfer protocol over SSH. It is a sub-system of the SSH protocol. It is not the FTP protocol. If the Chilkat FTP2 component/library should be used for the FTP protocol. Returns 1 for success, 0 for failure. Diagnosing UnlockComponent Problems UnlockComponent LastErrorText shows exact string passed to it. Verify UnlockComponent Success w/ Permanent Unlock Code LastErrorText Standard Information How UnlockComponent Works
# handle is a string (input)
# fromFilename is a string (input)
# Returns a boolean value
UploadFile( handle, fromFilename )
Uploads a file from the local filesystem to the SFTP server. handle is a handle of a currently open file (obtained by calling the OpenFile method). Returns 1 for success, 0 for failure.
# remoteFilePath is a string (input)
# localFilePath is a string (input)
# Returns a boolean value
UploadFileByName( remoteFilePath, localFilePath )
Simplified method for uploading a file to the SFTP/SSH server. Returns 1 for success, 0 for failure. SFTP Simplified Upload Example
# handle is a string (input)
# byteData is a CkByteData object (output)
# Returns a boolean value
WriteFileBytes( handle, byteData )
Appends byte data to an open file. The handle is a file handle returned by the OpenFile method. Returns 1 for success, 0 for failure.
# handle is a string (input)
# offset is an integer (input)
# data is a CkByteData object (output)
# Returns a boolean value
WriteFileBytes32( handle, offset, data )
Writes data to an open file at a specific offset from the beginning of the file. The handle is a file handle returned by the OpenFile method. The offset is an offset from the beginning of the file. Returns 1 for success, 0 for failure.
# handle is a string (input)
# offset64 is a string (input)
# data is a CkByteData object (output)
# Returns a boolean value
WriteFileBytes64s( handle, offset64, data )
Writes data to an open file at a specific offset from the beginning of the file. The handle is a file handle returned by the OpenFile method. The offset64 is an offset (in decimal string format) from the beginning of the file. Returns 1 for success, 0 for failure.
# handle is a string (input)
# charset is a string (input)
# textData is a string (input)
# Returns a boolean value
WriteFileText( handle, charset, textData )
Appends character data to an open file. The handle is a file handle returned by the OpenFile method. charset is a character encoding and is typically set to values such as "ansi", "utf-8", "windows-1252", etc.
A list of supported character encodings is found on this page: Supported Charsets.
Note: It is necessary to specify the character encoding because in many programming languages, strings are represented as Unicode (2 bytes/char) and in most cases one does not wish to write Unicode chars to a text file (although it is possible by setting charset = "Unicode"). Returns 1 for success, 0 for failure.
# handle is a string (input)
# offset32 is an integer (input)
# charset is a string (input)
# textData is a string (input)
# Returns a boolean value
WriteFileText32( handle, offset32, charset, textData )
Writes character data to an open file at a specific offset from the beginning of the file. The handle is a file handle returned by the OpenFile method. charset is a character encoding and is typically set to values such as "ansi", "utf-8", "windows-1252", etc.
A list of supported character encodings is found on this page: Supported Charsets. Returns 1 for success, 0 for failure.
# handle is a string (input)
# offset64 is a string (input)
# charset is a string (input)
# textData is a string (input)
# Returns a boolean value
WriteFileText64s( handle, offset64, charset, textData )
Writes character data to an open file at a specific offset from the beginning of the file. The handle is a file handle returned by the OpenFile method. The offset64 is an offset (in decimal string format) from the beginning of the file. charset is a character encoding and is typically set to values such as "ansi", "utf-8", "windows-1252", etc.
A list of supported character encodings is found on this page: Supported Charsets. Returns 1 for success, 0 for failure.
# n1 is a string (input)
# n2 is a string (input)
# Returns a string
add64( n1, n2 )
Convenience method for 64-bit addition. Allows for two 64-bit integers to be passed as decimal strings and returns the sum in a decimal sting. Returns a null on failure
# Returns a string
clientIdentifier( )
The client-identifier string to be used when connecting to an SSH/SFTP server. Defaults to "SSH-2.0-PuTTY_Local:_Jun_27_2008_16:28:58". (This string is used to mimic PuTTY because some servers are known to disconnect from clients with unknown client identifiers.) Returns a null on failure
# Returns a string
clientIpAddress( )
The IP address to use for computers with multiple network interfaces or IP addresses.
For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.
The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124". Returns a null on failure
# Returns a string
debugLogFilePath( )
Used for debugging in cases where a Chilkat method call hangs and never returns. This should generally never happen. The only causes for this are (1) a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired, (2) the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or (3) there is an internal problem (bug) in the Chilkat code that causes the hang.
This property allows one to specifiy a debug file path that will be created (or appended if it already exists) and information will be logged to it as the Chilkat methods are called. If a hang occurs, the log file may be viewed to get information about what happened. Returns a null on failure
# Returns a string
disconnectReason( )
If the SSH/SFTP server sent a DISCONNECT message when closing the connection, this property contains a descriptive string for the "reason code" as specified in RFC 4253. Returns a null on failure
# Returns a string
filenameCharset( )
Automatically set during the InitializeSftp method if the server sends a filename-charset name-value extension. Otherwise, may be set directly to the name of a charset, such as "utf-8", "iso-8859-1", "windows-1252", etc. ("ansi" is also a valid choice.) Incoming filenames are interpreted as utf-8 if no FilenameCharset is set. Outgoing filenames are sent using utf-8 by default. Otherwise, incoming and outgoing filenames use the charset specified by this property. Returns a null on failure
# Returns a string
forceCipher( )
Set to one of the following encryption algorithms to force that cipher to be used. By default, the component will automatically choose the first cipher supported by the server in the order listed here: "aes256-cbc", "aes128-cbc", "twofish256-cbc", "twofish128-cbc", "blowfish-cbc", "3des-cbc", "arcfour128", "arcfour256". (If blowfish is chosen, the encryption strength is 128 bits.)
Important: If this is property is set and the server does NOT support then encryption algorithm, then the Connect will fail. Returns a null on failure
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# Returns a string
getFileGroup( filenameOrHandle, bFollowLinks, bIsHandle )
Returns the group of a file. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server.
Note: Servers running the SFTP v3 protocol or lower do not have the ability to return a file's group name. Instead, the decimal GID of the file is returned. Returns a null on failure
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# Returns a string
getFileOwner( filenameOrHandle, bFollowLinks, bIsHandle )
Returns the owner of a file. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server.
Note: Servers running the SFTP v3 protocol or lower do not have the ability to return a file's owner name. Instead, the decimal UID of the file is returned. Returns a null on failure
# filenameOrHandle is a string (input)
# bFollowLinks is a boolean (input)
# bIsHandle is a boolean (input)
# Returns a string
getFileSizeStr( filenameOrHandle, bFollowLinks, bIsHandle )
Returns the size in bytes (in decimal string form) of a file on the SSH server. filenameOrHandle may be a remote filepath or an open handle string as returned by OpenFile. If filenameOrHandle is a handle, then bIsHandle must be set to 1, otherwise it should be 0. If bFollowLinks is 1, then symbolic links will be followed on the server.
Note: This method exists for environments that do not have 64-bit integer support. The Add64 method is provided for 64-bit addition, and other methods such as ReadFileBytes64s allow for 64-bit values to be passed as strings. Returns a null on failure
# Returns a string
hostKeyFingerprint( )
Set after connecting to an SSH/SFTP server. The format of the fingerprint looks like this: "ssh-rsa 1024 68:ff:d1:4e:6c:ff:d7:b0:d6:58:73:85:07:bc:2e:d5" Returns a null on failure
# Returns a string
httpProxyAuthMethod( )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy authentication method name. Valid choices are "LOGIN" or "NTLM". Returns a null on failure
# Returns a string
httpProxyHostname( )
If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or IPv4 address (in dotted decimal notation). Returns a null on failure
# Returns a string
httpProxyPassword( )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy password. Returns a null on failure
# Returns a string
httpProxyUsername( )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy login name. Returns a null on failure
# Returns a string
initializeFailReason( )
The InitializeSftp method call opens a channel for the SFTP session. If the request to open a channel fails, this property contains a description of the reason for failure. (It contains descriptive text matching the InitializeFailCode property.) Returns a null on failure
# Returns a string
lastErrorHtml( )
Error information in HTML format for the last method called.Returns a null on failure
# Returns a string
lastErrorText( )
Error information in plain-text format for the last method called.Returns a null on failure
# Returns a string
lastErrorXml( )
Error information in XML format for the last method called.Returns a null on failure
# path is a string (input)
# Returns a string
openDir( path )
Opens a directory for reading. To get a directory listing, first open the directory by calling this method, then call ReadDir to read the directory, and finally call CloseHandle to close the directory.
The SFTP protocol represents file names as strings. File names are
assumed to use the slash ('/') character as a directory separator.
File names starting with a slash are "absolute", and are relative to
the root of the file system. Names starting with any other character
are relative to the user's default directory (home directory). Note
that identifying the user is assumed to take place outside of this
protocol.
Servers SHOULD interpret a path name component ".." as
referring to the parent directory, and "." as referring to the
current directory.
An empty path name is valid, and it refers to the user's default
directory (usually the user's home directory). Returns a null on failure Understanding SFTP Absolute FilePaths
# remotePath is a string (input)
# access is a string (input)
# createDisposition is a string (input)
# Returns a string
openFile( remotePath, access, createDisposition )
Opens or creates a file on the remote system. Returns a handle which may be passed to methods for reading and/or writing the file.
access should be one of the following strings: "readOnly", "writeOnly", or "readWrite". createDisposition is a comma-separated list of keywords to provide more control over how the file is opened or created. One of the following keywords must be present: "createNew", "createTruncate", "openExisting", "openOrCreate", or "truncateExisting". All other keywords are optional. The list of keywords and their meanings are shown here:
createNew
A new file is created; if the file already exists the method fails.
createTruncate
A new file is created; if the file already exists, it is opened and truncated.
openExisting
An existing file is opened. If the file does not exist the method fails.
openOrCreate
If the file exists, it is opened. If the file does not exist,
it is created.
truncateExisting
An existing file is opened and truncated. If the file does not
exist the method fails.
appendData
Data is always written at the end of the file.
Data is not required to be appended atomically. This means that
if multiple writers attempt to append data simultaneously, data
from the first may be lost.
appendDataAtomic
Data is always written at the end of the file.
Data MUST be written atomically so that there is no chance that
multiple appenders can collide and result in data being lost.
textMode
Indicates that the server should treat the file as text and
convert it to the canonical newline convention in use.
When a file is opened with this flag, data is always appended to the end of the file.
Servers MUST process multiple, parallel reads and writes correctly
in this mode.
blockRead
The server MUST guarantee that no other handle has been opened
with read access, and that no other handle will be
opened with read access until the client closes the
handle. (This MUST apply both to other clients and to other
processes on the server.) In a nutshell, this opens the file
in non-sharing mode.
blockWrite
The server MUST guarantee that no other handle has been opened
with write access, and that no other
handle will be opened with write
access until the client closes the handle. (This MUST apply both
to other clients and to other processes on the server.)
In a nutshell, this opens the file
in non-sharing mode.
blockDelete
The server MUST guarantee that the
file itself is not deleted in any other way until the client
closes the handle. No other client or process is allowed to open the file with delete access.
blockAdvisory
If set, the above "block" modes are advisory. In
advisory mode, only other accesses that specify a "block" mode need
be considered when determining whether the "block" can be granted,
and the server need not prevent I/O operations that violate the
block mode.
The server MAY perform mandatory locking even if the
blockAdvisory flag is set.
noFollow
If the final component of the path is a symlink, then the open
MUST fail.
deleteOnClose
The file should be deleted when the last handle to it is closed.
(The last handle may not be an sftp-handle.) This MAY be emulated
by a server if the OS doesn't support it by deleting the file when
this handle is closed.
accessAuditAlarmInfo
The client wishes the server to enable any privileges or extra
capabilities that the user may have in to allow the reading and
writing of AUDIT or ALARM access control entries.
accessBackup
The client wishes the server to enable any privileges or extra
capabilities that the user may have in order to bypass normal
access checks for the purpose of backing up or restoring files.
backupStream
This flag indicates that the client wishes to read or write a
backup stream. A backup stream is a system dependent structured
data stream that encodes all the information that must be
preserved in order to restore the file from backup medium.
The only well defined use for backup stream data read in this
fashion is to write it to the same server to a file also opened
using the backupStream flag. However, if the server has a well
defined backup stream format, there may be other uses for this
data outside the scope of this protocol.
IMPORANT: If remotePath is a filename with no path, such as "test.txt", and the server responds with a "Folder not found" error, then try prepending "./" to the remotePath. For example, instead of passing "test.txt", try "./test.txt". Returns a null on failure Understanding SFTP Absolute FilePaths SFTP Where Did My Upload Go?
# handle is a string (input)
# numBytes is an integer (input)
# charset is a string (input)
# Returns a string
readFileText( handle, numBytes, charset )
This method is identical to ReadFileBytes except for one thing: The bytes are interpreted according to the specified charset (i.e. the character encoding) and returned as a string. A list of supported charset values may be found on this page: Supported Charsets.
Note: If the charset is an encoding where a single character might be represented in multiple bytes (such as utf-8, Shift_JIS, etc.) then there is a risk that the very last character may be partially read. This is because the method specifies the number of bytes to read, not the number of characters. This is never a problem with character encodings that use a single byte per character, such as all of the iso-8859-* encodings, or the Windows-* encodings.
To read an entire file, one may call ReadFileText repeatedly until Eof(handle) returns 1. Returns a null on failure
# handle is a string (input)
# offset is an integer (input)
# numBytes is an integer (input)
# charset is a string (input)
# Returns a string
readFileText32( handle, offset, numBytes, charset )
This method is identical to ReadFileBytes32 except for one thing: The bytes are interpreted according to the specified charset (i.e. the character encoding) and returned as a string. A list of supported charset values may be found on this page: Supported Charsets.
Note: If the charset is an encoding where a single character might be represented in multiple bytes (such as utf-8, Shift_JIS, etc.) then there is a risk that the very last character may be partially read. This is because the method specifies the number of bytes to read, not the number of characters. This is never a problem with character encodings that use a single byte per character, such as all of the iso-8859-* encodings, or the Windows-* encodings. Returns a null on failure
# handle is a string (input)
# offset is a string (input)
# numBytes is an integer (input)
# charset is a string (input)
# Returns a string
readFileText64s( handle, offset, numBytes, charset )
This method is identical to ReadFileBytes64s except for one thing: The bytes are interpreted according to the specified charset (i.e. the character encoding) and returned as a string. A list of supported charset values may be found on this page: Supported Charsets.
Note: If the charset is an encoding where a single character might be represented in multiple bytes (such as utf-8, Shift_JIS, etc.) then there is a risk that the very last character may be partially read. This is because the method specifies the number of bytes to read, not the number of characters. This is never a problem with character encodings that use a single byte per character, such as all of the iso-8859-* encodings, or the Windows-* encodings. Returns a null on failure
# originalPath is a string (input)
# composePath is a string (input)
# Returns a string
realPath( originalPath, composePath )
This method can be used to have the server
canonicalize any given path name to an absolute path. This is useful
for converting path names containing ".." components or relative
pathnames without a leading slash into absolute paths. The absolute path is returned by this method.
originalPath is the first component of the path which the client wishes resolved
into a absolute canonical path. This may be the entire path.
The composePath is a path which the client wishes the server to compose with the
original path to form the new path. This field is optional and may be set to a zero-length string.
The server will take the originalPath and apply the composePath
as a modification to it. composePath may be relative to originalPath or may be an absolute path, in which case originalPath will
be discarded. The composePath may be zero length.
Note: Servers running SFTP v4 and below do not support composePath. Returns a null on failure
# Returns a string
sessionLog( )
Contains a log of the messages sent to/from the SFTP server. To enable session logging, set the KeepSessionLog property = 1. Note: This property is not a filename -- it is a string property that contains the session log data. Returns a null on failure
# Returns a string
socksHostname( )
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5). Returns a null on failure
# Returns a string
socksPassword( )
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4. Returns a null on failure
# Returns a string
socksUsername( )
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5). Returns a null on failure
# Returns a string
version( )
The version of the SFTP component, such as "2.3.0". Returns a null on failure
|