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)