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.