Qore SSH2 Module  1.0
Qore::SSH2::SFTPClient Class Reference

allows Qore programs to use the sftp protocol with a remote server More...

Inheritance diagram for Qore::SSH2::SFTPClient:

Public Member Functions

string chdir (string path, timeout timeout=60s)
 Changes the directory on the remote server and returns the new directory; throws an exception if any errors occur. More...
 
nothing chmod (string path, int mode, timeout timeout=60s)
 Changes the mode of a remote file or directory; sticky bits may not be set; throws an exception if any errors occur. More...
 
 constructor (string url, softint port=0)
 Creates the object with the given URL. More...
 
 copy ()
 Throws an exception; currently SFTPClient objects cannot be copied. More...
 
binary getFile (string path, timeout timeout=60s)
 Retrieves a remote file and returns it as a binary object; throws an exception if any errors occur. More...
 
string getTextFile (string path, timeout timeout=60s, *string encoding)
 Retrieves a remote file and returns it as a string; throws an exception if any errors occur. More...
 
hash info ()
 Returns a hash with information about the current connection status. More...
 
hash list (*string path, timeout timeout=60s)
 Returns a hash of directory information; throws an exception if any errors occur. More...
 
list listFull (*string path, timeout timeout=60s)
 Returns a list of directory information with detailed information for files, links, and directories; throws an exception if any errors occur. More...
 
nothing mkdir (string path, int mode=0755, timeout timeout=60s)
 Makes a directory on the remote server; throws an exception if any errors occur. More...
 
*string path ()
 Returns the current path as a string or NOTHING if no path is set. More...
 
int putFile (binary bin, string path, int mode=0644, timeout timeout=60s)
 Saves a file on the remote server from a binary argument and returns the number of bytes sent; throws an exception if any errors occur. More...
 
int putFile (string data, string path, int mode=0644, timeout timeout=60s)
 Saves a file on the remote server from a string argument and returns the number of bytes sent; throws an exception if any errors occur. More...
 
nothing removeFile (string path, timeout timeout=60s)
 Deletes a file on the server side; throws an exception if any errors occur. More...
 
nothing rename (string old_name, string new_name, timeout timeout=60s)
 Renames or moves a remote file; throws an exception if any errors occur. More...
 
int retrieveFile (string remote_path, string local_path, timeout timeout=60s, int mode=0644)
 Retrieves a remote file and saves it on the local filesystem; throws an exception if any errors occur. More...
 
nothing rmdir (string path, timeout timeout=60s)
 Removes a directory on the remote server; throws an exception if any errors occur. More...
 
*hash stat (string path, timeout timeout=60s)
 Returns a hash of information about a file or NOTHING if the file cannot be found. More...
 
int transferFile (string local_path, string remote_path, timeout timeout=60s, *int mode)
 Transfers a local file to the remote server and returns the number of bytes sent; throws an exception if any errors occur. More...
 
- Public Member Functions inherited from Qore::SSH2::SSH2Base
 clearStats ()
 Clears performance statistics. More...
 
nothing clearWarningQueue ()
 Removes any warning Queue object from the Socket. More...
 
nothing connect (timeout timeout=1m)
 connect to remote system More...
 
bool connected ()
 returns True if the session is connected, False if not More...
 
 constructor ()
 Throws an exception; the constructor cannot be called manually. More...
 
nothing disconnect (timeout timeout=1m)
 Disconnects from the remote system; throws an exception if the object is not currently connected. More...
 
hash getUsageInfo ()
 Returns performance statistics for the socket. More...
 
nothing setKeys (string priv_key, *string pub_key)
 Sets path to the private key and optionally the public key to use for the next connection; can only be called when a connection is not established, otherwise an exception is thrown. More...
 
nothing setPassword (string pass)
 Sets the password for the next connection; can only be called when a connection is not established, otherwise an exception is thrown. More...
 
nothing setUser (string user)
 Sets the user name for the next connection; can only be called when a connection is not established, otherwise an exception is thrown. More...
 
nothing setWarningQueue (int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms=1s)
 Sets a Queue object to receive socket warnings. More...
 

Detailed Description

allows Qore programs to use the sftp protocol with a remote server

Restrictions:
Qore::PO_NO_NETWORK

Member Function Documentation

string Qore::SSH2::SFTPClient::chdir ( string  path,
timeout  timeout = 60s 
)

Changes the directory on the remote server and returns the new directory; throws an exception if any errors occur.

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
pathThe pathname of the directory to change to
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
Example:
$sftpclient.chdir($path);
nothing Qore::SSH2::SFTPClient::chmod ( string  path,
int  mode,
timeout  timeout = 60s 
)

Changes the mode of a remote file or directory; sticky bits may not be set; throws an exception if any errors occur.

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
paththe pathname of the file or directory to update
modethe new mode to se
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Exceptions
SFTPCLIENT-PARAMETER-ERRORmode setting is only possible for user, group and other (no sticky bits)
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
Example:
$sftpclient.chmod("file.txt", 0600);
Qore::SSH2::SFTPClient::constructor ( string  url,
softint  port = 0 
)

Creates the object with the given URL.

Parameters
urlthe remote host to connect to - can also be a url like "sftp://user:pass@hostname:port"; if any scheme is given in the URL, then it must be "sftp" or an SFTPCLIENT-PARAMETER-ERROR exception will be thrown
portthe port number on the remote host to connect to; if the port is 0, then the port given in the url argument is used; if none is given there, then the default port is used (22)
Exceptions
SFTPCLIENT-PARAMETER-ERRORunknown protocol passed in URL; no hostname in URL
Example:
my SFTPClient $sftpclient("sftp://user:pass@host:4022");
Qore::SSH2::SFTPClient::copy ( )

Throws an exception; currently SFTPClient objects cannot be copied.

Exceptions
SFTPCLIENT-COPY-ERRORcopying SFTPClient objects is not currently implemented
binary Qore::SSH2::SFTPClient::getFile ( string  path,
timeout  timeout = 60s 
)

Retrieves a remote file and returns it as a binary object; throws an exception if any errors occur.

Example:
my binary $b = $sftpclient.getFile("file.bin");

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
paththe pathname of the file to retrieve
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
See also
string Qore::SSH2::SFTPClient::getTextFile ( string  path,
timeout  timeout = 60s,
*string  encoding 
)

Retrieves a remote file and returns it as a string; throws an exception if any errors occur.

Example:
my string $str = $sftpclient.getTextFile("file.txt");

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
paththe pathname of the file to retrieve
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
encodingan optional file encoding/character set. Qore default encoding is used if not set.
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
See also
hash Qore::SSH2::SFTPClient::info ( )

Returns a hash with information about the current connection status.

this method is safe to call when not connected

Returns
a hash with the following keys:
  • ssh2host: (string) the host name of the remote server
  • ssh2port: (int) the port number of the remote server
  • ssh2user: (string) the user name used for the connection
  • keyfile_priv: (string) the filename of the local private key file used
  • keyfile_pub: (string) the filename of the local public key file used
  • fingerprint: (*string) The fingerprint of the public host key of the remote server as a string of hex digit pairs separated by colons (:), ex: "AC:AA:DF:3F:49:82:5A:1A:DE:C9:ED:14:00:7D:65:9E" or NOTHING if not connected
  • authenticated: (*string) a string giving the authentication mechanism used: "publickey", "password", "keyboard-interactive" or NOTHING if not connected
  • connected: (bool) tells if the connection is currently active or not
  • methods: (hash) a hash of strings giving the crytographic methods used for the connection
  • path: (*string) a string giving the path name set in the object or NOTHING if no path is set
Code Flags:
CONSTANT
Example:
my hash $h = $sftpclient.info();
hash Qore::SSH2::SFTPClient::list ( *string  path,
timeout  timeout = 60s 
)

Returns a hash of directory information; throws an exception if any errors occur.

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Code Flags:
RET_VALUE_ONLY
Parameters
pathThe pathname of the directory to list; if no path is given, then information about the current directory is returned
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Returns
a hash with the following keys containing and sorted lists of directory, file, or symbolic link names, respectively:
  • path: the path used
  • directories: sorted list of subdirectory names in the directory
  • files: sorted list of file names in the directory
  • links: sorted list of symbolic links in the directory
Exceptions
SFTPCLIENT-LIST-ERRORfailed to list directory
SFTPCLIENT-TIMEOUTtimeout in network operation
Example:
my hash $h = $sftpclient.list($path);
See also
SFTPClient::listFull()
list Qore::SSH2::SFTPClient::listFull ( *string  path,
timeout  timeout = 60s 
)

Returns a list of directory information with detailed information for files, links, and directories; throws an exception if any errors occur.

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Code Flags:
RET_VALUE_ONLY
Parameters
pathThe pathname of the directory to list; if no path is given, then information about the current directory is returned
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Returns
a list of hashes; each hash has the following keys:
  • name: the name of the file, link, or directory
  • size: the size of the file in bytes
  • uid: the UID of the owner of the file
  • gid: the GID of the owner of the file
  • mode: the permissions / mode of the file
  • atime: the last accessed date/time of the file
  • mtime: the last modified date/time of the file
  • type: the type of file; one of: "REGULAR", "DIRECTORY", "SYMBOLIC-LINK", "BLOCK-DEVICE", "CHARACTER-DEVICE", "FIFO", "SYMBOLIC-LINK", "SOCKET", or "UNKNOWN"
  • perm: a string giving UNIX-style permissions for the file (ex: "-rwxr-xr-x")
Exceptions
SFTPCLIENT-LIST-ERRORfailed to list directory
SFTPCLIENT-TIMEOUTtimeout in network operation
Example:
my list $l = $sftpclient.listFull($path);
See also
SFTPClient::list()
Since
ssh2 0.9.8.1
nothing Qore::SSH2::SFTPClient::mkdir ( string  path,
int  mode = 0755,
timeout  timeout = 60s 
)

Makes a directory on the remote server; throws an exception if any errors occur.

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
pathThe pathname of the new directory
modethe mode of the new directory
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Exceptions
SFTPCLIENT-MKDIR-ERRORdirectory name is an empty string
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
Example:
$sftpclient.mkdir($path, 0700);
*string Qore::SSH2::SFTPClient::path ( )

Returns the current path as a string or NOTHING if no path is set.

Returns
the current path as a string or NOTHING if no path is set
Code Flags:
CONSTANT
Example:
my *string $path = $sftpclient.path();
int Qore::SSH2::SFTPClient::putFile ( binary  bin,
string  path,
int  mode = 0644,
timeout  timeout = 60s 
)

Saves a file on the remote server from a binary argument and returns the number of bytes sent; throws an exception if any errors occur.

Example:
my int $size = $sftpclient.putFile($bin, "file.bin", 0600);

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
binthe file data as a binary object
paththe remote path name on the server
modethe mode of the file on the server
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Returns
the number of bytes actually sent
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
See also
int Qore::SSH2::SFTPClient::putFile ( string  data,
string  path,
int  mode = 0644,
timeout  timeout = 60s 
)

Saves a file on the remote server from a string argument and returns the number of bytes sent; throws an exception if any errors occur.

Example:
my int $size = $sftpclient.putFile($str, "file.bin", 0600);

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
datathe file data as a string
paththe remote path name on the server
modethe mode of the file on the server
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Returns
the number of bytes actually sent
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
See also
nothing Qore::SSH2::SFTPClient::removeFile ( string  path,
timeout  timeout = 60s 
)

Deletes a file on the server side; throws an exception if any errors occur.

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
paththe pathname of the file to delete
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
Example:
$sftpclient.removeFile($path);
nothing Qore::SSH2::SFTPClient::rename ( string  old_name,
string  new_name,
timeout  timeout = 60s 
)

Renames or moves a remote file; throws an exception if any errors occur.

If a connection has not yet been established, it is implicitly attempted here before executing the method. Note that this command is executed with the LIBSSH2_SFTP_RENAME_OVERWRITE option set to True, but that this option is commonly ignored by sshd servers, in which case if the target file already exists, an SSH2-ERROR exception will be raised

Parameters
old_namethe old pathname of the file
new_namethe new pathname of the file
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message; file exists and server does not allow overwriting
SFTPCLIENT-TIMEOUTtimeout in network operation
Example:
$sftpclient.name("file.txt", "file.txt.orig");
int Qore::SSH2::SFTPClient::retrieveFile ( string  remote_path,
string  local_path,
timeout  timeout = 60s,
int  mode = 0644 
)

Retrieves a remote file and saves it on the local filesystem; throws an exception if any errors occur.

Restrictions:
Qore::PO_NO_FILESYSTEM
Example:
$sftpclient.retrieveFile("file.bin", "/tmp/file.bin");

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
remote_paththe remote pathname of the file to retrieve
local_paththe local filesystem pathname to save the file to
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Returns
the number of bytes transferred
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
See also
Since
ssh2 1.0
nothing Qore::SSH2::SFTPClient::rmdir ( string  path,
timeout  timeout = 60s 
)

Removes a directory on the remote server; throws an exception if any errors occur.

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
pathThe pathname of the directory to remove
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Exceptions
SFTPCLIENT-RMDIR-ERRORdirectory name is an empty string
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
Example:
$sftpclient.rmdir($path);
*hash Qore::SSH2::SFTPClient::stat ( string  path,
timeout  timeout = 60s 
)

Returns a hash of information about a file or NOTHING if the file cannot be found.

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Code Flags:
RET_VALUE_ONLY
Parameters
paththe pathname of the file to stat
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Returns
NOTHING if the path was not found or a hash with the following keys (note that some hash keys may not be present if the data was not returned from the remote server):
  • size: (int) the size of the file in bytes
  • atime: (date) the date/time the file was last accessed
  • mtime: (date) the date/time the file was last modified
  • uid: (int) the userid of the file's owner
  • gid: (int) the groupid of the file
  • mode: (int) the mode of the file as an integer
  • type: the type of file; one of: "REGULAR", "DIRECTORY", "SYMBOLIC-LINK", "BLOCK-DEVICE", "CHARACTER-DEVICE", "FIFO", "SYMBOLIC-LINK", "SOCKET", or "UNKNOWN"
  • permissions: (string) a string giving the symbolic mode of the file
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
Example:
my *hash $h = $sftpclient.stat($path);
int Qore::SSH2::SFTPClient::transferFile ( string  local_path,
string  remote_path,
timeout  timeout = 60s,
*int  mode 
)

Transfers a local file to the remote server and returns the number of bytes sent; throws an exception if any errors occur.

Restrictions:
Qore::PO_NO_FILESYSTEM
Example:
my int $size = $sftpclient.putFile($str, "file.bin", 0600);

If a connection has not yet been established, it is implicitly attempted here before executing the method.

Parameters
local_paththe path to the local file on the local filesystem
remote_paththe remote path name on the server
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
modethe mode of the file on the server; if not given then the same file mode on the local filesystem will be used on the remote
Returns
the number of bytes actually sent
Exceptions
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUTtimeout in network operation
See also
Since
ssh2 1.0

The documentation for this class was generated from the following file: