Background Enabled Methods – Using Chilkat Asynchronously
Notice: The functionality described here is deprecated and replaced by a newer model for asynchronous method calls. The newer model was introduced in Chilkat v220.127.116.11, and is identified by methods having names ending in “Async” which return a task object.
The Chilkat HTTP component has a set of methods and properties that allow already-existing methods to be called asynchronously. For example, by setting the UseBgThread property equal to True, any background-enabled method, such as Download, will run in a background thread. Normally, when called synchronously, the method returns control to the caller only after the HTTP operation has completed. However, when UseBgThread = True, the method returns immediately and the HTTP operation is started in a background thread. (For a given HTTP object instance, only one background method may be ongoing at a time. It is possible to use multiple HTTP object instances, each of which might be processing a backgrounded method call.)
The set of background-enabling methods and properties are:
- (property) UseBgThread – If True, then background-enabled methods will run in a background thread. Normally, a method will return after its work is completed. However, when UseBgThread is true, the method will return immediately and a background thread is started to carry out the method’s task.
- (property) BgTaskRunning – If True then the object instance already has a backgrounded method running. Another backgrounded method cannot be started until the 1st completes. (Multiple simultaneous background methods may run by using multiple object instances.)
- (property) BgTaskFinished – Becomes True when the background method completes. Your application would periodically check for this condition.
- (property) BgTaskSuccess – Only meaningful (True/False) after a background method completes.
- (property) BgLastErrorText – Last-error information is saved here and not in the LastErrorText property. If the background method fails, this will contain information about what transpired. (This property also contains information when the background method succeeds.)
- (method) BgTaskAbort – Call this to force the currently running backgrounded method to abort.
- (property) BgResultString – If the backgrounded method returns a string, the return value is found here.
- (property) BgResultInt – If the backgrounded method returns an integer, the return value is found here.
- (property) BgResultData – If the backgrounded method returns a byte array, the returned data is found here.
- (method) BgResponseObject – If the backgrounded method returns an HttpResponse object, it may be retrieved by calling this method.
An example of backgrounding the Download method may be found here.
Background Enabling other Chilkat Components
The HTTP component is the first Chilkat component to become background-enabled. The current development plan is to add the identical set of properties and methods to other Chilkat components to background-enable its functionality (such as for POP3, SMTP, IMAP, SSH, SFTP, Zip, MHT, etc.)