NAME
immd_defer - Defers a message for later processing.
SYNOPSIS
#include <imta.h>
int immd_defer(immd_t md, int increment, char *reason);
DESCRIPTION
immd_defer() provides a simple way to defer a message for
all recipients. The same behavior can be obtained by setting
the disposition to IM_DISP_DEFERRED for all recipient while
calling immd_recipient_disposition().
immd_recipient_disposition() must be used when deferrinfg a
message for only some of the recipients.
The deferred message will be left in the message queues for
processing by a subsequent processing job. If the message
continues to remain in the message queues long enough, it
will be returned automatically. See the message return and
bouncing discussions in the "SIMS Administrator's Guide" for
further details on this subject.
Typically message processing is deferred when a temporary
error (e.g., network link down, etc.) or an unexpected error
affecting the message as a whole occurs. In the event of a
permanent error, the disposition of each and every recipient
should be set to an appropriate value using
immd_recipient_disposition().
Each time a message is deferred, an explanation of why the
message is being deferred may be placed in the message's
"delivery failure log". This failure log can be read with
immd_read_failure_log() when the previously deferred message
is again accessed. Should the message be returned as an
undeliverable message by SIMS's MTA, a copy of the log will
be included with the returned message. The log is only gen-
erated if you specify the reason argument. If this parame-
ter is never used for a given message, then that message
will have no delivery failure log. increment Specifies
whether or not the message retry count should be incre-
mented. When reason is specified (not NULL), this argument
is ignored and the message retry count incremented. No firm
guidelines exist to determine when the retry count should or
should not be incremented. In general, however, it should be
incremented. This helps postmasters to spot messages which
have defied delivery.
RETURN VALUES
immd_defer() 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 imme_init()
has been previously called.
IMRC_TEXT_TRUNCATED
The reason string contained more than IM_LOG_LEN
characters, so it has been truncated to fit.
ATTRIBUTES
_______________________________________
| Attribute Type | Attribute Value|
|____________________|_________________|
| Architecture | sparc, x86 |
|____________________|_________________|
| Availability | SUNWimsdk |
|____________________|_________________|
| MT-Level | MT-Safe |
|____________________|_________________|
| Interface Stability| Stable |
|____________________|_________________|
SEE ALSO
immd_init(3), immd_recipient_disposition(3), imta_error(3),
immd_read_failure_log(3)