Misc. documentation fixes by Simon Dick.
[squirrelmail.git] / doc / mime.txt
index 7def8e7..39eb3cb 100644 (file)
-mime.txt
-by Luke Ehresman
-June 22, 2000 - Last updated: June 22, 2000
+SquirrelMail MIME Support Introduction
+======================================
 
-Who should read this?
-
-   The intended audience for this document are people who want to understand how
-   the MIME code works.  This is a technical documentation of how mime.php 
-   works and how it parses a MIME encoded message.
+The intended audience for this document are people who want to understand how
+the MIME code works.  This is a technical documentation of how mime.php 
+works and how it parses a MIME encoded message.
 
 
 Object Structure
-
-   There are two objects that are used: "message" and "msg_header".  here is a
-   brief overview of what each object contains.
-
-   msg_header
-      Contains variables for all the necessary parts of the header of a
-      message.  This includes (but is not limited to) the following:  to, from,
-      subject, type (type0), subtype (type1), filename ...
+----------------
+There are two objects that are used: "message" and "msg_header".  Here is a
+brief overview of what each object contains.
+
+msg_header
+   Contains variables for all the necessary parts of the header of a
+   message.  This includes (but is not limited to) the following:  to, from,
+   subject, type (type0), subtype (type1), filename ...
       
-   message
-      This contains the structure for the message.  It contains two parts:
-      $header and $entities[].  $header is of type msg_header, and $entities[]
-      is an array of type $message.  The $entities[] array is optional.  If
-      it does not exist, then we are at a leaf node, and have an actual
-      attachment (entity) that can be displayed.  Here is a tree view of how
-      this object functions.
-
-      header
-      entities
-         |
-         +--- header
-         |
-         +--- header
-         |    entities
-         |       |
-         |       +--- header
-         |       |
-         |       +--- header
-         |
-         +--- header
+message
+   This contains the structure for the message.  It contains two parts:
+   $header and $entities[].  $header is of type msg_header, and $entities[]
+   is an array of type $message.  The $entities[] array is optional.  If
+   it does not exist, then we are at a leaf node, and have an actual
+   attachment (entity) that can be displayed.  Here is a tree view of how
+   this object functions.
+
+   header
+   entities
+      |
+      +--- header
+      |
+      +--- header
+      |    entities
+      |       |
+      |       +--- header
+      |       |
+      |       +--- header
+      |
+      +--- header
 
 
 Getting the Structure
+---------------------
+Previously (version 0.4 and below), SquirrelMail handled all the parsing of
+the email message.  It would read the entire message in, search for 
+boundaries, and create an array similar to the $message object described
+above.  This was very inefficient.
 
-   Previously (version 0.4 and below), SquirrelMail handled all the parsing of
-   the email message.  It would read the entire message in, search for 
-   boundaries, and created an array similar to the $message object discribed
-   above.  This was very inefficient.
+Currently, all the parsing of the body of the message takes place on the
+IMAP server itself.  According to RFC 2060 section 7.4.2, we can use the
+BODYSTRUCTURE function which will return the structure of the body (imagine
+that).  It goes into detail of how the bodystructure should be formatted,
+and we have based our new MIME support on this specification.  
 
-   Currently, all the parsing of the body of the message takes place on the
-   IMAP server itself.  According to RFC 2060 section 7.4.2, we can use the
-   BODYSTRUCTURE function which will return the structure of the body (imagine
-   that).  It goes into detail of how the bodystructure should be formatted,
-   and we have based our new MIME support on this specification.  
+A simple text/plain message would have a BODYSTRUCTURE similar to the 
+following:
 
-   A simple text/plain message would have a BODYSTRUCTURE similar to the 
-   following:
+   ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152 23)
 
-      ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152 23)
+A more complicated multipart message with an attachment would look like:   
 
-   A more complicated multipart message with an attachment would look like:   
-
-      (("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152 23)("TEXT" 
-      "PLAIN" ("CHARSET" "US-ASCII" "NAME" "cc.diff") 
-      "<960723163407.20117h@cac.washington.edu>" "Compiler diff" "BASE64" 
-      4554 73) "MIXED"))
+   (("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152 23)("TEXT" 
+   "PLAIN" ("CHARSET" "US-ASCII" "NAME" "cc.diff") 
+   "<960723163407.20117h@cac.washington.edu>" "Compiler diff" "BASE64" 
+   4554 73) "MIXED"))
    
-   Our MIME functionality implements different functions that recursively
-   run through this text and parses out the structure of the message.  If you
-   want to learn more about how the structure of a message is returned with
-   the BODYSTRUCTURE function, please see RFC 2060 section 7.4.2.
+Our MIME functionality implements different functions that recursively
+run through this text and parses out the structure of the message.  If you
+want to learn more about how the structure of a message is returned with
+the BODYSTRUCTURE function, please see RFC 2060 section 7.4.2.
 
-   NOTE:  SquirrelMail passes the MIME Torture Test written by Mark
-          Crispin (author of the IMAP protocol).  This message is crazy!  It
-          has about 30 parts nested inside each other.  A very good test, 
-          and SquirrelMail passed it.  It can be found here:
+NOTE:  SquirrelMail passes the MIME Torture Test written by Mark
+       Crispin (author of the IMAP protocol).  This message is crazy!  It
+       has about 30 parts nested inside each other.  A very good test, 
+       and SquirrelMail passed it.  It can be found here:
 
-          ftp://ftp.lysator.liu.se/mirror/unix/imapd/mime/torture-test.mbox
+       ftp://ftp.lysator.liu.se/mirror/unix/imapd/mime/torture-test.mbox
 
 Getting the Body
+----------------
+Once all the structure of the message has been read into the $message
+object, we then need to display the body of one entity.  There are a number
+of ways we decide which entity to display at a certain time, and I won't go
+into that here.  
 
-   Once all of the structure of the message has been read into the $message
-   object, we then need to display the body of one entity.  There are a number
-   of ways we decide which entity to display at a certain time, and I won't go
-   into that here.  
-
-   Each entity has its own ID.  Entity IDs look something like "1.2.1", or 
-   "4.1", or just "2".  You can find a detailed description of how entities
-   should be identified by reading RFC 2060 section 6.4.5.  To fetch the body
-   of a particular entity, we use the function "BODY[<section>]".  For 
-   instance, if we were wanting to return entity 1.2.1, we would send the
-   IMAP server the command: "a001 FETCH <msg_id> BODY[1.2.1]".
+Each entity has its own ID.  Entity IDs look something like "1.2.1", or 
+"4.1", or just "2".  You can find a detailed description of how entities
+should be identified by reading RFC 2060 section 6.4.5.  To fetch the body
+of a particular entity, we use the function "BODY[<section>]".  For 
+instance, if we were wanting to return entity 1.2.1, we would send the
+IMAP server the command: "a001 FETCH <msg_id> BODY[1.2.1]".
 
-   This returns a string of the entire body.  Based upon what is in the header,
-   we may need to decode it or do other things to it.
+This returns a string of the entire body.  Based upon what is in the header,
+we may need to decode it or do other things to it.
 
 
 Closing Notes  
+-------------
+That is basically how it works.  There is a variable in mime.php called
+$debug_mime that is defined at the top of that file.  If you set it to true,
+it will output all kinds of valuable information while it tries to decode
+the MIME message.
 
-   That is basically how it works.  There is a variable in mime.php called
-   $debug_mime that is defined at the top of that file.  If you set it to true,
-   it will output all kinds of valuable information while it tries to decode
-   the MIME message.
+The code in mime.php is pretty well documented, so you might want to poke
+around there as well to find out more details of how this works.
 
-   The code in mime.php is pretty well documented, so you might want to poke
-   around there as well to find out more details of how this works.
-   
-   If you have questions about this, please direct them to our mailing list:
-   squirrelmail-list@sourceforge.net
+If you have questions about this, please direct them to our mailing list:
+squirrelmail-users@sourceforge.net