base class for SFTPClient and SSH2Client More...

#include <QC_SSH2Base.dox.h>

Inheritance diagram for Qore::SSH2::SSH2Base:

Public Member Methods
	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

base class for SFTPClient and SSH2Client

Restrictions:: Qore::PO_NO_NETWORK

The SSH2Base class provides common methods to the SSH2Client and SFTPClient classes

Member Function Documentation

◆ clearStats()

Qore::SSH2::SSH2Base::clearStats ( )

Clears performance statistics.

Example:: sftpclient.clearStats();

Since: ssh2 1.0

See also: SSH2Base::getUsageInfo()

◆ clearWarningQueue()

nothing Qore::SSH2::SSH2Base::clearWarningQueue ( )

Removes any warning Queue object from the Socket.

Example:: sftpclient.clearWarningQueue();

See also: SSH2Base::setWarningQueue()

Since: ssh2 1.0

◆ connect()

nothing Qore::SSH2::SSH2Base::connect ( timeout timeout = 1m )

connect to remote system

Example:: sftpclient.connect(30s);

Connects to the remote system; if a connection is already established, then it is disconnected first

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)

Exceptions

SOCKET-CONNECT-ERROR	error establishing socket connection (no listener, port blocked, etc); timeout establishing socket connection
SSH2CLIENT-CONNECT-ERROR	no user name set; ssh2 or libssh2 error
SSH2-ERROR	error initializing or establishing ssh2 session
SSH2CLIENT-AUTH-ERROR	no proper authentication method found
SFTPCLIENT-CONNECT-ERROR	error initializing sftp session or getting remote path (exception only possible when called from an SFTPClient object)

◆ connected()

bool Qore::SSH2::SSH2Base::connected ( )

returns True if the session is connected, False if not

Code Flags:: CONSTANT

Example:: bool b = sftpclient.connected();

Returns: True if the session is connected, False if not

Since: ssh2 0.9.8.1

◆ constructor()

Qore::SSH2::SSH2Base::constructor ( )

Throws an exception; the constructor cannot be called manually.

Throws an exception if called directly; this class cannot be instantiated directly

Exceptions

SSH2BASE-CONSTRUCTOR-ERROR this class is an abstract class and cannot be instantiated directly or directly inherited by a user-defined class

◆ disconnect()

nothing Qore::SSH2::SSH2Base::disconnect ( timeout timeout = 1m )

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

Example:: sftpclient.disconnect();

Exceptions

SSH2CLIENT-NOT-CONNECTED the client is not connected

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)

◆ getAuthenticatedWith()

*string Qore::SSH2::SSH2Base::getAuthenticatedWith ( )

returns the authentication type if connected

Returns

the authentication type if connected; one of the following strings is returned:

"password"
"publickey"
"keyboard-interactive"

Since: ssh2 1.3

◆ getHost()

*string Qore::SSH2::SSH2Base::getHost ( )

returns the target hostname if any is set

Returns: the target hostname if any is set

Since: ssh2 1.3

◆ getKeyPriv()

*string Qore::SSH2::SSH2Base::getKeyPriv ( )

returns the private key path if any is set

Returns: the private key path if any is set

Since: ssh2 1.3

◆ getKeyPub()

*string Qore::SSH2::SSH2Base::getKeyPub ( )

returns the public key path if any is set

Returns: the public key path if any is set

Since: ssh2 1.3

◆ getPassword()

*string Qore::SSH2::SSH2Base::getPassword ( )

returns the connection passsword if any is set

Returns: the connection passsword if any is set

Since: ssh2 1.3

◆ getPort()

int Qore::SSH2::SSH2Base::getPort ( )

returns the target port

Returns: the target port

Since: ssh2 1.3

◆ getUsageInfo()

hash< auto > Qore::SSH2::SSH2Base::getUsageInfo ( )

Returns performance statistics for the socket.

Code Flags:: CONSTANT

Example:: hash<auto> h = sftpclient.getUsageInfo();

Returns

a hash with the following keys:

"bytes_sent": an integer giving the total amount of bytes sent
"bytes_recv": an integer giving the total amount of bytes received
"us_sent": an integer giving the total number of microseconds spent sending data
"us_recv": an integer giving the total number of microseconds spent receiving data
"arg": (only if warning values have been set with Socket::setWarningQueue()) the optional argument for warning hashes
"timeout": (only if warning values have been set with Socket::setWarningQueue()) the warning timeout in microseconds
"min_throughput": (only if warning values have been set with Socket::setWarningQueue()) the minimum warning throughput in bytes/sec

Since: ssh2 1.0

See also: SSH2Base::clearStats()

◆ getUser()

*string Qore::SSH2::SSH2Base::getUser ( )

returns the target user if any is set

Returns: the target user if any is set

Since: ssh2 1.3

◆ setKeys()

nothing Qore::SSH2::SSH2Base::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.

Restrictions:: Qore::PO_NO_FILESYSTEM

Example:: sftpclient.setKeys(ENV.HOME + "/.ssh/id_rsa", ENV.HOME + "/.ssh/id_rsa.pub");

Parameters

priv_key	the path to the private key file to use for the next connection
pub_key	optional: the path to the public key file to use for the next connection; note that if this argument is not passed, then the public key file's name will be automaticaly generated by appending `".pub"` to the private key file's name

Exceptions

SSH2-CONNECTED	this method cannot be called when a connection is established
SSH2-SETKEYS-ERROR	the given keys are not available or readable

Note

both keys must be present (private and public) and readable in order for key-based authentication to work
if the keys are not valid no exception is thrown here, however key-based authentication will fail with am error like: "SSH2CLIENT-AUTH-ERROR: No proper authentication method found" (the same or similar error can be raised when the server does not accept otherwise valid keys)

◆ setPassword()

nothing Qore::SSH2::SSH2Base::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.

Example:: sftpclient.setPassword("pass");

Parameters

pass	the password to use for the next connection

Exceptions

SSH2-CONNECTED this method cannot be called when a connection is established

◆ setUser()

nothing Qore::SSH2::SSH2Base::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.

Example:: sftpclient.setUser("username");

Parameters

user	the user name to set for the next connection

Exceptions

SSH2-CONNECTED this method cannot be called when a connection is established

◆ setWarningQueue()

nothing Qore::SSH2::SSH2Base::setWarningQueue	(	int	warning_ms,
		int	warning_bs,
		Queue	queue,
		any	arg,
		timeout	min_ms = `1s`
	)

Sets a Queue object to receive socket warnings.

Example:: sftpclient.setWarningQueue(5000, 5000, queue, "socket-1");

Parameters

warning_ms	the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys: `"type"`: a string with the constant value `"SOCKET-OPERATION-WARNING"` `"operation"`: a string giving the operation that caused the warning (ex: `"connect"`) `"us"`: an integer giving the number of microseconds for the operation `"timeout"`: an integer giving the warning threshold in microseconds `"arg"`: if any `"arg"` argument is passed to the Socket::setWarningQueue() method, it will be included in the warning hash here
warning_bs	value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with th following keys: `"type"`: a string with the constant value `"SOCKET-THROUGHPUT-WARNING"` `"dir"`: either `"send"` or `"recv"` depending on the direction of the data flow `"bytes"`: the amount of bytes sent `"us"`: an integer giving the number of microseconds for the operation `"bytes_sec"`: a float giving the transfer speed in bytes per second `"threshold"`: an integer giving the warning threshold in bytes per second `"arg"`: if any `"arg"` argument is passed to the Socket::setWarningQueue() method, it will be included in the warning hash here
queue	the Queue object to receive warning events
arg	an optional argument to be placed in the `"arg"` key in each warning hash (could be used to identify the socket for example)
min_ms	the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning

Exceptions

QUEUE-ERROR	the Queue passed has a maximum size set
SOCKET-SETWARNINGQUEUE-ERROR	at least one of warning_ms and warning_bs must be > 0

See also: SSH2Base::clearWarningQueue()

Since: ssh2 1.0

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

QC_SSH2Base.dox.h

Public Member Methods

Detailed Description

Member Function Documentation

◆ clearStats()

◆ clearWarningQueue()

◆ connect()

◆ connected()

◆ constructor()

◆ disconnect()

◆ getAuthenticatedWith()

◆ getHost()

◆ getKeyPriv()

◆ getKeyPub()

◆ getPassword()

◆ getPort()

◆ getUsageInfo()

◆ getUser()

◆ setKeys()

◆ setPassword()

◆ setUser()

◆ setWarningQueue()