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.
|
<<< Previous | Home | Next >>> |
C/C++ namespace | Up | mail::ACCOUNT Synchronous API reference |