The Input Source

The message to be decoded is provided as either a dequeue context or a caller-supplied routine.

Dequeue Context

When using a dequeue context, you must observe the following:

1. Pass the dequeue context from mtaDecodeStart() to mtaDecodeMessage() along with the MTA_DECODE_DQ item code.

2. The recipient list of the message being dequeued must have already been read by mtaDequeueRecipientNext() before calling mtaDecodeMessage().

3. mtaDequeueMessageFinish() must not yet have been called for the dequeue context.

After using a dequeue context with mtaDecodeMessage(), further calls to mtaDequeueRecipientNext() can’t be made. Calls to mtaDequeueLineNext() can only be performed after a call to mtaDequeueRewind().

Caller-Supplied Input Routine

To use a caller-supplied input routine, pass the address of the input routine along with the MTA_DECODE_PROC item code to mtaDecodeMessage(). In Example 5–1, the caller supplied routine's name is decode_read().

When using a caller-supplied input routine, each block of data returned by the routine must be a single line of the message. This is the default expectation of mtaDecodeMessage() and corresponds to the MTA_TERM_NONE item code. If, instead, the MTA_TERM_CR, _CRLF, _LF, or _LFCR item code are specified, then the block of data need not correspond to a single, complete line of message data; it may be a portion of a line, multiple lines, or even the entire message.

On each successful call, the input routine should return a status code of zero (MTA_OK). When there is no more message data to provide, then the input routine should return MTA_EOF. The call that returns the last byte of data should return zero; it is the subsequent call that must return MTA_EOF. In the event of an error, the input routine should return a non-zero status code other than MTA_EOF (for example, MTA_NO). This terminates the message parsing process and mtaDecodeMessage() returns an error.