Download Sun Java System Messaging Server 6 2005Q1 MTA Developer`s

mtaDequeueLineNext
Syntax
int mtaDequeueLineNext(mta_dq_t
*dq_ctx,
const char **line,
size_t
*len);
Arguments
Arguments
Description
dq_ctx
A dequeue context created by mtaDequeueStart().
line
Optional address of a pointer to receive the address of the next line of the
message. The line will not be NULL terminated. A value of NULL may be passed
for this argument.
len
Optional address of a size_t to receive the length of the returned line. A value of
NULL may be passed for this argument.
Description
After exhausting a message’s list of envelope recipients by repeated calls to
mtaDequeueRecipientNext(), begin reading the message’s header and content with
mtaDequeueLineNext(). Each call will return one line of the message, with the first
call returning the first line of the message, the second call the second line, and so
on. Once the message has been completely read, the status code MTA_EOF will be
returned.
The returned lines of the message will not be NULL terminated. This is because the
underlying message file is often mapped into memory. When that is the case, then
the returned pointer is a pointer into that memory map. Since the message files
themselves do not contain NULL terminators and the file is mapped read-only, it is
not possible for the SDK to add a NULL terminator to the end of the line without
copying it first to a writable portion of memory.
The returned lines of the message will not have any line terminators such as a line
feed or a carriage return. It is up to the calling routine to supply whatever line
terminators might be appropriate (for example, adding a carriage-return line-feed
pair when transmitting the line over SMTP.)
It is possible to call mtaDequeueLineNext() with NULL values for both the line and
len call arguments. But this is of limited use; one example is when writing a
channel that deletes all queued messages after first counting the number of lines in
each message for accounting purposes. More typical of such a channel would be to
supply NULL for the line argument but pass a non-zero address for the len
argument. That would then allow the channel to count up the number of bytes in
the deleted message.
Chapter 6
MTA SDK Reference
161