PercentDone callback counts as an AbortCheck

Question:

“I’ve got the Chilkat C++ libs linked with my project, and am using the HTTP classes successfully.
One thing is confusing me, though. I’ve derived a class from CkHttpProgress.h and overridden AbortCheck(…) to provide cancellation support. However, AbortCheck(…) never gets called. At first, I thought perhaps the HTTP retrieval was occurring too quickly, so I set the “HeartbeatMs” property to “1”, and it still never gets called.
I know the assignment of the callback class is working, because if I override PercentDone(…), it does indeed get called.
Is it possible that my use of the HTTP QuickGetStr(…) method does not support the AbortCheck(…) callback? I’m (successfully) reading a small XML file from a web server in close proximity to the client.”

Answer:
The PercentDone callback method also has an “abort” argument, so it may also be used to abort a method while in progress.  In cases where the PercentDone callback provides abort capability, it counts as an AbortCheck callback — to prevent too many callbacks from bombarding your application.
Therefore, if HeartbeatMs is set to 100ms, and a PercentDone callback is fired, then the timer for the next AbortCheck callback is reset.  The entire operation could be short enough such that all of the callbacks are PercentDone callbacks, and AbortCheck never gets called.  The AbortCheck callback would only be called when the elapsed time between 1% completion intervals exceeds the HeartbeatMs.

AbortCheck Event in Chilkat .NET Components

The AbortCheck event is standard in Chilkat .NET classes that involve communications over sockets (FTP, POP3, SMTP, IMAP, HTTP, etc.) or time-consuming operations such as zipping/unzipping large files. There are three steps to using AbortCheck:

1. Enable event callbacks by setting the EnableEvents property = true.

Chilkat.MailMan mailman = new Chilkat.MailMan();
mailman.EnableEvents = true;

2. Set the HeartbeatMs property. The HeartbeatMs property is the number of milliseconds between each AbortCheck callback. The default value is 0 to indicate that no AbortCheck events will be fired. You must set the HeartbeatMs property to a non-zero value to receive AbortCheck events. For example, a value of 100 sends 10 events per second.

mailman.HeartbeatMs = 100;

3. Add a handler for OnAbortCheck. To do this, (in C#) begin typing “mailman.OnAbortCheck +=” and a tooltip will appear, as shown below:

OnAbortCheck

Press the TAB character to complete the statement. Press the TAB character again to auto-generate the event handler code, which now looks like this:

        private void AbortTest()
        {
            Chilkat.MailMan mailman = new Chilkat.MailMan();
            mailman.EnableEvents = true;

            mailman.HeartbeatMs = 100;
            mailman.OnAbortCheck += new Chilkat.MailMan.AbortCheckEventHandler(mailman_OnAbortCheck);
        }

        void mailman_OnAbortCheck(object sender, Chilkat.AbortCheckEventArgs args)
        {
            throw new Exception("The method or operation is not implemented.");
        }

The mailman_OnAbortCheck event handler is now called once every 100 milliseconds during any POP3 or SMTP operation that involves communication with the server. You may abort by setting args.Abort = true. For example:

        void mailman_OnAbortCheck(object sender, Chilkat.AbortCheckEventArgs args)
        {
            bool bAbort = false;
            // Add code here to determine whether the in-progress operation should be aborted.
            // If so, set args.Abort = true
            if (bAbort) args.Abort = true;
        }

Important: Many Chilkat methods allow for percent-done progress monitoring. Percent-done event callbacks also provide the ability to abort an operation. Therefore, AbortCheck events are suppressed when the frequency of percent-done callbacks is greater than the HeartbeatMs. The reason for this is to prevent too many callbacks from disrupting performance. If you used both percent-done and AbortCheck events, you should also code for aborting from the percent-done event.

Creating a VB.NET Event Handler for AbortCheck

In VB.NET, the object must not be declared as a local variable. It must be declared “WithEvents”, typically as a member of the Form. Then select the data member (as shown below) to get a list of events (in the “Declarations” combo-box to the right).

VB.NET AbortCheck

Finally, select the event from the combo box (you should see the various events listed) and let Visual Studio generate your event handler code…

Can Ftp2.SyncLocalTree be progress monitored?

The FTP2 component’s SyncLocalTree method downloads an entire directory tree from an FTP server to the local filesystem. There are several modes of operation:

mode=0: Download all files
mode=1: Download all files that do not exist on the local filesystem.
mode=2: Download newer or non-existant files.
mode=3: Download only newer files. If a file does not already exist on the local filesystem, it is not downloaded from the server.

It is possible to monitor activity via the AbortCheck event. The AbortCheck event is called periodically according to the HeartbeatMs property setting. The AbortCheck callback method has one argument: an output-only “abort” flag. If set to true (non-zero), the FTP2 component will abort the SyncLocalTree.

It is not possible to monitor a percentage completion (i.e. 0% to 100%). The reason is that it is impossible to know the full extent of the remote directory tree and files to be downloaded. There is nothing in the FTP protocol that allows a client to ask the server to “give me the sum of the sizes of all files in a directory tree”. The SyncLocalTree works by traversing the directory tree through a series of “change directory” commands, downloading files in each directory found, etc.