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

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.