NAME
immd_get_message - gets the next queued message
SYNOPSIS
#include <imta.h>
int immd_get_message(immd_t md, char **from, int *size);
DESCRIPTION
immd_get_message() must be called repeatedly, once for each
message to process during a dequeue session. This is the
first step in the dequeuing process of a message.
immd_get_message() outputs the message originator's address
into the buffer referenced by from.
Each call to immd_get_message() overwrites values previously
output by calls to the same function. Therefore, the con-
tent of from must be copied to a buffer allocated by the
caller if it is to be re-used after immd_get_message() is
again called using the same dequeue context.
immd_get_message() sets size to an approximation of the size
of the message. In this release, the size can only be
approximated, and is only guaranteed to be more than half of
the total message size. md is the dequeue context output by
an earlier call to immd_init().
Once immd_get_message() has been called, the recipients can
be retrieved by calling immd_get_recipient().
RETURN VALUES
imme_get_message() returns IMRC_OK when successful, and
IMRC_EOF if there are no more queued messages to be read.
If another error has happened, one of the following return
codes is returned:
IMRC_BAD_CONTEXT
The dequeue context md has not been initialized
or has been corrupted. Make sure immd_init()
has been previously called.
IMRC_MESSAGE_LOCKED
The message is processed by another dequeue con-
text. call immd_message() again to get the next
message, or close this dequeue context by cal-
ling immd_end().
IMRC_MESSAGE_CORRUPTED
The message file could not be read, because it's
missing critical information, it is already
deleted or it's missing both message header and
message body. This can happen because the file
has not been completely written to disk or con-
secutively to a hardware failure. The calling
program should then abort processing of the
current message and call either immd_defer() or
immd_dequeue() if the problem appears to be per-
manent.
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_recipient(3)