Qore SSH2 Module  1.4.1
Qore::SSH2::SSH2Base Class Reference

base class for SFTPClient and SSH2Client More...

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
timeoutan integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)
Exceptions
SOCKET-CONNECT-ERRORerror establishing socket connection (no listener, port blocked, etc); timeout establishing socket connection
SSH2CLIENT-CONNECT-ERRORno user name set; ssh2 or libssh2 error
SSH2-ERRORerror initializing or establishing ssh2 session
SSH2CLIENT-AUTH-ERRORno proper authentication method found
SFTPCLIENT-CONNECT-ERRORerror 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-ERRORthis 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-CONNECTEDthe client is not connected
Parameters
timeoutan 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_keythe path to the private key file to use for the next connection
pub_keyoptional: 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-CONNECTEDthis method cannot be called when a connection is established
SSH2-SETKEYS-ERRORthe 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
passthe password to use for the next connection
Exceptions
SSH2-CONNECTEDthis 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
userthe user name to set for the next connection
Exceptions
SSH2-CONNECTEDthis 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_msthe 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_bsvalue 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
queuethe Queue object to receive warning events
argan optional argument to be placed in the "arg" key in each warning hash (could be used to identify the socket for example)
min_msthe 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-ERRORthe Queue passed has a maximum size set
SOCKET-SETWARNINGQUEUE-ERRORat 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: