Mailfromd Manual (split by section):   Section:   Chapter:FastBack: Library   Up: Library   FastForward: Using MFL Mode   Contents: Table of ContentsIndex: Concept Index

5.15 Message Functions

The functions described below retrieve information from RFC822 messages. The message to operate upon is identified by its descriptor, an integer number returned by the previous call to mailbox_get_message (see mailbox_get_message) or current_message (see current_message) function. The maximum number of message descriptors is limited by 1024. You can change this limit using the max-open-messages runtime configuration statement (see max-open-messages).

Built-in Function: number message_size (number nmsg)

Return the size of the message nmsg, in bytes. Notice, that if nmsg refers to current message (see current_message), the returned value is less than the size seen by the MTA, because mailfromd recodes CR-LF sequences to LF, i.e. removes carriage returns (ASCII 13) occurring before line feeds (ASCII 10. To obtain actual message length as seen by the MTA, add the number of lines in the message:

  set actual_length message_size(nmsg) + message_lines(nmsg)
Built-in Function: boolean message_body_is_empty (number nmsg)

Returns true if the body of message nmsg has zero size or contains only whitespace characters. If the ‘Content-Transfer-Encoding’ header is present, it is used to decode body before processing.

Built-in Function: void message_close (number nmsg)

Close the message identified by descriptor nmsg.

Built-in Function: number message_lines (number nmsg)

Return total number of lines in message nmsg. The following relation holds true:

message_lines(x) = message_body_lines(x)
                         + message_header_lines(x) + 1
Built-in Function: string message_read_line (number nmsg)

Read and return next line from the message nmsg. If there are no more lines to read, raise the eof exception.

Use message_rewind to rewind the message stream and read its contents again.

Built-in Function: void message_rewind (number nmsg)

Rewind the stream associated with message referred to by descriptor nmsg.

Built-in Function: number message_from_stream (number fd; string filter_chain)

Converts contents of the stream identified by fd to a mail message. Returns identifier of the created message.

Optional filter_chain supplies the name of a Mailutils filter chain, through which the data will be passed before converting. See http://mailutils.org/wiki/Filter_chain, for a description of filter chains.

Built-in Function: void message_to_stream (number fd, number nmsg; string filter_chain)

Copies message nsmg to stream descriptor fd. The descriptor must be obtained by a previous call to open.

Optional filter_chain supplies the name of a Mailutils filter chain, through which the data will be passed before writing them to fd. See http://mailutils.org/wiki/Filter_chain, for a description of filter chains.

5.15.1 Header functions

Built-in Function: number message_header_size (number nmsg)

Return the size, in bytes of the headers of message nmsg. See the note to the message_size, above.

Built-in Function: number message_header_lines (number nmsg)

Return number of lines occupied by headers in message nmsg.

Built-in Function: number message_header_count (number nmsg, [string name])

Return number of headers in message nmsg.

If name is supplied, count only headers with that name.

Built-in Function: string message_find_header (number nmsg, string name [, number idx])

Return value of header name from the message nmsg. If the message contains several headers with the same name, optional parameter idx may be used to select one of them. Headers are numbered from ‘1’.

If no matching header is not found, the not_found exception is raised. If another error occurs, the failure exception is raised.

The returned string is a verbatim copy of the message contents (except for eventual CR-LF -> LF translation, see above). You might need to apply the unfold function to it (see unfold).

Built-in Function: string message_nth_header_name (number nmsg, number n)

Returns the name of the nth header in message nmsg. If there is no such header, e_range exception is raised.

Built-in Function: string message_nth_header_value (number msg, number n)

Returns the value of the nth header in message nmsg. If there is no such header, e_range exception is raised.

Built-in Function: boolean message_has_header (number nmsg, string name [, number idx])

Return true if message nmsg contains header with the given name. If there are several headers with the same name, optional parameter idx may be used to select one of them.

5.15.2 Message body functions

Built-in Function: number message_body_size (number nmsg)

Return the size, in bytes, of the body of message nmsg. See the note to the message_size, above.

Built-in Function: number message_body_lines (number nmsg)

Return number of lines in the body of message referred to by descriptor nmsg.

Built-in Function: void message_body_rewind (number nmsg)

Rewind the stream associated with the body of message referred to by descriptor nmsg.

A call to message_body_read_line (see below) after calling this function will return the first line from the message body.

Built-in Function: string message_read_body_line (number nmsg)

Read and return next line from the body of the message nmsg. If there are no more lines to read, raise the eof exception.

Use message_body_rewind (see above) to rewind the body stream and read its contents again.

Built-in Function: void message_body_to_stream (number fd, number nmsg; string filter_chain)

Copies the body of the message nsmg to stream descriptor fd. The descriptor must be obtained by a previous call to open.

Optional filter_chain supplies the name of a Mailutils filter chain, through which the data will be passed before writing them to fd. oSee http://mailutils.org/wiki/Filter_chain, for a description of filter chains.

5.15.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.

5.15.4 Message digest functions

Message digests are specially formatted messages that contain certain number of mail messages, encapsulated using the method described in RFC 934. Such digests are often used in mailing lists to reduce the frequency of sending mails. Messages of this format are also produced by the forward function in most MUA’s.

The usual way to handle a message digest in MFL is to convert it first to a MIME message, and then to use functions for accessing its parts (see MIME functions).

Built-in Function: number message_burst (number nmsg ; number flags)

Converts the message identified by the descriptor nmsg to a multi-part message. Returns a descriptor of the created message.

Optional argument flags controls the behavior of the bursting agent. It is a bitwise OR of error action and bursting flags.

Error action defines what to do if a part of the digest is not in RFC822 message format. If it is ‘BURST_ERR_FAIL’ (the default), the function will raise the ‘e_format’ exception. If onerr is ‘BURST_ERR_IGNORE’, the improperly formatted part will be ignored. Finally, the value ‘BURST_ERR_BODY’ instructs message_burst to create a replacement part with empty headers and the text of the offending part as its body.

Bursting flags control various aspects of the agent behavior. Currently only one flag is defined, ‘BURST_DECODE’, which instructs the agent to decode any MIME parts (according to the ‘Content-Transfer-Encoding’ header) it encounters while bursting the message.

Parts of a message digest are separated by so-called encapsulation boundaries, which are in essence lines beginning with at least one dash followed by a non-whitespace character. A dash followed by a whitespace serves as a byte-stuffing character, a sort of escape for lines which begin with a dash themselves. Unfortunately, there are mail agents which do not follow byte-stuffing rules and pass lines beginning with dashes unmodified into resulting digests. To help handle such cases a global variable is provided which controls how much dashes should the line begin with for it to be recognized as an encapsulation boundary.

Built-in variable: number burst_eb_min_length

Minimal number of consecutive dashes an encapsulation boundary must begin with.

The default is 2.

The following example shows a function which saves all parts of a digest message to separate disk files. The argument orig is a message descriptor. The resulting files are named by concatenating the string supplied by the stem argument and the ordinal number (1-based) of the message part.

func burst_digest(number orig, string stem)
do
  number msg message_burst(orig)
  number nparts message_count_parts(msg)
  
  loop for number i 1,
       while i <= nparts,
       set i i + 1
  do
    number part message_get_part(msg, i)
    number out open(sprintf('>%s%02d', stem, i))
    message_to_stream(out, part)
  done
  message_close(msg)
done

Mailfromd Manual (split by section):   Section:   Chapter:FastBack: Library   Up: Message functions   FastForward: Using MFL Mode   Contents: Table of ContentsIndex: Concept Index