257 lines
9.7 KiB
Racket
257 lines
9.7 KiB
Racket
#lang scribble/doc
|
|
@(require "common.ss"
|
|
scribble/struct
|
|
(for-label net/mime
|
|
net/mime-unit
|
|
net/mime-sig))
|
|
|
|
@(define-syntax-rule (mime-table (type (sub-type0 ref0) (sub-type ref) ...) ...)
|
|
(let ([spacer (hspace 1)]
|
|
[to-flow (lambda (e)
|
|
(make-flow (list (make-paragraph (list e)))))])
|
|
(make-table
|
|
#f
|
|
(append
|
|
(list
|
|
(list (to-flow (scheme 'type))
|
|
(to-flow spacer)
|
|
(to-flow (scheme 'sub-type0))
|
|
(to-flow spacer)
|
|
(to-flow ref0))
|
|
(list (to-flow spacer)
|
|
(to-flow spacer)
|
|
(to-flow (scheme 'sub-type))
|
|
(to-flow spacer)
|
|
(to-flow ref))
|
|
...)
|
|
...))))
|
|
|
|
@title[#:tag "mime"]{MIME: Decoding Internet Data}
|
|
|
|
@defmodule[net/mime]{The @schememodname[net/mime] library provides
|
|
utilities for parsing and creating MIME encodings as described in RFC
|
|
2045 through RFC 2049.
|
|
|
|
The library was written by Francisco Solsona.}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section{Message Decoding}
|
|
|
|
@defproc[(mime-analyze [message-in (or/c bytes? input-port)]
|
|
[part? any/c])
|
|
message?]{
|
|
|
|
Parses @scheme[message-in] and returns the parsed result as a
|
|
@scheme[message] instance.}
|
|
|
|
@defstruct[message ([version real?]
|
|
[entity entity]
|
|
[fields (listof string?)])]{
|
|
|
|
A decoded MIME message. The version is @scheme[1.0] by default. The
|
|
@scheme[entity] field represents the message data. The @scheme[fields]
|
|
field contains one string for each field in the message header.}
|
|
|
|
@defstruct[entity ([type symbol?]
|
|
[subtype symbol?]
|
|
[charset symbol?]
|
|
[encoding symbol?]
|
|
[disposition disposition?]
|
|
[params (listof (cons/c symbol? string?))]
|
|
[id string?]
|
|
[description string?]
|
|
[other (listof string?)]
|
|
[fields (listof string?)]
|
|
[parts (listof message?)]
|
|
[body (output-port? . -> . void?)])]{
|
|
|
|
Represents the content of a message or a sub-part.
|
|
|
|
Standard values for the @scheme[type] field include @scheme['text],
|
|
@scheme['image], @scheme['audio], @scheme['video],
|
|
@scheme['application], @scheme['message], and @scheme['multipart].
|
|
|
|
Standard values for the @scheme[subtype] field depend on the
|
|
@scheme[type] field, and include the following:
|
|
|
|
@mime-table[
|
|
(
|
|
text (plain "[RFC1521, NSB]")
|
|
(richtext "[RFC1521, NSB]")
|
|
(tab-separated-values "[Lindner]")
|
|
)(
|
|
multipart (mixed "[RFC1521, NSB]")
|
|
(alternative "[RFC1521, NSB]")
|
|
(digest "[RFC1521, NSB]")
|
|
(parallel "[RFC1521, NSB]")
|
|
(appledouble "[MacMime, Faltstrom]")
|
|
(header-set "[Crocker]")
|
|
)(
|
|
message (rfc822 "[RFC1521, NSB]")
|
|
(partial "[RFC1521, NSB]")
|
|
(external-body "[RFC1521, NSB]")
|
|
(news "[RFC 1036, Spencer]")
|
|
)(
|
|
application (octet-stream "[RFC1521, NSB]")
|
|
(postscript "[RFC1521, NSB]")
|
|
(oda "[RFC1521, NSB]")
|
|
(atomicmail "[atomicmail, NSB]")
|
|
(andrew-inset "[andrew-inset, NSB]")
|
|
(slate "[slate, Crowley]")
|
|
(wita "[Wang Info Transfer, Campbell]")
|
|
(dec-dx "[Digital Doc Trans, Campbell]")
|
|
(dca-rft "[IBM Doc Content Arch, Campbell]")
|
|
(activemessage "[Shapiro]")
|
|
(rtf "[Lindner]")
|
|
(applefile "[MacMime, Faltstrom]")
|
|
(mac-binhex40 "[MacMime, Faltstrom]")
|
|
(news-message-id "[RFC1036, Spencer]")
|
|
(news-transmission "[RFC1036, Spencer]")
|
|
(wordperfect5.1 "[Lindner]")
|
|
(pdf "[Lindner]")
|
|
(zip "[Lindner]")
|
|
(macwriteii "[Lindner]")
|
|
(msword "[Lindner]")
|
|
(remote-printing "[RFC1486,MTR]")
|
|
)(
|
|
image (jpeg "[RFC1521, NSB]")
|
|
(gif "[RFC1521, NSB]")
|
|
(ief "[RFC1314]")
|
|
(tiff "[MTR]")
|
|
)(
|
|
audio (basic "[RFC1521, NSB]")
|
|
)(
|
|
video (mpeg "[RFC1521, NSB]")
|
|
(quicktime "[Lindner]")
|
|
)]
|
|
|
|
Standard values for the @scheme[charset] field include
|
|
@scheme['us-ascii], which is the default.
|
|
|
|
Standard values for the @scheme[encoding] field are @scheme['7bit],
|
|
@scheme['8bit], @scheme['binary], @scheme['quoted-printable], and
|
|
@scheme['base64]. The default is @scheme['7bit].
|
|
|
|
The @scheme[params] field contains a list of parameters from other
|
|
MIME headers.
|
|
|
|
The @scheme[id] field is taken from the @scheme["Content-Id"] header
|
|
field.
|
|
|
|
The @scheme[description] field is taken from the
|
|
@scheme["Content-description"] header field.
|
|
|
|
The @scheme[other] field contains additional (non-standard) field
|
|
headers whose field names start with @scheme["Content-"].
|
|
|
|
The @scheme[fields] field contains additional field headers whose
|
|
field names @emph{do not} start with @scheme["Content-"].
|
|
|
|
The @scheme[parts] contains sub-parts from multipart MIME
|
|
messages. This list is non-empty only when @scheme[type] is
|
|
@scheme['multipart] or @scheme['message].
|
|
|
|
The @scheme[body] field represents the body as a function that
|
|
consumes an output out and writes the decoded message to the port. No
|
|
bytes are written if @scheme[type] is @scheme['multipart] or
|
|
@scheme['message]. All of the standard values of @scheme[encoding]
|
|
are supported. The procedure only works once (since the encoded body
|
|
is pulled from a stream).}
|
|
|
|
@defstruct[disposition ([type symbol?]
|
|
[filename (or/c string? false/c)]
|
|
[creation (or/c string? false/c)]
|
|
[modification (or/c string? false/c)]
|
|
[read (or/c string? false/c)]
|
|
[size (or/c exact-nonnegative-integer? false/c)]
|
|
[params (listof (cons/c symbol? string?))])]{
|
|
|
|
Represents a @scheme["Content-Disposition"] header as defined in RFC
|
|
2183.
|
|
|
|
Standard values for the @scheme[type] field include @scheme['inline]
|
|
and @scheme['attachment].
|
|
|
|
The @scheme[filename] field is drawn from the @scheme["filename"]
|
|
parameter of the @scheme["Content-Disposition"] header, if included in
|
|
the message.
|
|
|
|
The @scheme[creation], @scheme[modification], and @scheme[read] fields
|
|
represent file timestamps as drawn from the @scheme["creation-date"],
|
|
@scheme["modification-date"], and @scheme["read-date"] attributes of
|
|
the @scheme["Content-Disposition"] header, if included in the message.
|
|
|
|
The @scheme[size] field is drawn from the @scheme["size"] parameter of
|
|
the @scheme["Content-Disposition"] header, if included in the message.
|
|
|
|
The @scheme[params] field stores any additional attribute bindings of
|
|
the @scheme["Content-Disposition"] header, if included in the message.}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section[#:tag "mime-exns"]{Exceptions}
|
|
|
|
@defstruct[mime-error ()]{
|
|
|
|
The supertype of all MIME exceptions.}
|
|
|
|
@defstruct[(unexpected-termination mime-error) ([msg string?])]{
|
|
|
|
Raised when an end-of-file is reached while parsing the headers of a
|
|
MIME entity. It usually means that the message does not conform
|
|
to RFC 2045 and friends.}
|
|
|
|
@defstruct[(missing-multipart-boundary-parameter mime-error) ()]{
|
|
|
|
Raised when a multipart type is specified, but no @scheme["Boundary"]
|
|
parameter is given or an end-of-file is encountered before the
|
|
boundary.}
|
|
|
|
@defstruct[(malformed-multipart-entity mime-error) ([msg string?])]{
|
|
|
|
Similar to @scheme[unexpected-termination], but used only while
|
|
scanning parts of a multipart message.}
|
|
|
|
@defstruct[(empty-mechanism mime-error) ()]{
|
|
|
|
Raised when no transport encoding mechanism was provided with the
|
|
@scheme["Content-Transfer-Encoding"] field.}
|
|
|
|
@defstruct[(empty-type mime-error) ()]{
|
|
|
|
Raised when no type is specified for @scheme["Content-Type"], or when
|
|
the specification is incorrectly formatted.}
|
|
|
|
|
|
@defstruct[(empty-subtype mime-error) ()]{
|
|
|
|
Raised when no sub-type is specified for @scheme["Content-Type"], or
|
|
when the specification is incorrectly formatted.}
|
|
|
|
|
|
@defstruct[(empty-disposition-type mime-error) ()]{
|
|
|
|
Raised when type specified for the @scheme["Content-Disposition"]
|
|
field, or when the specification is incorrectly formatted.}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section{MIME Unit}
|
|
|
|
@defmodule[net/mime-unit]
|
|
|
|
@defthing[mime@ unit?]{
|
|
|
|
Imports nothing, exports @scheme[mime^].}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section{MIME Signature}
|
|
|
|
@defmodule[net/mime-sig]
|
|
|
|
@defsignature[mime^ ()]{}
|
|
|
|
Includes everything exported by the @schememodname[net/mime] module.
|