Qore SSH2 Module  1.0
Qore::SSH2::SSH2Base Class Reference

base class for SFTPClient and SSH2Client More...

Inheritance diagram for Qore::SSH2::SSH2Base:

Public Member Functions

 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...
 
hash getUsageInfo ()
 Returns performance statistics for the socket. 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

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

Clears performance statistics.

Example:
$sftpclient.clearStats();
Since
ssh2 1.0
See also
SSH2Base::getUsageInfo()
nothing Qore::SSH2::SSH2Base::clearWarningQueue ( )

Removes any warning Queue object from the Socket.

Example:
$sftpclient.clearWarningQueue();
See also
SSH2Base::setWarningQueue()
Since
ssh2 1.0
nothing Qore::SSH2::SSH2Base::connect ( timeout  timeout = 1m)

connect to remote system

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)
Example:
$sftpclient.connect(30s);
bool Qore::SSH2::SSH2Base::connected ( )

returns True if the session is connected, False if not

Returns
True if the session is connected, False if not
Code Flags:
CONSTANT
Example:
my bool $b = $sftpclient.connected();
Since
ssh2 0.9.8.1
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
nothing Qore::SSH2::SSH2Base::disconnect ( timeout  timeout = 1m)

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

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)
Example:
$sftpclient.disconnect();
hash Qore::SSH2::SSH2Base::getUsageInfo ( )

Returns performance statistics for the socket.

Code Flags:
CONSTANT
Example:
my hash $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()
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
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)
Example:
$sftpclient.setKeys($ENV.HOME + "/.ssh/id_rsa", $ENV.HOME + "/.ssh/id_rsa.pub");
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.

Parameters
passthe password to use for the next connection
Exceptions
SSH2-CONNECTEDthis method cannot be called when a connection is established
Example:
$sftpclient.setPassword("pass");
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.

Parameters
userthe user name to set for the next connection
Exceptions
SSH2-CONNECTEDthis method cannot be called when a connection is established
Example:
$sftpclient.setUser("username");
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: