Usage Modes for mtaDecodeMessage()

There are two usage modes for mtaDecodeMessage(). In the first mode, messages are simply parsed, any encoded content decoded, and each resulting, atomic message part presented to an inspection routine. This mode of usage is primarily of use to channels which interface the MTA to non-Internet mail systems such as SMS and X.400. The second mode of operation allows the message to be rewritten after inspection. The output destination for this rewriting may be either the MTA channel queues, or an arbitrary destination via a caller-supplied output routine. During the inspection process in this second usage mode, individual, atomic message parts may be discarded or replaced with text. This operational mode is primarily of use to intermediate processing channels which need to scan message content or perform content conversions. For example, virus scanners and encryption software. A Simple Decoding Example illustrates the first usage mode, while A Simple Virus Scanner Example the second.

For the first usage mode, the calling routine must supply the following items:

1. An input source for the message.

2. An inspection routine which will be passed each atomic message part of the parsed and decoded message.

   For the second usage mode, the calling routine must supply the same two items as listed for the first usage mode, and in addition a third item must be supplied:

3. An output destination to direct the resulting message to.

The input source can be either a queued message file, represented by a dequeue context, or it can be provided by a caller-supplied input routine. Use the former when processing queued messages and the latter when processing data from disk files, data streams, or other arbitrary input sources. Since the parser and decoder require only a single, sequential pass over its input data, it is possible to stream data to mtaDecodeMessage().

The output destination can be a message being enqueued and represented either by an enqueue context, or by a caller-supplied output routine. Use an enqueue context when submitting the message to the MTA. In all other cases, use a caller-supplied output routine.

The following are some common usage cases and their associated input sources and output destinations.

• Send to the MTA (slave channel). For this case, a caller- supplied routine accepts incoming messages from a source outside of the MTA and then enqueues it to the MTA. The caller-supplied input routine is used in conjunction with an enqueue context as the output source. Doing a MIME parse and decode isn’t usually called for in this case. However, specialized services might be constructed this way. For instance, a custom server that accepts MIME formatted messages, and strips a control attachment before submitting the remainder of the message to the MTA.

• An intermediate processing channel. For this case, an example is a virus scanner that scans queued mail messages, re-enqueuing them to the MTA for delivery. In this case, a dequeue context is used as the input source and an enqueue context as the output source.

• Send from the MTA (master channel). For this case, queued messages are gatewayed to another mail system. A dequeue context is used for the input source and an output destination is often not needed; the inspection routine usually suffices. Channels of this sort are common place when interfacing Messaging Server to systems that do not support MIME and for which conversion of MIME formatted messages to other formats is required (for example, X.400 and SMS).

• A command line utility to parse a message. For this case, a caller-supplied input routine is used. No output destination is needed; an inspection routine usually suffices.