More on FlowSshCpp

FlowSshCpp users have to include a single header file, namely FlowSshCpp.h. The following is its include dependency graph.

As apparent from the above graph, FlowSshCpp relies on FlowSshC as the underlying implementation. Further, FlowSshCpp uses some STL features, such as string, vector, and exception. In FlowSshCpp's interface there are only Unicode character strings; usually wchar_t* is used for parameters, and std::wstring where string values are returned. All exceptions thrown by the library are derived from FlowSshCpp::Exception, which itself derives from std::exception. Finally, std::vector is used for returning file listings from ClientSftpChannel.

With FlowSshCpp, your very first line of code will always be an Initializer. It takes an ErrorHandler as a parameter; in turn this ErrorHandler is invoked when there is an uncaught exception in any other handler. Take a look at the Initializer API for more details. At this point, just remember that there must always be one and only one Initializer for your application, and that it must be instantiated before using any other SSH functionality.

FlowSshCpp classes can be divided into two groups.

• Main classes: Keypair, PublicKey, Client, ClientSessionChannel, ClientSftpChannel
• Handler classes: ErrorHandler, ProgressHandler, ReceiveHandler, RealPathHandler, StatHandler, SftpHandler, ListHandler, TransferHandler

Note that these classes are reference counted. The following usage guidelines apply:

1. Always create them on the heap (dynamic allocation).
2. Never delete them. They provide AddRef and Release calls similar to those found in COM objects. FlowSshCpp will automatically destroy these objects after their reference count drops to 0.
   Important: These objects are destroyed when both the user and the library have released them. When the user releases an object before the library does, the object will continue to exist until it is released by the library. During this time, its handlers may still be called.
3. Use our convenient RefPtr template. Example:
       RefPtr<Client> client(new Client);
   RefPtr manages the necessary AddRef and Release calls of the wrapped object. On occasions where you cannot use RefPtr be sure to call AddRef and Release as appropriate.

Handler methods will only be called on objects that are active. Handler objects are said to be active when they are in progress, this is between and including their OnStart and OnDone calls. Clients are active if they are either connected or connecting. Similarly, channels are active if they are open or opening. The global error handler is active as long as there is an active client or channel.

Handler classes have two methods in common, namely OnStart and OnDone. OnStart is called when an operation starts and OnDone as soon as it completes.

Active handler objects are guaranteed to exist even without the user explicitly referencing them. This means that you can start several requests and forget about them until their OnDone is called. This works because OnStart implicitly increases a handler objects reference count; and after calling OnDone, FlowSshCpp decreases the reference count again. An active handler object also implicitly references the associated main object, and prevents it from being destroyed prematurely in the middle of a request.

Note that you cannot use MFC from within your handler overrides. This is because handler methods get invoked by ordinary Win32 threads which lack the necessary MFC initializations.