NAME

     immd_read_text - Reads a line of text from a  message  being
     dequeued


SYNOPSIS

     #include <imta.h>

     int immd_read_text(immd_t md, char **text);


DESCRIPTION

     Lines from a message file can be read, one  at  a  time,  by
     calling repeatedly immd_read_text().  Upon success, the line
     of text is placed in the buffer  referenced  by  text.   The
     line  is  NULL-terminated  and includes the line terminator,
     e.g. CRLF for SMTP.

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

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

     Once  all  lines  within  the  message   have   been   read,
     immd_read_text() returns 1.  That is, if two lines remain to
     be read, then the next two calls will read those  two  lines
     and  return  0  and  output a new line of text. A third call
     will not read any line and will return 1.

     immd_read_text() may be used to  read  both  message  header
     lines and the content of the message body. When this call is
     used to read the message header, then the first  blank  line
     encountered  signifies the end of the message header and the
     start of the message body. If immd_read_header() is used  to
     read  the  message  header,  then immd_read_text() will only
     read the message body and the blank line separating the mes-
     sage header from message body will not be seen.

     immd_rewind() may be called to reset the  read  position  to
     the start of the message header.


RETURN VALUES

     0 is returned if the call is successful and an line of  con-
     tent is output.

     1 is return if there are no more lines in  the  body  to  be
     read.


     Otherwise, one of the following error code 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_NO_ENVELOPE
                 All envelope recipients of the message  must  be
                 read  before starting to write the header.  Keep
                 calling immd_get_recipient() until it returns 1.

     IMRC_MESSAGE_CORRUPTED
                 It is likely that the file could not be read The
                 calling  program should then abort processing of
                 the   current   message    and    call    either
                 immd_dequeue() or immd_defer().

     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_defer(3), imta_error(3), immd_dequeue(3),
     immd_read_header(3)