/** @mainpage Qore SSH2 Module

    @tableofcontents

    @section ssh2intro Introduction to the ssh2 Module

    The ssh2 module provides Qore the possibility to communicate with sshd servers via the <a href="http://en.wikipedia.org/wiki/Secure_Shell#Version_2.x">ssh2 protocol</a>; the underlying functionality is provided by <a href="http://www.libssh2.org">libssh2</a>.

    This module is released under a choice of two licenses:
    - <a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">LGPL 2.1</a>
    - MIT (see COPYING.MIT in the source distribution for more information)
    .
    The module is tagged as such in the module's header (meaning it can be loaded unconditionally regardless of how the %Qore library was initialized).  This version of the module requires Qore 0.8.1+ to compile and run.

    To use the module in a %Qore script, use the \c %%requires directive as follows:
    @code %requires ssh2 @endcode

    This module provides the following classes:
    |!Class|!Description
    |Qore::SSH2::SSH2Base|base class for @ref Qore::SSH2::SFTPClient "SFTPClient" and @ref Qore::SSH2::SSH2Client "SSH2Client"
    |Qore::SSH2::SSH2Client|allows Qore programs to establish an ssh2 connection to a remote server
    |Qore::SSH2::SFTPClient|allows Qore programs to use the sftp protocol
    |Qore::SSH2::SSH2Channel|allows Qore programs to send and receive data through an ssh2 channel

    Also included with the binary ssh2 module:
    - <a href="../../SftpPoller/html/index.html">SftpPoller user module</a>

    When connecting the module will try to:

    - connect to the server with the given port or with port 22 if no port is given
    - login as the given user (user is set in the URL given to @ref Qore::SSH2::SSH2Client::constructor() "SSH2Client::constructor()" or @ref Qore::SSH2::SFTPClient::constructor() "SFTPClient::constructor()" or can be modified with @ref Qore::SSH2::SSH2Base::setUser() "SSH2Base::setUser()") using:
      - publickey authentification (public and private key files can be modified with @ref Qore::SSH2::SSH2Base::setKeys() "SSH2Base::setKeys()")
      - password authentification (password can be set in the URL given to @ref Qore::SSH2::SSH2Client::constructor() "SSH2Client::constructor()" or @ref Qore::SSH2::SFTPClient::constructor() "SFTPClient::constructor()" or can be set afterwards with @ref Qore::SSH2::SSH2Base::setPassword() "SSH2Base::setPassword()")

    See some examples here: @ref examples

    @section examples Examples

    Example of a basic sftp connection:

    @code{.py}
# create object
SFTPClient sftp("sftp://user:pass@host.com:22");
# connect to sftp server
sftp.connect();@endcode

    Example of logging in via ssh2 and executing a command and retrieving the output:

    @code{.py}
# set URL
string url = "sftp://user:pass@host.com:22";
# create object
SSH2Client ssh2(url);
# connect to remote sshd daemon
ssh2.connect();
# get a session channel
SSH2Channel chan = sc.openSessionChannel();
# execute a command on the channel
chan.exec("ls -l");
# retrieve the output and print it out
stdout.printf("%s", chan.read());
# close channel
chan.sendEof();
chan.close();
# print out the exit status after the channel is closed
stdout.printf("exit status: %d\n", chan.getExitStatus());@endcode

    @section codetags Function and Method Tags

    @subsection NOOP NOOP

    Code with this flag makes no calculations, but rather returns a constant value. This flag is given to function and method variants that return a default value depending on the type of argument(s).  When variants with this flag are resolved at parse time, a \c "call-with-type-errors" warning is raised (assuming this warning is enabled), unless \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set.  If \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set, then these variants are inaccessible at parse time; resolving to a variant with this flag set at parse time causes an exception to be thrown.

    These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

    This tag is equal to @ref RUNTIME_NOOP, except no runtime effect is caused by resolving a function or method tagged with \c NOOP at runtime; this tag only affects parse time resolution.

    @subsection RUNTIME_NOOP RUNTIME_NOOP

    Code with this flag makes no calculations, but rather returns a constant value.  This flag is given to function and method variants that return a default value depending on the type of argument(s).  When variants with this flag are resolved at parse time, a \c "call-with-type-errors" warning is raised (assuming this warning is enabled), unless \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set.  If \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set, then these variants are inaccessible; resolving to a variant with this flag set at parse time or run time causes an exception to be thrown.

    These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

    This tag is equal to @ref NOOP, except that \c RUNTIME_NOOP is also enforced at runtime.

    @subsection RET_VALUE_ONLY RET_VALUE_ONLY

    This flag indicates that the function or method has no side effects; it only returns a value, for example.

    This tag is identical to @ref CONSTANT except that functions or methods tagged with \c RET_VALUE_ONLY could throw exceptions.

    @subsection CONSTANT CONSTANT

    This flag indicates that the function or method has no side effects and does not throw any exceptions.

    This tag is identical to @ref RET_VALUE_ONLY except that functions or methods tagged with \c CONSTANT do not throw exceptions.

    @subsection DEPRECATED DEPRECATED

    Code with this flag is deprecated and may be removed in a future version of this module; if a variant with this flag is resolved at parse time, a \c "deprecated" warning is raised (assuming this warning is enabled).

    @section ssh2releasenotes Release Notes

    @subsection ssh2v11 Version 1.1
    - argument error in SFTPClient disconnection with socket errors causes a crash (<a href="https://github.com/qorelanguage/qore/issues/714">issue 765</a>)
    - infinite loop in SftpPoller polling when PO_NO_PROCESS_CONTROL is not set and no sleep option is given (<a href="https://github.com/qorelanguage/qore/issues/773">issue 773</a>)
    - implement support for additional directories in SftpPoller (<a href="https://github.com/qorelanguage/qore/issues/753">issue 753</a>)
    - SftpPoller::run() cannot be synchronized (<a href="https://github.com/qorelanguage/qore/issues/798">issue 798</a>)
    - compile fixes for Solaris 10 g++ (<a href="https://github.com/qorelanguage/qore/issues/861">issue 861</a>)
    - add contructor option to SftpPoller for checking if polled directories are writable (<a href="https://github.com/qorelanguage/qore/issues/888">issue 888</a>)
    - crash in SFTPClient (<a href="https://github.com/qorelanguage/qore/issues/1040">issue 1040</a>)
    - streaming from SFTP server impossible without user re-implementing SftpPoller methods (<a href="https://github.com/qorelanguage/qore/issues/1557">issue 1557</a>)
    - fixed a bug in libssh2 library initialization error reporting (<a href="https://github.com/qorelanguage/qore/issues/1696">issue 1696</a>)

    @subsection ssh2v10 Version 1.0
    - fixed crashing bugs handling errors and handle scope in the @ref Qore::SSH2::SFTPClient "SFTPClient" class
    - added the <a href="../../SftpPoller/html/index.html">SftpPoller</a> user module
    - force socket disconnect in case of a timeout error when trying to close a file descriptor
    - socket performance instrumentation supported in the @ref Qore::SSH2::SFTPClient "SFTPClient" class
    - user modules moved to top-level qore module directory from version-specific module directory since they are valid for multiple versions of qore
    - fixed a bug where a crash would result when attempting a connection and libssh2 would not return any user authentication methods
    - implemented an automatic disconnection when timeouts occur to avoid dead connections
    - fixed crashing bugs in the @ref Qore::SSH2::SFTPClient "SFTPClient" class handling disconnect events when an sftp handle was open; the handle must be closed before the socket connection is closed or a crash will result
    - implemented the @ref Qore::SSH2::SFTPClient::retrieveFile() "SFTPClient::retrieveFile()" and @ref Qore::SSH2::SFTPClient::transferFile() "SFTPClient::transferFile()" methods
    - ported the @ref Qore::SSH2::SFTPClient "SFTPClient" class tests to QUnit and added tests for the new methods
    - ported test/sftp-poller.q to QUnit
    - fixed a bug in socket handling related to asyncronous socket event polling and select(2) and lack of socket descriptor bounds checking (<a href="https://github.com/qorelanguage/qore/issues/714">issue 714</a>)
    - requires %Qore 0.8.12+ to build (uses the new QoreValue API)

    @subsection ssh2v099 Version 0.9.9
    - closed some gaps in the non-blocking I/O solution introduced in the last release
    - implemented implicit connections for the @ref Qore::SSH2::SFTPClient "SFTPClient" class
    - implemented the @ref Qore::SSH2::SFTPClient::listFull() "SFTPClient::listFull()" method
    - implemented the @ref Qore::SSH2::SSH2Base::connected() "SSH2Base::connected()" method
    - when errors occur in the @ref Qore::SSH2::SFTPClient "SFTPClient" class, the connection is marked as closed if the connection has been terminated
    - made the current working directory in the @ref Qore::SSH2::SFTPClient "SFTPClient" class persistent across connections to better deal with implicit disconnections and reconnections
    - use keepalive by default to try and maintain persistent connections
    - released also under the MIT licenses (in addition to LGPL 2.1)

    @subsection ssh2v098 Version 0.9.8
    - default timeout of 60 seconds added to connect methods to avoid hanging connections indefinitely
    - non-blocking I/O implemented for all SFTPClient methods, default timeout set to 60s
    - send the file mode when opening files read-only in case broken servers will erroneously set the remote file's mode to 0 and then the file will not be readable
    - @ref Qore::SSH2::SFTPClient::getTextFile() "SFTPClient::getTextFile()" has a new optional parameter: encoding

    @subsection ssh2v097 Version 0.9.7
    - an exception will be thrown if a key file is set and either the public or private key is not available or readable; previously such errors would cause hard-to-debug connection problems (for instance, see: http://comments.gmane.org/gmane.network.ssh.libssh2.devel/5873; note that the patch mentioned in the linked thread was subsequently reverted)
    - fixed another deadlock in the @ref Qore::SSH2::SFTPClient::disconnect() "SFTPClient::disconnect()" method
    - minor doc updates
    - requires qore 0.8.5+ to build and run

    @subsection ssh2v096 Version 0.9.6
    - major documentation updates; now using doxygen
    - fixed a deadlock in the @ref Qore::SSH2::SFTPClient::disconnect() "SFTPClient::disconnect()" method
    - requires qore 0.8.1+ to build and run

    @subsection ssh2v095 Version 0.9.5
    - Initial release of the ssh2 module
    - Requires qore 0.8.0+ to build and run
*/