LibMAIL APIs

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.

NOTE:

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.

NOTE:

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.