Sun Java System Messaging Server 6 2005Q4 MTA Developer's Reference


Read the next line of the message from the queued message file.


int mtaDequeueLineNext(mta_dq_t    *dq_ctx,
                       const char **line,
                       size_t      *len);





A dequeue context created by mtaDequeueStart().


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. 


Optional address of a size_t to receive the length of the returned line. A value of NULL may be passed for this argument.


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.

Return Values

Return Values  



Normal, successful completion. 


A NULL value was supplied for the dq_ctx call argument, or an invalid dequeue context was supplied for dq_ctx.


Message file has been completely read; no further lines to return. 


int istat;
const char *line;
size_t len;

while (!(istat = mtaDequeueLineNext(dq_ctx, &line, &len)))
     printf("%.*s\n", len, line);
if (istat != MTA_EOF)
     printf("An error occured; %s\n", mtaStrError(istat));