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)
	Changes the directory on the remote server and returns the new directory; throws an exception if any errors occur.

nothing	chmod (string path, int mode)
	Changes the mode of a remote file or directory; sticky bits may not be set; throws an exception if any errors occur.

	constructor (string url, softint port=0)
	Creates the object with the given URL.

	copy ()
	Throws an exception; currently SFTPClient objects cannot be copied.

binary	getFile (string path)
	Retrieves a remote file and returns it as a binary object; throws an exception if any errors occur.

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

hash	info ()
	Returns a hash with information about the current connection status.

hash	list (*string path)
	Returns a hash of directory information; throws an exception if any errors occur.

nothing	mkdir (string path, int mode=0755)
	Makes a directory on the remote server; throws an exception if any errors occur.

*string	path ()
	Returns the current path as a string or `NOTHING` if no path is set.

int	putFile (binary bin, string path, int mode=0644)
	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.

int	putFile (string data, string path, int mode=0644)
	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.

nothing	removeFile (string path)
	Deletes a file on the server side; throws an exception if any errors occur.

nothing	rename (string old_name, string new_name)
	Renames or moves a remote file; throws an exception if any errors occur.

nothing	rmdir (string path)
	Removes a directory on the remote server; throws an exception if any errors occur.

*hash	stat (string path)
	Returns a hash of information about a file or `NOTHING` if the file cannot be found.

Public Member Functions inherited from Qore::SSH2::SSH2Base
nothing	connect (timeout timeout=-1)
	connect to remote system

	constructor ()
	Throws an exception; the constructor cannot be called manually.

nothing	disconnect ()
	Disconnects from the remote system; throws an exception if the object is not currently connected.

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.

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.

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.

Detailed Description

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

Member Function Documentation

string Qore::SSH2::SFTPClient::chdir ( string path )

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

Parameters

path	The pathname of the directory to change to

Exceptions

SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

Example:: $sftpclient.chdir($path);

nothing Qore::SSH2::SFTPClient::chmod	(	string	path,
		int	mode
	)

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

Parameters

path	the pathname of the file or directory to update
mode	the new mode to set

Exceptions

SFTPCLIENT-PARAMETER-ERROR	mode setting is only possible for user, group and other (no sticky bits)
SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

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 )

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

Parameters

path	the pathname of the file to retrieve

Exceptions

SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

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

string Qore::SSH2::SFTPClient::getTextFile ( string path )

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

Parameters

path	the pathname of the file to retrieve

Exceptions

SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

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 )

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

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

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-NOT-CONNECTED	client is not connected
SFTPCLIENT-LIST-ERROR	failed to list directory

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

nothing Qore::SSH2::SFTPClient::mkdir	(	string	path,
		int	mode = `0755`
	)

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

Parameters

path	The pathname of the new directory
mode	the mode of the new directory

Exceptions

SFTPCLIENT-MKDIR-ERROR	directory name is an empty string
SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

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`
	)

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.

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

Returns: the number of bytes actually sent

Exceptions

SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

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

int Qore::SSH2::SFTPClient::putFile	(	string	data,
		string	path,
		int	mode = `0644`
	)

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.

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

Returns: the number of bytes actually sent

Exceptions

SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

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

nothing Qore::SSH2::SFTPClient::removeFile ( string path )

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

Parameters

path	the pathname of the file to delete

Exceptions

SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

Example:: $sftpclient.removeFile($path);

nothing Qore::SSH2::SFTPClient::rename	(	string	old_name,
		string	new_name
	)

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

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

Exceptions

SFTPCLIENT-NOT-CONNECTED	no connection has been established
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

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

nothing Qore::SSH2::SFTPClient::rmdir ( string path )

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

Parameters

path	The pathname of the directory to remove

Exceptions

SFTPCLIENT-RMDIR-ERROR	directory name is an empty string
SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

Example:: $sftpclient.rmdir($path);

*hash Qore::SSH2::SFTPClient::stat ( string path )

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

Code Flags:: RET_VALUE_ONLY

Parameters

path	the pathname of the file to stat

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

SFTPCLIENT-NOT-CONNECTED	no connection has been established
SSH2-ERROR	socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

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

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

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

Public Member Functions

Detailed Description

Member Function Documentation