<<< Previous |  | Next >>>

# `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.

<<< Previous | Home | Next >>>
C/C++ namespace | Up | `mail::ACCOUNT` Synchronous API reference