NAME

     immd_read_failure_log - Reads a message delivery failure log
     from a message being dequeued.


SYNOPSIS

     #include <imta.h>

     int  immd_read_failure_log(immd_t  md,  char   **date,  char
     **text);


DESCRIPTION

     Messages may contain a delivery failure  log  detailing  why
     previous  failed  delivery attempts, if any. This log may be
     read only after the message content (headers and  body)  has
     been  read.  Upon success, the date of the failure is placed
     in the buffer referenced by date, and the  reason  for  this
     failure is placed in the buffer referenced by text.

     Each call to immd_read_failure_log() overwrites values  pre-
     viously   output  by  calls  to  immd_read_failure_log()  or
     immd_read_text().  Therefore, the contents of text and  date
     must  be copied to a buffer allocated by the caller if it is
     to be re-used after immd_read_failure_log() is again called.

     md points to the dequeue  context  initilized  earlier  with
     immd_init().  Both are NULL-terminated.  The value output by
     previous calls to immd_read_text() is lost.

     Delivery failure logs are generated with immd_defer().


RETURN VALUES

     immd_read_failure_log() returns IMRC_OK when successful.

     If no failure log is present, or if all of  them  have  been
     read, then a value of IMRC_EOF is returned.

     In the event of an error, one of the following  error  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_BODY_NOT_READ
                 The message body must be completely read  before
                 failure   logs   can   be  read.   keep  calling
                 immd_read_text() until it returns 1.

     The 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),       immd_read_text(3),        imta_error(3),
     immd_defer(3)