Question:

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:

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).

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

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.