NAME
immd_recipient_disposition - NOTARY routine
SYNOPSIS
#include <imta.h>
int immd_recipient_disposition( immd_t d, const char *rcpt,
const char *orcpt, const char *reason, im_disp_t disp);
DESCRIPTION
This set of functions is used by channel programs to support
NOTARY, that is the generation of Delivery Status Notifica-
tions (DSN) per RFC 1891.
immd_recipient_disposition() can be used to communicate to
the mail server the delivery status of a recipient described
by its address rcpt and original address, orcpt.
The disposition disp associated with the recipient is stored
by the library so that an appropriate action can be taken
when immd_dequeue() is called.
The available values for the disposition argument, and their
effects are the following:
IM_DISP_DEFERRED The message could not be delivered to this
recipient, owing to a temporary failure.
If this is the only recipient, or if there
are no other recipient with a disposition
of IM_DISP_DEFERRED, the message will be
deferred when calling immd_dequeue(). If
there are other recipients with different
disposition, the message will be re-
enqueued for only those recipients whose
disposition is IM_DISP_DEFERRED.
IM_DISP_DELIVERED The message has been successfully
delivered for this recipient. Upon cal-
ling immd_dequeue() the message will be
removed from the queue. If requested by
the NOTARY flags, a positive message
disposition notification may be sent to
the originator. IM_DISP_FAILED The mes-
sage has been successfully delivered for
this recipient. Upon calling
immd_dequeue() the message will be removed
from the queue and returned to the origi-
nator. If requested by the NOTARY flags,
the notification will include a "delivery
failed" status for this user.
IM_DISP_RELAYED The message has been successfully relayed
to to a non-NOTARY mail component incapa-
ble of preserving the NOTARY information.
Upon calling immd_dequeue() the message
will be removed from the queue.
IM_DISP_RELAYED_FOREIGN
The message has been successfully handed
off to a non-NOTARY mail component incapa-
ble of preserving the NOTARY information.
Upon calling immd_dequeue() the message
will be removed from the queue.
IM_DISP_RETURN The message has been deemed undeliverable
for this recipient. Upon calling
immd_dequeue() the message will be removed
from the queue and returned to the origi-
nator, if requested by the NOTARY flags.
IM_DISP_TIMEDOUT The message has been deemed undeliverable
for this recipient, after unsuccessfully
attempting to deliver too many times.
Upon calling immd_dequeue() the message
will be removed from the queue and
returned to the originator, if requested
by the NOTARY flags. The notification will
include a "delivery timed out" status for
this user. If the message is re-enqueued
for some recipients, rcpt will not be a
recipient of this message.
reason can be used to include a more human readable explana-
tion of the delivery status in the DSN message.
md is the dequeue context used for this message.
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_RECIPIENT_DISPOSITION
The value of disp passed to
immd_recipient_disposition() does not correspond
to any valid delivery status.
IMRC_NO_RECIPIENT
rcpt passed to immd_recipient_disposition() is
NULL or does not correspond to any valid
recipient of this message.
A textual explanation of the failure can be obtained by cal-
ling imta_error() immediately afterwards.
ATTRIBUTES
NOTES
In a previous release of the SIMS SDK, Notary support was
implemented through the immd_return() and
immd_return_add_entry() interfaces. immd_return() and
immd_return_add_entry() are obsolete and should no longer be
used, even though binary compatibility and approximate func-
tionality are maintained in the short term. immd_return()
no longer does anything, as what it used to do is now done
by immd_dequeue(), which had to be called anyway.
immd_return_add_entry() provides approximately the same
functionality that immd_recipient_disposition() provides,
except that it takes a delivery status status as opposed to
a recipient disposition.
_______________________________________
| Attribute Type | Attribute Value|
|____________________|_________________|
| Architecture | sparc, x86 |
|____________________|_________________|
| Availability | SUNWimsdk |
|____________________|_________________|
| MT-Level | MT-Safe |
|____________________|_________________|
| Interface Stability| Stable |
|____________________|_________________|
SEE ALSO
immd_get_recipient(3), immd_dequeue(3), imta_error(3)