The LibMAIL library provides two alternative interfaces: called the “native” and the “synchronous” interfaces (API). The native API is based on two fundamental objects: mail::account - an “account”; and mail::folder - a “folder”. The syncronous API uses mail::ACCOUNT objects instead of mail::account objects; the synchronous API also uses mail::folder objects, but they are used in a different manner: instead of invoking mail::folder's methods, the synchronous API provides additional mail::ACCOUNT methods that take a mail::folder object as an additional parameter.
Both APIs fulfill the same function, but use fundamentally
different approaches. The synchronous, mail::ACCOUNT-based API, is a traditional,
function-oriented interface: each function completes its given
task, and returns. The native, mail::account-based API uses an
event-driven paradigm. mail::account (and mail::folder) methods receive a
mail::callback object, or one
of its subclasses, as an extra parameter. The methods always
return immediately, without waiting for the requested operation
to complete. The mail::callback
object has two methods: success
and fail. One of these methods
will be invoked when the original task is completed.
In some cases it's possible that the requested task can be completed immediately, but this mechanism is still used: the callback method will be invoked before the original method returns to the application, instead of afterwards.
The native API is designed for interactive, event-driven applications. The application's main event loop should invoke the mail::account::process(3x) method. This method checks all pending requests, and invokes the completed requests' callback methods.
The native API is not convenient for single-purpose command line based mail processing tools . That's the purpose of the alternative mail::ACCOUNT-based API. The mail::ACCOUNT synchronous API is designed specifically for single-purpose command line tools. It should NOT be used by interactive, event-driven applications. This is because open mail accounts usually require some sort of periodic, regularly-scheduled processing (such as checking for new mail). This processing is automatically handled by mail::account::process(3x). An interactive application that uses the synchronous API will exhibit random failures because it will be regularly disconnected from mail servers, for inactivity, when no mail processing occurs for a significant period of time.
The synchronous API is really nothing more than a small wrapper around the native API. mail::ACCOUNT methods closely parallel their equivalent mail::account-based methods. A given mail::ACCOUNT method is implemented by creating a callback object, invoking the corresponding mail::account (or mail::folder) method, then repeatedly calling mail::account::process(3x), until the callback object is invoked.