services -- Writing PigeonDeliver 2.0 Services
Prev		Next

7. About Methods

If you need a description on how methods are called and how methods are supposed to handle errors, please read the first few sections of this same document.

In this section we will go into details about writing each of the methods a Service should/may provide.

Please keep in mind that only few functions of the PigeonDeliver API will be discussed in the following sections. For a full list of functions, please take a look at %TODO%.

Each of the following sections information about how to declare the given method, the parameters that the caller will take care to pass and the return value it will be allowed to return.

Functions have all been declared as if they were part of the mailToMars Service. Please replace mailToMars with the name of your own module.

Error statuses, or the type dscm_mstatus_srv_e, will be discussed further in their own section %TODO%.

For a complete example of a module, please look into the sources directory, dscm/services. A good example may be the mailForward or mailAntivirus module.

7.1. load method

static dscm_mstatus_srv_e dscm_mailToMars_load(dscm_state_t *state, void **ld);

state contains the state parameter used by many of the PigeonDeliver API functions.
ld allows the function to return a custom descriptor, the load_data described in the examples in the previous sections. This descriptor is then passed over to all the other Service methods.

In case an error verifies, the function must return an error and cleanup and reset all the allocated resources, like if it was never called. It is acceptable for the caller to try to call the load method again in case of failure.

The load method can assume it will never be called with a NULL state or ld parameter, and should generate an assertion failed error in case it is.

The load method should always make use of the ld parameter. If it is left NULL, the caller can assume: that the load method was never called and the ld parameter still needs initialization or that there is no need to call other Service methods. In the rare case you don't need it, please set it to a non-zero value anyway.

7.2. unload method

static dscm_mstatus_srv_e dscm_mailToMars_unload(void **ld);

ld a pointer to the data initialized by the load method (in the examples, referred as load_data).

Although allowed, it is unacceptable for this function to fail and return an error. In case it does, however, the caller will probably die, since it couldn't free up important resources.

The unload method can assume it will never be called with a NULL ld parameter, and should generate an assertion failed error in case it is.

7.3. init method

static dscm_mstatus_srv_e dscm_mailToMars_init(void *ld, void **id, dscm_secret_t *secret);

ld a pointer to the data initialized by the load method (in the examples, referred as load_data).
id allows the function to return a custom descriptor, the init_data described in the examples in the previous sections. This descriptor is then passed over to all the other Service methods.
secret an authentication descriptor used by many PigeonDeliver API to perform authentication. This parameter may disappear in future releases of PigeonDeliver.

The init method can assume it will never be called with a NULL ld, id or secret parameter, and should generate an assertion failed error in case it is.

7.4. done method

static dscm_mstatus_srv_e dscm_mailToMars_done(void *ld, void *id);

ld a pointer to the data initialized by the load method (in the examples, referred as load_data).
id a pointer to the data initialized by the init method (in the examples, referred as init_data).

Although allowed, it is unacceptable for this function to fail and return an error. In case it does, however, the caller will probably die, since it couldn't free up important resources.

The done method can assume it will never be called with a NULL ld or id parameter, and should generate an assertion failed error in case it is.

7.5. del_init method

static dscm_mstatus_srv_e dscm_mailToMars_del_init(void *ld, void *id, void **dd, dscm_request_t *req, dscm_stream_t *stream);

ld a pointer to the data initialized by the load method (in the examples, referred as load_data).
id a pointer to the data initialized by the init method (in the examples, referred as init_data).
dd allows the function to return a custom descriptor, the del_data described in the examples in the previous sections. This descriptor is then passed over to all the other Service methods.
req a structure representing the delivery request. Used by other PigeonDeliver API to gather information about the current delivery. Although the API is not complete yet, this parameter should never be used directly by the Service.
stream a structure representing the control stream used by other PigeonDeliver API. This parameter will disappear in future version of PigeonDeliver.

The del_init method can assume it will never be called with a NULL ld, id, dd, req or stream parameter, and should generate an assertion failed error in case it is.

7.6. del_done method

static dscm_mstatus_srv_e dscm_mailToMars_del_done(void *ld, void *id, void *dd);

ld a pointer to the data initialized by the load method (in the examples, referred as load_data).
id a pointer to the data initialized by the init method (in the examples, referred as init_data).
dd a pointer to the data initialized by the del_init method (in the examples, referred as del_data).

In case this function returns an error, the caller may assume that all the resources were freed correctly but that the email could not be delivered.

The del_done method can assume it will never be called with a NULL ld, id or dd parameter, and should generate an assertion failed error in case it is.

7.7. del_perform method

static dscm_mstatus_srv_e dscm_mailToMars_del_done(void *ld, void *id, void *dd, dscm_recipient_t *rcpt, dscm_attr_t *db_attrs, int *mail_status, dscm_inject_t **inject);

ld a pointer to the data initialized by the load method (in the examples, referred as load_data).
id a pointer to the data initialized by the init method (in the examples, referred as init_data).
dd a pointer to the data initialized by the del_init method (in the examples, referred as del_data).
rcpt a pointer to a structure representing the current recipient of a mail.
db_attrs a pointer to a structure representing the configuration of the recipient the caller would like to be applied to the delivery.
mail_status while the return value of the function represents if the function itself succeeded or failed, this status indicates what sort the mail should follow once the function returns.
inject a pointer to a structure used by other PigeonDeliver API in order to allow a Service to change a mail being delivered (inject a mail in the queue).

The del_perform method can assume it will never be called with a NULL ld, id, dd, rcpt, mail_status or inject parameter, and should generate an assertion failed error in case it is. Note that db_attrs is thus allowed to be NULL.

Prev	Home	Next
Starting to write a PigeonDeliver Service		Error statuses