Table of Contents

Name

immd_get_recipient - Obtain the next envelope To: address from a message.

Synopsis

#include <imta.h>

int immd_get_recipient(immd_t md, int *flags, char **adr, char **origadr);

Description

immd_get_recipient() should be called repeatedly to obtain each envelope To: address from a message. The address is placed in a buffer referenced by adr . For each call, a single envelope To: address will be returned in address.

Each call to immd_get_recipient() overwrites values previously output by calls to the same function. Therefore, the contents of adr or origadr must be copied to a buffer allocated by the caller if it is to be re-used after immd_get_recipient() is again called.

md is the dequeue context output by an earlier call to immd_init() .

After all addresses have been output, immd_get_recipient() will return IMRC_EOF. For example, if the message envelope has two To: addresses, then three calls to immd_get_recipient() should be made. In the first two calls, the two addresses will be output along with the return IMRC_OK. In the third call no address will be output and IMRC_EOF will be returned. After all of the envelope To: addresses have been read, the message header and body may be read with immd_read_header() and/or immd_read_text() .

The origadr gives, if known, the original form of the envelope To: address. This is useful when dealing with messaging formats 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 otherwised used or discarded as appropriate.

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_read_header(3)

Table of Contents