make-mime-part

Function

Package: net.post-office

ToC

DocOverview

CGDoc

RelNotes

Index

PermutedIndex

Allegro CL version 7.0
Unrevised from 6.2 to 7.0. New since 7.0 release.

make-mime-part

Arguments: &key content-type encoding external-format headers attachmentp name text start end file subparts id description parameters charset

MIME support was added in an update released around February 3, 2006. You must have that update to use it. See sys:update-allegro for information on updating Allegro CL.

This function returns a mime-part-constructed object with properties as specified by the arguments. There are many examples using this function in MIME support in imap.htm.

Like many Lisp constructor functions, make-mime-part offers a lot of options and looks complicated but typically only a few of the many keyword arguments are actually necessary. make-mime-part supplies many defaults that are sufficient for the most common scenarios.

MIME parts have contents. The contents can be supplied in one of three ways: with the text argument, with the file argument, or with the subparts argument:

Using the text keyword argument: the text keyword argument specifies a string that will be used as the body of the new part. If one or both of the start and end keyword arguments are supplied, then the desired subsequence of the string will be used. The default content-type is "text/plain" when text is a string. See also the description of the external-format keyword argument.
The text keyword argument can also be an (unsigned-byte 8) array. The subsequence of the array bounded by the start and end keyword arguments (specified) will be used. The default content-type is "application/octet-stream" when text is an (unsigned-byte 8) array.
Using the file keyword argument: the file keyword argument specifies a filename or an input stream that will be used to populate the body of new part. Note that the file/stream is not read until the part is rendered. If the argument is an input stream, it must be a stream that is capable of being read in an octet-oriented manner (e.g., it cannot be a string-input-stream). The default content-type will be deduced based on the specified filename or the filename associated with the input stream (if possible). If no specific content-type can be deduced, "application/octet-stream" will be used as the default. See also the description of the external-format keyword argument.
Using the subparts keyword argument: this only applies to multipart parts. The contents of a multipart part are simply other parts. The subparts argument should be a list of parts (as constructed by make-mime-part). The default content-type when subparts is specified is "multipart/mixed".

The start and end keyword arguments can be used to specify a subsequence of a text string to use. See the description of the text argument just above.

The remaining keyword arguments allow you to augment and override default settings for the new part:

content-type is a string specifying the MIME content type of the part. Examples: "text/plain", "text/html", "multipart/mixed", "multipart/alternative", etc. If no content-type is supplied, a default is chosen based on the other arguments to the function. The descriptions of text/file/subparts above say how defaults are selected. If the content-type is text, make sure you supply the proper charset if necessary.
The external-format keyword argument is only used if the content-type is a text type. The default value is :default. If the text of the part is being supplied from a file, make sure the external-format keyword argument corresponds to the external format of the file.
encoding is a string specifying how the part contents should be encoded (after any external format processing). Valid choices are "7bit", "8bit", "base64" and "quoted-printable". The default for non-text content-types is base64. The default for latin1 (aka US-ASCII) text is "7bit". The default for non-latin1 text is quoted-printable.
The attachmentp keyword argument controls the attachment disposition of the mime part. Generally, parts marked as "inline" are displayed (if possible) in the recipients email client at their respective position within the messages. Parts marked as "attachment" are typically displayed as a link or button that the user must click on or otherwise manipulate in order to open, save, or view. Keep in mind that that the attachment/inline disposition is only a suggestion and the behavior of email clients may vary with respect to the disposition. For content provided by file, the default disposition is "attachment". Otherwise, the default for non-text parts is "inline". The attachmentp keyword argument can be used to override the default. Note that text parts will never be marked "inline".
name is a string specifying the name of an attachment. For attachments provided using the file keyword argument, the name defaults to the basename of the pathname associated with the file. To override the default, or to provide information when it cannot be automatically deduced, use this keyword argument.
headers is an alist specifying additional headers that should be included with the part. This is most useful for specifying the standard email headers in the top level part (but see also send-letter for a simpler way to do this). The car of each entry should be a string naming the header. The cdr should be a string containing the contents of the header. For example: '(("Subject" . "This is a MIME-compliant message") ("Date" . "Mon, 9 Jan 2006 13:58:22 -0800")).
id is a string specifying the id for this part. This data will be used to construct the Content-Id header of the part.
description is a string specifying the description for this part. This data will be used to construct the Content-Description header of the part.
charset is a string specifying the MIME character set of text content-types. The default is determined by the external-format keyword argument. The charset keyword argument can be used to override the default. If you do override the default, make sure the external format of the part contents is in agreement with the charset.
paramaters is an alist specifying additional parameters that should be included in the Content-Type header for the part. The car of each entry should be a string naming the header. The cdr should be a string containing the contents of the header. For example: '(("format" . "flowed")).