From a789e2bc7b347bdaa1e045f471c8897627a7ec9c Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 14 Apr 2008 21:26:28 +0000 Subject: [PATCH] keyword-ized plot, plot and mime docs svn: r9304 original commit: fbfc9bf8832d0db7aed103a7fc5e6b68040276b4 --- collects/net/scribblings/mime.scrbl | 237 ++++++++++++++++++++++++++++ collects/net/scribblings/net.scrbl | 7 +- 2 files changed, 241 insertions(+), 3 deletions(-) create mode 100644 collects/net/scribblings/mime.scrbl diff --git a/collects/net/scribblings/mime.scrbl b/collects/net/scribblings/mime.scrbl new file mode 100644 index 0000000000..e355895701 --- /dev/null +++ b/collects/net/scribblings/mime.scrbl @@ -0,0 +1,237 @@ +#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{MIME: Decoding Internet Data} + +@defmodule[net/mime]{The @schememodname[net/mime] module 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.} + diff --git a/collects/net/scribblings/net.scrbl b/collects/net/scribblings/net.scrbl index 4be7c90bc5..759f1289f8 100644 --- a/collects/net/scribblings/net.scrbl +++ b/collects/net/scribblings/net.scrbl @@ -9,13 +9,14 @@ @include-section["uri-codec.scrbl"] @include-section["sendurl.scrbl"] @include-section["smtp.scrbl"] -@include-section["cgi.scrbl"] @include-section["sendmail.scrbl"] @include-section["head.scrbl"] -@include-section["nntp.scrbl"] -@include-section["pop3.scrbl"] @include-section["imap.scrbl"] +@include-section["pop3.scrbl"] +@include-section["mime.scrbl"] @include-section["dns.scrbl"] +@include-section["nntp.scrbl"] +@include-section["cgi.scrbl"] @include-section["gifwrite.scrbl"] @(bibliography