Table of Contents

Name

immd_return, immd_return_add_entry - NOTARY routines

Synopsis

#include <imta.h>

int immd_return(immd_t md);

int immd_return_add_entry( immd_t md, const char *adr, const char *origadr, const char *reason, im_dlv_stat_t action);

Description

This set of functions is used by channel programs to support NOTARY, that is the generation of Delivery Status Notifications (DSN) per RFC 1891.

immd_return() enqueues a DSN addressed to the originator of the message being dequeued and, depending on the channel configuration, to the local postmaster. The DSN information is held in the dequeue context object md.

The dequeue context holds one entry per recipient for whom a DSN is needed. In other words, for each recipient and its delivery status, a return entry must be added when the delivery status matches one of the delivery statusses for whom the originator had requested a DSN for this recipient. For more details, refer to RFC 1891. immd_return_add_entry() is used to add an entry described by its address adr and original address, origadr to a return context. The addition of the first entry has also the effect of creating the return context.

immd_get_recipient() can be used to obtain the notary flags associated with each recipient. Similarly, imme_add_recipient() can be used to request a non-default DSN per recipient, when originating a message.

action specified the delivery status corresponding to the entry being added to the DSN and can be given one of the following values:

IM_DLVSTAT_BOUNCED
IM_DLVSTAT_DEFERRED
IM_DLVSTAT_DELAYED
IM_DLVSTAT_DELIVERED
IM_DLVSTAT_FAILED
IM_DLVSTAT_FORWARDED
IM_DLVSTAT_READ
IM_DLVSTAT_TIMEDOUT

reason can be used to include a more human readable explanation of the delivery status in the DSN message.

The memory allocated for DSN generation is freed automatically when calling immd_dequeue() or immd_defer().

Return Values

All these functions return IMRC_OK when successful, and one of the following error codes otherwise:

IMRC_BAD_CONTEXT
The dequeue context md has not been initialized or has been corrupted. Make sure immd_init() has been previously called.
IMRC_INVALID_DELIVERY_STATUS
The value of action passed to immd_return_list_add() does not correspond to any valid delivery status.
IMRC_NO_RECIPIENT
adr passed to immd_return_list_add() is NULL or does not correspond to any vali recipient of this message.

A textual explanation of the failure can be obtained by calling imta_error() immediately afterwards.

Attributes

center, box; c | c l | l .
Attribute Type Attribute Value
_

Architecture
sparc, x86 _ Availability SUNWimsdk _ MT-Level MT-Safe _ Interface Stability Stable

See Also

imme_add_recipient(3) , immd_get_recipient(3) , imta_error(3)

Table of Contents