Qore ssh2 Module ..
Loading...
Searching...
No Matches
Qore::SSH2::SFTPClient Class Reference

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

#include <QC_SFTPClient.dox.h>

Inheritance diagram for Qore::SSH2::SFTPClient:
Qore::SSH2::SSH2Base

Public Member Methods

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...
 
int get (string remote_path, Qore::OutputStream os, timeout timeout=60s)
 Retrieves a remote file and writes its content to an OutputStream; throws an exception if any errors occur. 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< SftpConnectionInfoinfo ()
 Returns a hash with information about the current connection status. More...
 
bool isAlive (timeout timeout_ms=60)
 Check if connections is responding to test request; throws an exception if any errors occur. More...
 
bool isAliveEx (timeout timeout_ms=60)
 Check if connections is responding to test request. More...
 
hash< SftpDirInfolist (*string path, timeout timeout=60s)
 Returns a hash of directory information; throws an exception if any errors occur. More...
 
list< hash< SftpFileInfo > > 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 put (Qore::InputStream is, string remote_path, timeout timeout=60s, int mode=0644)
 Saves a file on the remote server from an InputStream and returns the number of bytes sent; throws an exception if any errors occur. 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< Ssh2StatInfostat (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 Methods 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...
 
*string getAuthenticatedWith ()
 returns the authentication type if connected More...
 
*string getHost ()
 returns the target hostname if any is set More...
 
*string getKeyPriv ()
 returns the private key path if any is set More...
 
*string getKeyPub ()
 returns the public key path if any is set More...
 
*string getPassword ()
 returns the connection passsword if any is set More...
 
int getPort ()
 returns the target port More...
 
hash< auto > getUsageInfo ()
 Returns performance statistics for the socket. More...
 
*string getUser ()
 returns the target user if any is set 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

◆ chdir()

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.

Example:
sftpclient.chdir(path);

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
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

◆ chmod()

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.

Example:
sftpclient.chmod("file.txt", 0600);

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)
SFTPCLIENT-TIMEOUTtimeout in network operation
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

◆ constructor()

Qore::SSH2::SFTPClient::constructor ( string  url,
softint  port = 0 
)

Creates the object with the given URL.

Example:
SFTPClient sftpclient("sftp://user:pass@host:4022");
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

◆ copy()

Qore::SSH2::SFTPClient::copy ( )

Throws an exception; currently SFTPClient objects cannot be copied.

Exceptions
SFTPCLIENT-COPY-ERRORcopying SFTPClient objects is not currently implemented

◆ get()

int Qore::SSH2::SFTPClient::get ( string  remote_path,
Qore::OutputStream  os,
timeout  timeout = 60s 
)

Retrieves a remote file and writes its content to an OutputStream; throws an exception if any errors occur.

Example:
sftpclient.get(filepath, outputStream);

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
osthe output stream to write 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-GET-ERRORerror retrieving SFTP data
SFTPCLIENT-TIMEOUTtimeout in network operation
See also
Since
ssh2 1.1

◆ getFile()

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:
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
SFTPCLIENT-GETFILE-ERRORerror retrieving SFTP data
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
See also

◆ getTextFile()

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:
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
SFTPCLIENT-GETTEXTFILE-ERRORerror retrieving SFTP data
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
See also

◆ info()

hash< SftpConnectionInfo > Qore::SSH2::SFTPClient::info ( )

Returns a hash with information about the current connection status.

Code Flags:
CONSTANT
Example:
hash<SftpConnectionInfo> h = sftpclient.info();

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

◆ isAlive()

bool Qore::SSH2::SFTPClient::isAlive ( timeout  timeout_ms = 60)

Check if connections is responding to test request; throws an exception if any errors occur.

Example:
sftpclient.isAliveEx(timeout_ms);

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

This variant does not throw exceptions due to I/O errors or timeouts.

Returns
True if server is responding, False otherwise
Parameters
timeout_msan integer giving a timeout in milliseconds
See also
isAliveEx()

◆ isAliveEx()

bool Qore::SSH2::SFTPClient::isAliveEx ( timeout  timeout_ms = 60)

Check if connections is responding to test request.

Example:
sftpclient.isAliveEx(timeout_ms);

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

This variant throws exceptions if I/O errors or timeouts are encountered.

Returns
True if server is responding, False otherwise
Parameters
timeout_msan integer giving a timeout in milliseconds
Exceptions
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
See also
isAlive()

◆ list()

hash< SftpDirInfo > Qore::SSH2::SFTPClient::list ( *string  path,
timeout  timeout = 60s 
)

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

Code Flags:
RET_VALUE_ONLY
Example:
hash<auto> h = sftpclient.list(path);

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

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
SSH2-ERRORsocket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message
See also
SFTPClient::listFull()

◆ listFull()

list< hash< SftpFileInfo > > 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.

Code Flags:
RET_VALUE_ONLY
Example:
list<hash<SftpFileInfo>> l = sftpclient.listFull(path);

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

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
SSH2-ERRORsocket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message
See also
SFTPClient::list()
Since
ssh2 0.9.8.1

◆ mkdir()

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.

Example:
sftpclient.mkdir(path, 0700);

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
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

◆ path()

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

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

Code Flags:
CONSTANT
Example:
*string path = sftpclient.path();
Returns
the current path as a string or NOTHING if no path is set

◆ put()

int Qore::SSH2::SFTPClient::put ( Qore::InputStream  is,
string  remote_path,
timeout  timeout = 60s,
int  mode = 0644 
)

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

Example:
int size = sftpclient.put(inputStream, "file.bin");

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

Parameters
isthe input stream to upload to the server
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
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.1

◆ putFile() [1/2]

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:
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
SFTPCLIENT-PUTFILE-ERRORerror sending SFTP data
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
See also

◆ putFile() [2/2]

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:
int size = sftpclient.putFile(str, filepath, 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
SFTPCLIENT-PUTFILE-ERRORerror sending SFTP data
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
See also

◆ removeFile()

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

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

Example:
sftpclient.removeFile(path);

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
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

◆ rename()

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.

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

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
SFTPCLIENT-TIMEOUTtimeout in network operation
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

◆ retrieveFile()

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
SFTPCLIENT-RETRIEVEFILE-ERRORerror retrieving SFTP data
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
See also
Since
ssh2 1.0

◆ rmdir()

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

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

Example:
sftpclient.rmdir(path);

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
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

◆ stat()

*hash< Ssh2StatInfo > 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.

Code Flags:
RET_VALUE_ONLY
Example:
*hash<Ssh2StatInfo> h = sftpclient.stat(path);

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

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
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message

◆ transferFile()

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:
int size = sftpclient.transferFile(local_filepath, remote_filepath, 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
SFTPCLIENT-TIMEOUTtimeout in network operation
SSH2-ERRORsocket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message
See also
Since
ssh2 1.0

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