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)