 |
Index for
Section 1 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dtextbody(1)
CDE
NAME
dtextbody - utility to access external MIME body parts
SYNOPSIS
dtextbody body-part-as-file
DESCRIPTION
The dtextbody program is a tool used by dtmail to access remote MIME body
parts. It provides an easy-to-use interface for transfering the data from
a remote system to the local system.
FILE FORMAT
The body-part-as-file is the contents of a Content-Type: Message/External-
Body body part as described in RFC-1521. The following is an excerpt from
RFC-1521 covering the external message:
7.3.3. The Message/External-Body subtype
The external-body subtype indicates that the actual body data are
not included, but merely referenced. In this case, the parameters
describe a mechanism for accessing the external data.
When an entity is of type "message/external-body", it consists of a
header, two consecutive CRLFs, and the message header for the
encapsulated message. If another pair of consecutive CRLFs
appears, this of course ends the message header for the encap-
sulated message. However, since the encapsulated message's
body is itself external, it does NOT appear in the area that
follows. For example, consider the following message:
Content-type: message/external-body;
access-type=local-file;
name="/u/nsb/Me.gif"
Content-type: image/gif
Content-ID: <id42@guppylake.bellcore.com>
Content-Transfer-Encoding: binary
THIS IS NOT REALLY THE BODY!
The area at the end, which might be called the "phantom body",
is ignored for most external-body messages. However, it may be
used to contain auxiliary information for some such messages, as
indeed it is when the access-type is "mail-server". Of the access-
types defined by this document, the phantom body is used only
when the access-type is "mail-server". In all other cases, the
phantom body is ignored.
The only always-mandatory parameter for message/external-body
is "access-type"; all of the other parameters may be mandatory
or optional depending on the value of access-type.
ACCESS-TYPE -- A case-insensitive word, indicating the
supported access mechanism by which the file or data may
be obtained. Values include, but are not limited to, "FTP",
"ANON-FTP", "TFTP", "AFS", "LOCAL-FILE", and
"MAIL-SERVER". Future values, except for experimental
values beginning with "X-" must be registered with IANA, as
described in Appendix E.
In addition, the following three parameters are optional for ALL
access-types:
EXPIRATION -- The date (in the RFC 822 "date-time" syntax,
as extended by RFC 1123 to permit 4 digits in the year field)
after which the existence of the external data is not guaranteed.
SIZE -- The size (in octets) of the data. The intent of this
parameter is to help the recipient decide whether or not to
expend the necessary resources to retrieve the external data.
Note that this describes the size of the data in its canonical
form, that is, before any Content- Transfer-Encoding has been
applied or after the data have been decoded.
PERMISSION -- A case-insensitive field that indicates whether
or not it is expected that clients might also attempt to overwrite
the data. By default, or if permission is "read", the assumption
is that they are not, and that if the data is retrieved once, it
is never needed again. If PERMISSION is "read-write", this
assumption is invalid, and any local copy must be considered
no more than a cache. "Read" and "Read-write" are the only
defined values of permission.
The precise semantics of the access-types defined here are
described in the sections that follow.
The encapsulated headers in ALL message/external-body entities
MUST include a Content-ID header field to give a unique
identifier by which to reference the data. This identifier may be
used for cacheing mechanisms, and for recognizing the receipt of
the data when the access-type is "mail-server".
Note that, as specified here, the tokens that describe external-
body data, such as file names and mail server commands, are
required to be in the US-ASCII character set. If this proves
problematic in practice, a new mechanism may be required as a
future extension to MIME, either as newly defined access-types
for message/external-body or by some other mechanism.
As with message/partial, it is specified that MIME entities of type
message/external-body must always have a content-transfer-
encoding of 7-bit (the default). In particular, even in environ-
ments that support binary or 8-bit transport, the use of a
content-transfer-encoding of "8bit" or "binary" is explicitly
prohibited for entities of type message/external-body.
An access-type of FTP or TFTP indicates that the message body is
accessible as a file using the FTP [RFC-959] or TFTP [RFC-783]
protocols, respectively. For these access-types, the following
additional parameters are mandatory:
NAME -- The name of the file that contains the actual body
data.
SITE -- A machine from which the file may be obtained, using
the given protocol. This must be a fully qualified domain name,
not a nickname.
Before any data are retrieved, using FTP, the user will generally
need to be asked to provide a login id and a password for the
machine named by the site parameter. For security reasons, such an
id and password are not specified as content-type parameters, but
must be obtained from the user.
In addition, the following parameters are optional:
DIRECTORY -- A directory from which the data named by
NAME should be retrieved.
MODE -- A case-insensitive string indicating the mode to be
used when retrieving the information. The legal values for
access-type "TFTP" are "NETASCII", "OCTET", and "MAIL",
as specified by the TFTP protocol [RFC-783]. The legal values
for access-type "FTP" are "ASCII", "EBCDIC", "IMAGE", and
"LOCALn" where "n" is a decimal integer, typically 8. These
correspond to the representation types "A" "E" "I" and "L n" as
specified by the FTP protocol [RFC-959]. Note that "BINARY"
and "TENEX" are not valid values for MODE, but that "OCTET"
or "IMAGE" or "LOCAL8" should be used instead. IF MODE is
not specified, the default value is "NETASCII" for TFTP
and "ASCII" otherwise.
7.3.3.2. The "anon-ftp" access-type
The "anon-ftp" access-type is identical to the "ftp" access type,
except that the user need not be asked to provide a name and
password for the specified site. Instead, the ftp protocol will be
used with login "anonymous" and a password that corresponds
to the user's email address.
7.3.3.3. The "local-file" and "afs" access-types
An access-type of "local-file" indicates that the actual body is
accessible as a file on the local machine. An access-type of "afs"
indicates that the file is accessible via the global AFS file system.
In both cases, only a single parameter is required:
NAME -- The name of the file that contains the actual body data.
The following optional parameter may be used to describe the
locality of reference for the data, that is, the site or sites at which
the file is expected to be visible:
SITE -- A domain specifier for a machine or set of machines that
are known to have access to the data file. Asterisks may be used
for wildcard matching to a part of a domain name, such as
"*.bellcore.com", to indicate a set of machines on which the data
should be directly visible, while a single asterisk may be used to
indicate a file that is expected to be universally available, e.g.,
via a global file system.
7.3.3.4. The "mail-server" access-type
The "mail-server" access-type indicates that the actual body is
available from a mail server. The mandatory parameter for this
access-type is:
SERVER -- The email address of the mail server from which the
actual body data can be obtained.
Because mail servers accept a variety of syntaxes, some of which
is multiline, the full command to be sent to a mail server is not
included as a parameter on the content-type line. Instead, it is
provided as the "phantom body" when the content-type is
message/external-body and the access- type is mail-server.
An optional parameter for this access-type is:
SUBJECT -- The subject that is to be used in the mail that is
sent to obtain the data. Note that keying mail servers on
Subject lines is NOT recommended, but such mail servers are
known to exist.
Note that MIME does not define a mail server syntax. Rather, it
allows the inclusion of arbitrary mail server commands in the
phantom body. Implementations must include the phantom body
in the body of the message it sends to the mail server address to
retrieve the relevant data.
It is worth noting that, unlike other access-types, mail-server
access is asynchronous and will happen at an unpredictable time
in the future. For this reason, it is important that there be a
mechanism by which the returned data can be matched up with
the original message/external-body entity. MIME mailservers
must use the same Content-ID field on the returned message that
was used in the original message/external-body entity, to
facilitate such matching.
7.3.3.5. Examples and Further Explanations
With the emerging possibility of very wide-area file systems, it
becomes very hard to know in advance the set of machines where
a file will and will not be accessible directly from the file system.
Therefore it may make sense to provide both a file name, to be
tried directly, and the name of one or more sites from which the
file is known to be accessible. An implementation can try to
retrieve remote files using FTP or any other protocol, using
anonymous file retrieval or prompting the user for the necessary
name and password. If an external body is accessible via
multiple mechanisms, the sender may include multiple parts
of type message/external-body within an entity of type
multipart/alternative.
However, the external-body mechanism is not intended to be
limited to file retrieval, as shown by the mail-server access-type.
Beyond this, one can imagine, for example, using a video server
for external references to video clips.
If an entity is of type "message/external-body", then the body of
the entity will contain the header fields of the encapsulated
message. The body itself is to be found in the external location.
This means that if the body of the "message/external-body" mes-
sage contains two consecutive CRLFs, everything after those pairs
is NOT part of the message itself. For most message/external-
body messages, this trailing area must simply be ignored.
However, it is a convenient place for additional data that cannot
be included in the content-type header field. In particular, if the
"access-type" value is "mail-server", then the trailing area must
contain commands to be sent to the mail server at the address
given by the value of the SERVER parameter.
The embedded message header fields which appear in the body of
the message/external-body data must be used to declare the
Content-type of the external body if it is anything other than
plain ASCII text, since the external body does not have a header
section to declare its type. Similarly, any Content-transfer-
encoding other than "7bit" must also be declared here. Thus a
complete message/external-body message, referring to a document
in PostScript format, might look like this:
From: Whomever
To: Someone
Subject: whatever
MIME-Version: 1.0
Message-ID: <id1@host.com>
Content-Type: multipart/alternative; boundary=42
Content-ID: <id001@guppylake.bellcore.com>
--42
Content-Type: message/external-body;
name="BodyFormats.ps";
site="thumper.bellcore.com";
access-type=ANON-FTP;
directory="pub";
mode="image";
expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"
Content-type: application/postscript
Content-ID: <id42@guppylake.bellcore.com>
--42
Content-Type: message/external-body;
name="/u/nsb/writing/rfcs/RFC-MIME.ps";
site="thumper.bellcore.com";
access-type=AFS
expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"
Content-type: application/postscript
Content-ID: <id42@guppylake.bellcore.com>
--42
Content-Type: message/external-body;
access-type=mail-server
server="listserv@bogus.bitnet";
expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"
Content-type: application/postscript
Content-ID: <id42@guppylake.bellcore.com>
get RFC-MIME.DOC
--42--
Note that in the above examples, the default Content-transfer-
encoding of "7bit" is assumed for the external postscript data.
Like the message/partial type, the message/external-body type is
intended to be transparent, that is, to convey the data type in the
external body rather than to convey a message with a body of that
type. Thus the headers on the outer and inner parts must be
merged using the same rules as for message/partial. In particular,
this means that the Content-type header is overridden, but the
From and Subject headers are preserved.
Note that since the external bodies are not transported as mail,
they need not conform to the 7-bit and line length requirements,
but might in fact be binary files. Thus a Content-Transfer-
Encoding is not generally necessary, though it is permitted.
Note that the body of a message of type "message/external-body"
is governed by the basic syntax for an RFC 822 message. In
particular, anything before the first consecutive pair of CRLFs
is header information, while anything after it is body infor-
mation, which is ignored for most access-types.
The formal grammar for content-type header fields for data of type
message is given by:
message-type := "message" "/" message-subtype
message-subtype := "rfc822"
/ "partial" 2#3partial-param
/ "external-body" 1*external-param
/ extension-token
partial-param := (";" "id" "=" value)
/ (";" "number" "=" 1*DIGIT)
/ (";" "total" "=" 1*DIGIT)
; id & number required; total required for last part
external-param := (";" "access-type" "=" atype)
/ (";" "expiration" "=" date-time)
; Note that date-time is quoted
/ (";" "size" "=" 1*DIGIT)
/ (";" "permission" "=" ("read" / "read-write"))
; Permission is case-insensitive
/ (";" "name" "=" value)
/ (";" "site" "=" value)
/ (";" "dir" "=" value)
/ (";" "mode" "=" value)
/ (";" "server" "=" value)
/ (";" "subject" "=" value)
; access-type required;others required based on access-type
atype := "ftp" / "anon-ftp" / "tftp" / "local-file"
/ "afs" / "mail-server" / extension-token
; Case-insensitive
-----
FILES
/usr/dt/bin/dtextbody
This is the executable file transfer tool.
|
Index for
Section 1 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|