ListHandler Class

[C++]

class ListHandler : public HandlerBase (.. public RefCountable, public NoCopy)
{
public:
  bool Success() const;
  std::vector<FileInfo> const& GetFileInfos() const;
  ListErr GetError() const;

protected:
  virtual void OnStart();
  virtual void OnDone();
  virtual void OnList(std::vector<FileInfo> const& fileInfos, bool endOfList);
  virtual void OnError(ListErr const& error);
}

[C#]

public class ListHandler : IDisposable, HandlerBase (.. WaitImpl)
{
  public ListHandler(bool useGetFileInfos);
  
  public bool Success { get; }
  public FileInfo[] GetFileInfos();
  public ListErr GetError();
  
  public event StartEventHandler OnStart;
  public event DoneEventHandler OnDone;
  public event ListEventHandler OnList;
  public event ListErrorEventHandler OnError;
  
  public override sealed bool IsDisposed { get; }
  public override sealed void Dispose();
}

Members

[.NET] Constructor Parameters

• useGetFileInfos:
  true: The handler object should internally store all file listings. You can retrieve the list with GetFileInfos() once OnDone is called.
  false: You will not use GetFileInfos().

General

• Success: Request completed successfully?
• GetFileInfos: Returns an array of type FileInfo with information about files and directories for the requested listing.
• GetError: Returns a ListErr.

Overrides and Events

• OnStart: The first override/event being invoked for a request. *
• OnDone: The last override/event being invoked for a request. *
• OnList: Can be called multiple times. Return false to abort the listing.
  Parameters:
  • fileInfos: See GetFileInfos(). If called multiple times, only a part of the final array is passed by each call here.
  • endOfList: If endOfList=true, then this is the last call.
• OnError: Invoked for a failed request.
  Parameters:
  • error: See GetError().

[.NET] Disposing

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

Remarks

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

This handler is used with the [ClientSftpChannel]List request.

[C++] The default implementation stores all file listings to m_fileInfos. You can retrieve the list with GetFileInfos once OnDone is called. If you don't need this functionality, override OnList with your own implementation. **

[.NET] Use useGetFileInfos to specify if GetFileInfos will be used or not. **

* [C++] Always call the base class implementation from your override.
** If GetFileInfos is used: Keep in mind that for large folders quite some memory might be occupied by the handler object to hold all listing entries.