Qore ssh2 Module ..
|
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 directorySFTPCLIENT-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 fileSFTPCLIENT-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 |