Inspection Routine (Sun Java System Messaging Server 6 2005Q4 MTA Developer's Reference)

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

Inspection Routine

Key to either usage mode for mtaDecodeMessage() is the inspection routine, pointed to with the inspect argument. The mtaDecodeMessage() routine presents each atomic message part to the inspection routine one line at a time. The presentation begins with the part’s header lines. Once all of the header lines have been presented, the lines of content are presented next. The following points should also be noted:

Message parts need not have any content. A common example is a single part message with no content for which the sender used the Subject: header line to express their message.
In the case of a non-multipart message, the message has a single part. The header for this sole part is the header for the message itself. As noted previously, there may or may not be any content to this single part.
In the case of a multipart message, individual parts need not have a part header. In such cases, MIME defaults apply and imply that the content is text/plain using the US-ASCII character set.
Regardless of the value of the Content-transfer-encoding: header line, the content presented will no longer be encoded.
In the case of a multipart message, the outermost header is not presented. However, it may be inspected by means of an output routine. For a discussion of the output routine, see Output Routine that follows.

The following code fragment shows the required syntax of an inspection routine:

int inspection_routine(void         *ctx,
                       mta_decode_t *dctx,
                       int           data_type,
                       const char   *data,
                       size_t        data_len);

The following table lists each of the inspection routine’s arguments, and gives a description of each.

Arguments	Description
`ctx`	The caller-supplied private context.
`dctx`	A decode context created by `mtaDecodeMessage()`. This decode context represents the current part being processed. This context is to be used with calls to the other decode routines requiring a decode context. This context is automatically disposed of by `mtaDecodeMessage()`.
`data_type`	The nature of the data being presented: For a header line: `MTA_DATA_HEADER` For a line of text-based content: `MTA_DATA_TEXT` For a line of binary content: `MTA_DATA_BINARY` No data at all: `MTA_DATA_NONE`. Atomic part content with a MIME content type of `text/` or `message/` is considered to be text-based. Such content is given the data type `MTA_DATA_TEXT`. All other atomic part content (`audio/`, `image/`, and `application/*)` is considered to be binary and denoted by the data type `MTA_DATA_BINARY`. The data type `MTA_DATA_NONE` is only presented when using an optional output routine (supplied with the `output` argument in `mtaDecodeMessage()`).
`data`	A pointer to the data being presented. Message lines will not have carriage-return or line-feed terminators, nor is the data itself NULL terminated. (However, in the case of binary data, there may be carriage returns, line feeds, or even NULLs embedded within the data itself.)
`data_len`	The length in bytes of the data being presented. This length may be `0`, which indicates a blank line and not the absence of any data (`MTA_DATA_NONE`).