A PigeonDeliver Service must be written as closely as possible to the specification described on this document.
In particular the caller of the Service will expect it to provide some methods that will be used by the caller to perform the delivery of the email.
Some of the methods are mandatory, while others are not. A mandatory method must be provided by a Service which will be considered broken/incompatible/not compliant if not.
Here is the list of methods a Service may/should provide. Mandatory methods will be indicated in the description of the method itself
load
Called when the Service is first loaded. The
caller must call this method at least and at most
once per process.
The caller must also guarantee that in a multithreaded
environment, the caller will make use of the load
method before spawning threads or performing the
required locking.
It should be used by the Service to fetch configuration parameters from the configuration file, initialize static data structures or to prepare other Services to be used.
unload
Called to cleanup the resources allocated by
each call to the load method. The unload method
is thus called as many times as the load
method.
It should be used to free up memory used
to hold configuration variables, close database
connections or free up global static structures
initialized by the load method.
After the unload method is called, all the
resources allocated by the Service must have
been freed or returned back to the operating
system.
Note also that the caller is allowed not to call the unload
method if the load method returned a NULL descriptor to
hold initialized data, since it is allowed to assume that no initialization
was performed at all.
initCalled once per caller thread (if the thread spawns threads) or anyway to initialize one of possibly multiple parallel execution of this same Service.
It should be used to initialize thread or session specific variables, like database connections or memory used by the following methods.
done
Called once for each call to the init method, in order
to free up resources allocated by the init method itself.
After each done call, all memory resources allocated by
the corresponding init method call should have been freed.
Note also that the caller is allowed not to call the done
method if the init method returned a NULL descriptor to
hold initialized data, since it is allowed to assume that no
initialization was performed at all.
del_initCalled once at the beginning of the delivery of a single mail.
Should be used to perform checks over the email (to test, for example, if the module is interested in delivering the email), or to prepare resources that will be used during the delivery itself.
del_performmandatory Called once per each recipient of a given mail.
Should be used to deliver the email itself. This method is often referred in other documents as the ``delivery'' method.
del_done
Called once after the completion of the delivery of a mail
that was previously initialized calling the del_init method.
Should be used to free up resources allocated by the del_init
method.
Please read the following sections for more detailed information about the described methods.