![]() |
Qore SSH2 Module 1.4.1
|
allows Qore programs to use the sftp protocol with a remote server More...
#include <QC_SFTPClient.dox.h>

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< SftpConnectionInfo > | info () |
| 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< SftpDirInfo > | list (*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< Ssh2StatInfo > | 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 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... | |
allows Qore programs to use the sftp protocol with a remote server
| 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.
| 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) |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| 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.
| 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) |
| SFTPCLIENT-PARAMETER-ERROR | mode setting is only possible for user, group and other (no sticky bits) |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| 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 |
| Qore::SSH2::SFTPClient::constructor | ( | string | url, |
| softint | port = 0 |
||
| ) |
Creates the object with the given URL.
| 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) |
| SFTPCLIENT-PARAMETER-ERROR | unknown protocol passed in URL; no hostname in URL |
| Qore::SSH2::SFTPClient::copy | ( | ) |
Throws an exception; currently SFTPClient objects cannot be copied.
| SFTPCLIENT-COPY-ERROR | copying SFTPClient objects is not currently implemented |
| 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.
If a connection has not yet been established, it is implicitly attempted here before executing the method.
| remote_path | the remote pathname of the file to retrieve |
| os | the output stream to write to |
| timeout | an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds) |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| SFTPCLIENT-GET-ERROR | error retrieving SFTP data |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| 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.
| 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) |
| SFTPCLIENT-GETFILE-ERROR | error retrieving SFTP data |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| 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.
| 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. |
| SFTPCLIENT-GETTEXTFILE-ERROR | error retrieving SFTP data |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| hash< SftpConnectionInfo > Qore::SSH2::SFTPClient::info | ( | ) |
Returns a hash with information about the current connection status.
this method is safe to call when not connected
ssh2host: (string) the host name of the remote serverssh2port: (int) the port number of the remote serverssh2user: (string) the user name used for the connectionkeyfile_priv: (string) the filename of the local private key file usedkeyfile_pub: (string) the filename of the local public key file usedfingerprint: (*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 connectedauthenticated: (*string) a string giving the authentication mechanism used: "publickey", "password", "keyboard-interactive" or NOTHING if not connectedconnected: (bool) tells if the connection is currently active or notmethods: (hash) a hash of strings giving the crytographic methods used for the connectionpath: (*string) a string giving the path name set in the object or NOTHING if no path is set | bool Qore::SSH2::SFTPClient::isAlive | ( | timeout | timeout_ms = 60 | ) |
Check if connections is responding to test request; throws an exception if any errors occur.
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.
| timeout_ms | an integer giving a timeout in milliseconds |
| bool Qore::SSH2::SFTPClient::isAliveEx | ( | timeout | timeout_ms = 60 | ) |
Check if connections is responding to test request.
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.
| timeout_ms | an integer giving a timeout in milliseconds |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| hash< SftpDirInfo > 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.
| 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) |
path: the path useddirectories: sorted list of subdirectory names in the directoryfiles: sorted list of file names in the directorylinks: sorted list of symbolic links in the directory| SFTPCLIENT-LIST-ERROR | failed to list directory |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message |
| 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.
If a connection has not yet been established, it is implicitly attempted here before executing the method.
| 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) |
name: the name of the file, link, or directorysize: the size of the file in bytesuid: the UID of the owner of the filegid: the GID of the owner of the filemode: the permissions / mode of the fileatime: the last accessed date/time of the filemtime: the last modified date/time of the filetype: 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")| SFTPCLIENT-LIST-ERROR | failed to list directory |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message |
| 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.
| 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) |
| SFTPCLIENT-MKDIR-ERROR | directory name is an empty string |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| *string Qore::SSH2::SFTPClient::path | ( | ) |
Returns the current path as a string or NOTHING if no path is set.
NOTHING if no path is set | 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.
If a connection has not yet been established, it is implicitly attempted here before executing the method.
| is | the input stream to upload to the server |
| remote_path | the remote path name on the server |
| timeout | an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds) |
| mode | the mode of the file on the server |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| 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.
| 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) |
| SFTPCLIENT-PUTFILE-ERROR | error sending SFTP data |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| 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.
| 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) |
| SFTPCLIENT-PUTFILE-ERROR | error sending SFTP data |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| 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.
| 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) |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| 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
| 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) |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| 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 |
| 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.
If a connection has not yet been established, it is implicitly attempted here before executing the method.
| remote_path | the remote pathname of the file to retrieve |
| local_path | the local filesystem pathname to save the file to |
| timeout | an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds) |
| SFTPCLIENT-RETRIEVEFILE-ERROR | error retrieving SFTP data |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| 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.
| 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) |
| SFTPCLIENT-RMDIR-ERROR | directory name is an empty string |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| *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.
If a connection has not yet been established, it is implicitly attempted here before executing the method.
| 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) |
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 bytesatime: (date) the date/time the file was last accessedmtime: (date) the date/time the file was last modifieduid: (int) the userid of the file's ownergid: (int) the groupid of the filemode: (int) the mode of the file as an integertype: 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| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |
| 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.
If a connection has not yet been established, it is implicitly attempted here before executing the method.
| local_path | the path to the local file on the local filesystem |
| remote_path | the remote path name on the server |
| timeout | an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds) |
| mode | the 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 |
| SFTPCLIENT-TIMEOUT | timeout in network operation |
| SSH2-ERROR | socket error sending data; timeout on socket; invalid SFTP protocol response; server returned an error message |