ProgressHandler Class

[C++]

class ProgressHandler : public HandlerBase (.. public RefCountable, public NoCopy)
{
public:
  bool Success() const;
  unsigned int GetTaskState() const;
  unsigned int GetTaskSpecificStep() const;
  std::wstring GetAuxInfo() const;

protected:
  virtual void OnStart();
  virtual void OnDone();
  virtual void OnProgress(unsigned int taskSpecificStep);
  virtual void OnSuccess();
  virtual void OnError(unsigned int taskSpecificStep, std::wstring const& auxInfo);
}

[C#]

public class ProgressHandler : IDisposable, HandlerBase (.. WaitImpl)
{
  public bool Success { get; }
  public public TaskState GetTaskState();
  public uint GetTaskSpecificStep();
  public string GetAuxInfo();
  
  public event StartEventHandler OnStart;
  public event DoneEventHandler OnDone;
  public event ProgressEventHandler OnProgress;
  public event SuccessEventHandler OnSuccess;
  public event ProgressErrorEventHandler OnError;
  
  public override sealed bool IsDisposed { get; }
  public override sealed void Dispose();
}

Members

General

• Success: Request completed successfully?
• GetTaskState: Returns a TaskState enumeration.
• GetTaskSpecificStep: May return a ConnectStep or ClientSftpChannelOpenStep enumeration. **
• GetAuxInfo: Returns an auxiliary info string. For failed requests this is a human-readable error description. Otherwise it is an empty string.

Overrides and Events

• OnStart: The first override/event being invoked for a request. *
• OnDone: The last override/event being invoked for a request. *
• OnProgress: Invoked for [Client]Connect and [ClientSftpChannel]Open requests in order to report intermediate steps. These steps are reported right before they are processed.
  Parameters:
  • taskSpecificStep: See GetTaskSpecificStep().
• OnSuccess: Invoked when the request was successful.
• OnError: Invoked for a failed request.
  Parameters:
  • taskSpecificStep: See GetTaskSpecificStep().
  • auxInfo: See GetAuxInfo().

[.NET] Disposing

• IsDisposed: Is the object disposed?
• Dispose: Release all resources used by the object.

Remarks

ProgressHandler is a base class which must be derived to use. Either derive and implement your own OnDone() method, or use pre-made derived classes ProgressEvent or ProgressMsg (for Win32 graphical applications). If you use ProgressEvent, call WaitDone() or wait for GetDoneEvent() before checking the result.

This handler is used with with a variety of [C++/.NET] requests to track their progress.

* [C++] Always call the base class implementation from your override.
** TaskSpecificStep only makes sense for the [Client]Connect and [ClientSftpChannel]Open requests. For all other requests it is irrelevant (the value is zero or undefined) and should not be evaluated.