5.19.3 MIME functions

Built-in Function: boolean message_is_multipart (number nmsg)

Return true if message nmsg is a multipart (MIME) message.

Built-in Function: number message_count_parts (number nmsg)

Return number of parts in message nmsg, if it is a multipart (MIME) message. If it is not, return ‘1’.

Use message_is_multipart to check whether the message is a multipart one.

Built-in Function: number message_get_part (number nmsg, number n)

Extract nth part from the multipart message nmsg. Numeration of parts begins from ‘1’. Return message descriptor referring to the extracted part. Message parts are regarded as messages, so any message functions can be applied to them.

Built-in Function: string message_content_type (number nmsg)

Returns content type for the message nmsg. The returned string is composed of content type and subtype, delimited by slash.

If nmsg is not a multipart message, the function returns ‘text/plain’.

Several functions are provided for decoding multi-part messages. Such decoding is governed by Content-Transfer-Encoding and Content-Type headers of the message. The Content-Transfer-Encoding header defines the method used to encode the message. The value of Content-Type header is used to determine the character set the body is written in.

Basic MIME decoding facilities are provided by the built-in function message_body_to_stream, described in the previous subsection. To instruct it to decode the content, pass it the filter_chain argument beginning with the word mimedecode. The usual sequence is:

set fd open("> outfile")
message_body_to_stream(fd, msg, "mimedecode")

To ensure that the produced stream is represented in a specific character set, use the charset special filter. Its argument is the name of the character set to recode the text to:

set fd open("> outfile")
message_body_to_stream(fd, msg, "mimedecode|charset(utf-8)")

The charset filter takes also an optional second argument – a fallback method, specifying what to do when an octet sequence is encountered that cannot be represented in the requested character set. Possible values for this argument are:

‘none’

Stop further conversion and signal the e_ilseq exception.

‘copy-pass’

Copy the offending character to the output verbatim.

‘copy-octal’

Represent the offending character as a C octal sequence (‘\nnn’, where n is an octal digit). This is the default.

To decode a particular part of the message, first extract it using the message_get_part function. Recall that message parts are messages as well, and as such can be passed to message_body_to_stream. For example, the following code fragment extracts all top-level parts of a multi-part message to files named ‘part.N’:

if message_is_multipart(msg)
  set n message_count_parts(msg)
  loop for set i 1, while i <= n, set i i + 1
  do
    set fd open("> part.%i")
    message_body_to_stream(fd, message_get_part(msg, i), "mimedecode")
    close(fd)
  done
fi

The mime.mfl module provides additional functions for decoding multi-part messages:

Library Function: number message_body_decode (number nmsg; string charset, string fallback)

Decodes the body of the message (or message part) nmsg, optionally converting it to the given charset. The fallback argument specifies what to do if a byte sequence cannot be converted to the specified character set. See iconv fallback, for a detailed discussion.

The function returns a descriptor of the I/O stream that contains the decoded material. See I/O functions for a discussion of functions available for reading from it.

Library Function: number message_part_decode(number nmsg, number part; string charset, string fallback)

Decodes the body of the given part of a MIME message nmsg. The argument part is a 1-based index of the part in the message. Optional arguments charset and fallback have the same meaning as in message_body_decode (see above).

Returns a descriptor of the I/O stream that contains the decoded material.

This function is equivalent to:

message_body_decode(message_get_part(nmsg, part, charset,
                    fallback))