make-mime-part
Arguments:
&key content-type encoding external-format headers attachmentp name text start end file subparts id description parameters charset
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 (i.e., a content type
of the form text/<something> or message/rfc822. The default value is
:utf-8
. 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 encoding is selected according to the
following rules:
-
If the :text keyword argument is supplied and is a string, then
the string is converted to a usb8 array (using the external-format
specified in the :external-format keyword argument, which defaults
to :utf-8). The usb8 array is then scanned to see if there are any
bytes with the high bit set. If there are, "base64" is selected as
the encoding. Otherwise "7bit" is selected.
-
Otherwise, "base64" is selected.
-
The attachmentp keyword argument
controls the attachment disposition of the mime part. Generally,
parts marked as "inline" are displayed (if possible) in the recipient's
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 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.
-
The charset keyword argument is only used if the
content-type is a text type (i.e., a content type of the form
text/<something> or message/rfc822). The default charset is
determined by the external-format keyword argument (which itself
defaults to :utf-8), so in most cases, it should not be necessary to
use this keyword argument. If specified, charset should be a string
specifying a valid MIME charset.
-
parameters 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"))
.
See MIME support in
imap.htm for more information. That section
contains examples.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.