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...

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...

Public Member Functions inherited from Qore::SSH2::SSH2Base
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...

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...

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

path	The pathname of the directory to change to
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout 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

path	the pathname of the file or directory to update
mode	the new mode to se
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SFTPCLIENT-PARAMETER-ERROR	mode setting is only possible for user, group and other (no sticky bits)
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout 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

url	the 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
port	the 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-ERROR unknown 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-ERROR copying 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.

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

Parameters

path	the pathname of the file to retrieve
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout in network operation

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

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.

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

Parameters

path	the pathname of the file to retrieve
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)
encoding	an optional file encoding/character set. Qore default encoding is used if not set.

Exceptions

SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout in network operation

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

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

path	The pathname of the directory to list; if no path is given, then information about the current directory is returned
timeout	an 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-ERROR	failed to list directory
SFTPCLIENT-TIMEOUT	timeout 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

path	The pathname of the directory to list; if no path is given, then information about the current directory is returned
timeout	an 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
type:
perm: a string giving UNIX-style permissions for the file (ex: "-rwxr-xr-x")

Exceptions

SFTPCLIENT-LIST-ERROR	failed to list directory
SFTPCLIENT-TIMEOUT	timeout 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

path	The pathname of the new directory
mode	the mode of the new directory
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SFTPCLIENT-MKDIR-ERROR	directory name is an empty string
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout 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.

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

Parameters

bin	the file data as a binary object
path	the remote path name on the server
mode	the mode of the file on the server
timeout	an 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-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout in network operation

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

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.

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

Parameters

data	the file data as a string
path	the remote path name on the server
mode	the mode of the file on the server
timeout	an 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-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout in network operation

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

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

path	the pathname of the file to delete
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout 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_name	the old pathname of the file
new_name	the new pathname of the file
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message; file exists and server does not allow overwriting
SFTPCLIENT-TIMEOUT	timeout in network operation

Example:: $sftpclient.name("file.txt", "file.txt.orig");

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

path	The pathname of the directory to remove
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SFTPCLIENT-RMDIR-ERROR	directory name is an empty string
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout 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

path	the pathname of the file to stat
timeout	an 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
permissions: (string) a string giving the symbolic mode of the file

Exceptions

SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
SFTPCLIENT-TIMEOUT	timeout in network operation

Example:: my *hash $h = $sftpclient.stat($path);

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

/Users/david/src/qore/svn/module-ssh2/trunk/src/QC_SFTPClient.dox.h

Public Member Functions

Detailed Description

Member Function Documentation