NAME
immd_get_recipient - accessing envelope recipients
SYNOPSIS
#include <imta.h>
int immd_get_recipient(immd_t md, int *flags, char **rcpt,
char **orcpt);
int immd_rewind_recipients(immd_t md);
void *immd_get_recipient_data(immd_t md);
void immd_set_recipient_data(immd_t md, void *data);
DESCRIPTION
immd_get_recipient() is used to retrieve envelope recipients
attached to a message. As each call to immd_get_recipient()
retrieves at most one recipient, this function much be
called repeatedly, until all recipients have been retrieved.
Envelope recipients can be retrieved after opening the mes-
sage with immd_get_message() and before starting to read the
contents of the message (headers, body). After all
addresses have been retrieved, immd_get_recipient() returns
IMRC_EOF. For example, if the message envelope has two
envelope recipients, then three calls to
immd_get_recipient() should be made. The first two calls
will retrieve the recipients and return IMRC_OK. The third
will not retrieve any recipient and will return IMRC_EOF.
In some cases though, it is convenient for calling programs
to browse the envelope recipient list later on in the mes-
sage processing. If that is the case,
immd_rewind_recipients() must be called to rewind the reci-
pient list prior to accessing it, so that subsequent calls
to immd_get_recipient() can be used to retrieve all reci-
pients, as explained above.
To further reduce the need for the caller to create and
maintain their own recipient list, the entry points
immd_set_recipient_data() and immd_get_recipient_data() can
be used to respectively set and access caller-specific data
attached to one recipient. Either of these calls apply to
the last recipient returned by immd_get_recipient().
The final (rewritten) form of the recipient's address is
placed in a buffer referenced by rcpt.
The orcpt gives, if known, the original form of the envelope
To: address. This is useful when dealing with messaging for-
mats such as X.400 which retain such information. When re-
enqueuing a message, this information can be subsequently
passed back into imme_add_recipient() and otherwise used or
discarded as appropriate.
The memory to allocated by the library to store these
addresses is valid until immd_dequeue(), immd_end(),
immd_get_message(), or immd_defer() is called.
md is the dequeue context output by an earlier call to
immd_init() .
flags is set by the library to the notary flags for this
recipient the value is a bitwise OR of zero or more of the
following constants.
IM_NOTIFY_FAILURE A DSN is requested if the delivery
fails permanently
IM_NOTIFY_SUCCESS A DSN is requested if the delivery is
successful
IM_NOTIFY_DELAY A DSN is requested if the delivery
fails temporarily
IM_NOTIFY_NEVER no DSN is requested whatsoever
RETURN VALUES
IMRC_OK The call is successful and an address is output.
IMRC_EOF There are no more addresses to read.
IMRC_BAD_CONTEXT
The dequeue context md has not been initialized
or has been corrupted. Make sure immd_init()
has been previously called.
IMRC_NO_MESSAGE
No message is currently processed. make sure
the previous call to immd_get_message() returned
successfully.
IMRC_MESSAGE_CORRUPTED
it is likely that the file could not be read,
because it was deleted or because it's missing
both message header and message body. This can
happen consecutively to a hardware failure.
The calling program should then abort processing of the
current message and call either immd_dequeue() or
immd_defer(). In this particular case, both calls have the
same effect.
A textual version reason for the failure can be obtained by
calling imta_error() immediately afterwards.
ATTRIBUTES
_______________________________________
| Attribute Type | Attribute Value|
|____________________|_________________|
| Architecture | sparc, x86 |
|____________________|_________________|
| Availability | SUNWimsdk |
|____________________|_________________|
| MT-Level | MT-Safe |
|____________________|_________________|
| Interface Stability| Stable |
|____________________|_________________|
SEE ALSO
immd_init(3), imta_error(3), immd_get_message(3)