@@ -1,3 +1,14 @@

+2007-06-01  Ahmon Dancy  <dancy@dancy>

+

+	* mime-transfer-encoding.cl: New quoted-printable decoding utility

+	functions.

+

+	* mime-parse.cl: Improved handling of large or noncompliant

+	headers.  Improved mbox processing support.

+

+	* mime-api.cl: New exported function: decode-header-text.

+	

+

 2007-05-29  Kevin Layer  <layer@gemini.franz.com>

 	* mime-parse.cl: fix from dancy for parse-mime-structure

new file mode 100644

@@ -0,0 +1,198 @@

+Prelimanary documenation.

+

+Class: mime-part-parsed

+Subclass of: mime-part

+

+Slot accessors:

+

+    * mime-part-type 

+      <update comment about mime-part-parsed objects>

+    * mime-part-subtype

+      <update comment about mime-part-parsed objects>

+    * mime-part-parameters

+    * mime-part-id

+      <update comment about mime-part-parsed objects>

+    * mime-part-description

+      <update comment about mime-part-parsed objects>

+    * mime-part-encoding

+      <update comment about mime-part-parsed objects>

+    * mime-part-headers

+    * mime-part-parts

+    * mime-part-boundary

+      <update comment about mime-part-parsed objects>

+

+    * mime-part-headers-size

+      This is the size, in bytes, of the header portion of the part

+      (including the blank line terminator)

+

+    * mime-part-body-size

+      This is the size, in bytes, of the body of the part.

+

+    * mime-part-lines

+      For non-multipart types, this is the number of lines that make

+      up the part body.

+   

+    * mime-part-position 

+      This is the file positon of the start of the part headers,

+      relative to the beginning of the topmost part.

+  

+    * mime-part-body-position

+      This is the file position of the start of the part body,

+      relative to the beginning of the topmost part.

+

+    * mime-part-message 

+      For message/rfc822 parts, this slot contains the

+      mime-part-parsed object which represents the encapsulated message.

+

+Function: parse-mime-structure

+

+Arguments: stream &key mbox

+

+Return values: 

+The function returns two values:

+

+ 1) A mime-part-parsed object which represents the topmost MIME part

+    (which may possibly contain subparts).  If there was no message to

+    parse (such as if the stream is at EOF), then nil is returned.

+

+ 2) The number of bytes that were read.

+

+'stream' should be a stream that is positioned at the first header of

+a MIME-compliant email message.  

+

+If 'mbox' is true, then parsing will terminate at EOF or when a line

+which begins with "From " is read.

+

+MIME messages always have a topmost part and may possibly have

+multiple subparts which may recursively have their own subparts.  This

+function reads 'stream' and creates a mime-part-parsed object which

+contains information about these parts and subparts.  For each part,

+the following information is collected:

+

+* The major content type, (e.g, "text", if the Content-Type header

+  is "text/html").

+* The content subtype, (e.g., "html", if the Content-Type header is

+  "text/html").

+* Any parameter information that was supplied in the Content-Type

+  header.

+* The part id, as determined by the Content-Id header, if there was

+  one.

+* The part description, as determined by the Content-Description

+  header, if there was one.

+* The part encoding, as determined by the Content-Transfer-Encoding

+  header.

+* The boundary string, for multipart types.  

+* The list of subparts (which are also mime-part-parsed objects) for

+  multipart parts.

+* The encapsulated message (which is a mime-part-parsed object) for

+  message/rfc822 parts.

+* The size of the part headers (in bytes).

+* The size of the part body (in bytes).

+* The number of lines comprising the part body.

+* The file position of the beginning of the part headers, relative to the

+  position of the topmost part.  For the topmost part, this value will

+  always be zero.  

+* The file position of the beginning of the part body, relative to the

+  position of the topmost part.  

+

+See also: <the documentation page which lists the slots of the

+mime-part-parsed class>.

+

+

+Function: map-over-parts 

+Arguments: part function

+

+'part' must be a mime-part.

+

+'function' must be a function (or symbol naming a function) which

+takes a single argument, a mime-part.

+

+map-over-parts calls 'function' on 'part', then, if part contains

+subparts (or an encapsulated message in the case of a message/rfc822

+part), map-over-parts is called recursively for each subpart (or

+encapsulated message).

+

+Function: qp-encode-stream

+Arguments: instream outstream &key wrap-at

+

+This function reads bytes from instream and writes them in

+quoted-printable format to outstream.  Lines in the output are wrapped

+approximately every 'wrap-at' output characters (which defaults to

+72).  Wrapping may be late by up to 3 characters under some

+circumstances (e.g., when using the default 'wrap-at' value of 72,

+some lines may be 75 characters long).

+

+'instream' is read until EOF is seen.

+

+'instream' must be a stream capable of being read in an octet-oriented

+manner.  In particular, it cannot be a string stream.

+

+See also: qp-decode-stream, base64-encode-stream, base64-decode-stream

+

+

+

+Function: qp-decode-stream

+Arguments: instream outstream

+

+This function reads quoted-printable encoded text from 'instream' and

+writes the decoded text to 'outstream'.  Reading continues until

+end-of-file is seen on 'instream'.  

+

+See also: qp-encode-stream, base64-encode-stream, base64-decoed-stream

+

+

+Macro: with-part-stream

+Arguments: (sym part instream &key (header t)) &body body

+

+with-part-stream evaluates 'body' with 'sym' bound to an input stream

+which, when read, supplies bytes from 'instream'.  'instream' must be

+positioned either at the beginning of the part headers (if keyword

+argument 'header' is true) or at the beginning of the part body (if

+keyword argument 'header' is false).  The 'part' argument is used by

+the macro to determine how many bytes from 'instream' will be used.

+

+The primary purpose of this macro is to create a stream that will

+generate an end-of-file indicator when the contents of a part have

+been completely read.  Such a stream is useful for passing to

+functions which expect to read a stream until EOF (such as

+'decode-quoted-printable' or 'excl:base64-decode-stream').

+

+See also: with-decoded-part-body-stream

+

+Macro: with-decoded-part-body-stream

+Arguments: (sym part instream) &body body

+

+with-decoded-part-body-stream evaluates 'body' with 'sym' bound to an

+input stream which, when read, supplies decoded bytes.  The encoded

+bytes are read from 'instream', which should be an input stream whose

+file position is at the beginning of the part body.  The 'part'

+argument is used by the macro to determine the size of the part body

+and also to determine the content transfer encoding of the part.  The

+input stream bound to 'sym' will signal end-of-file when the part body

+has been exhausted.

+

+Example:

+

+(use-package :net.post-office)

+

+(defun extract-all-jpegs (filename)

+  (with-open-file (f filename)

+    (let ((toppart (parse-mime-structure f))

+	  (count 0))

+      

+      (flet ((extract-jpeg (part)

+	       (if* (and (equalp (mime-part-type part) "image")

+			 (equalp (mime-part-subtype part) "jpeg"))

+		  then (incf count)

+		       (let ((filename (format nil "image~d.jpg" count)))

+			 (format t "Saving ~a...~%" filename)

+			 (with-open-file (out filename :direction :output)

+			   ;; Position source file pointer to the beginning

+			   ;; of the part body.

+			   (file-position f (mime-part-body-position part))

+			   (with-decoded-part-body-stream (bod part f)

+			     (sys:copy-file bod out)))))))

+      

+	(map-over-parts toppart #'extract-jpeg)))))

+

+See also: mime-part-body-position slot accessor.

@@ -14,7 +14,7 @@

 ;; merchantability or fitness for a particular purpose.  See the GNU

 ;; Lesser General Public License for more details.

 ;;

-;; $Id: mime-transfer-encoding.cl,v 1.10 2007/05/31 23:13:08 dancy Exp $

+;; $Id: mime-transfer-encoding.cl,v 1.11 2007/06/01 16:24:40 dancy Exp $

 (defpackage :net.post-office

   (:use #:lisp #:excl)

@@ -116,6 +116,7 @@

 ;; Used by qp-decode-stream

+(eval-when (compile)

 (defconstant *qp-digit-values*

     #.(let ((arr (make-array 257 :element-type 'fixnum)))

 	(dotimes (n 256)

@@ -126,7 +127,7 @@

 	       then (- n (- (char-code #\A) 10))

 	       else -1)))

 	(setf (aref arr 256) -2)

-	arr))

+	arr)))

 (defun qp-decode-stream (instream outstream &key count)

   (declare (optimize (speed 3)))