test

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

mtaDecodeMessagePartDelete()

Prevent a message part from being written or replace it with a text part.

Syntax


int mtaDecodeMessagePartDelete(mta_decode_t *dctx,
                               int           item_code, ...);

Arguments

Arguments  

Description  

dctx

A decode context created by mtaMessageDecode().

item_code

An optional list of item codes. See the description section that follows for a list of item codes. The list must be terminated with an integer argument with value 0.

Description

When an output routine is used in conjunction with mtaDecodeMessage(), the inspection routine may discard the current message part by calling this routine. As an alternative to discarding the part, it may be replaced with a part containing caller-supplied data such as a warning message. This replacement is achieved through the use of item codes.

Once mtaDecodeMessagePartDelete() has been called, the inspection routine will no longer be called for that message part. As such, calling the routine is final and cannot be undone short of cancelling the entire message decode operation itself (for example, by having the caller-supplied read routine return an error, or after mtaDecodeMessage() completes, cancelling the dequeue and enqueue operations with mtaDequeueMessageFinish() and mtaEnqueueFinish()).

The following table lists the item codes for this routine, any additional item code arguments each item code requires, and gives a description of each.

Item Codes  

Additional Arguments  

Description  

MTA_DECODE_CCHARSET

const char *charset

size_t charset_len

Specify the character set used for the message part (for example, us-ascii, iso-8859-1). This item code must be followed by two additional call arguments:

  1. The name of the character set

  2. The length in bytes of that name

    If a value of zero is passed for the length, then the name must be NULL terminated.

MTA_DECODE_CDISP

const char *disposition

size_t disposition_len

Specify the content disposition for the message part (for example, inline, attachment; filename=a.doc). This disposition information will be placed in a Content-disposition: header line. The item code must be followed by two additional call arguments:

  1. The disposition string

  2. The length in bytes of that string

    If a value of zero is passed for the length, then the disposition string must be NULL terminated.

MTA_DECODE_CLANG,

const char *language

size_t language_len

Specify the language used for the message part (for example, en, fr). This language information will be placed in a Content-language: header line. The item code must be followed by two additional call arguments:

  1. The language string

  2. The length in bytes of that string.

    If a value of zero is passed for the length, then the string must be NULL terminated.

MTA_DECODE_CSUBTYPE

const char *subtype

size_t subtype_len

Specify the content subtype for the message part (for example, plain or html for text/plain or text/html). This subtype information will be combined with the type and charset information and placed in a Content-type: header line. The item code must be followed by two additional call arguments:

  1. The language string

  2. The length in bytes of that string.

    If a value of zero is passed for the length, then the string must be NULL terminated.

MTA_DECODE_CTYPE

const char *type

size_t type_len

Specify the major content type for the message part (for example, text for text/plain or text/html). This major type information will be combined with the subtype and charset information and placed in a Content-type: header line. The item code must be followed by two additional call arguments:

  1. The language string

  2. The length in bytes of that string.

    If a value of zero is passed for the length, then the string must be NULL terminated.

MTA_ITEM_LIST

mta_item_list_t *item_list

Specify a pointer to an item list array. The item list array must be terminated with a final array entry with an item code value of 0. For further information on item lists, see Item Codes and Item Lists.

MTA_REASON

const char *text

size_t text_len

Specifies the content and length of caller-supplied text or data used to replace the deleted message part. 

The item code must be followed by two additional call arguments: 

  1. The language string

  2. The length in bytes of that string.

    If a value of zero is passed for the length, then the string must be NULL terminated.

Return Values

Return Values  

Description  

0

Normal, successful completion. 

MTA_BADARGS

Returned for one of two reasons: 

  1. A NULL value was supplied for the dctx call argument, an invalid decode context was supplied for dctx.

  2. A required argument to an item code was NULL.

MTA_NO

Returned for one of two reasons: 

  1. Invalid call. Either no output routine is being used, or the call was made from the output routine itself.

  2. Output errors encountered while attempting to write the output.

MTA_NOSUCHITEM

An invalid item code was specified. 

Example

The following code fragment shows how the routine is used to discard the message part:

mtaDecodeMessagePartDelete(dctx, 0);

The following code fragment shows how to replace the message part with a text warning:


mtaDecodeMessagePartDelete(dctx,
    MTA_REASON, "Warning: virus infected message part was
                 discarded.", 0,”
    MTA_DECODE_CLANG, "en", 2,
    MTA_DECODE_CCHARSET, "us-ascii", 8, 0);

The following code fragment shows the output generated by the preceding code example.


Content-type: text/plain; charset=us-ascii
Content-language: en

Warning: virus infected message part was discarded.

See also Example 5–2.