phpgroupware-cvs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Phpgroupware-cvs] old/squirrelmail/doc tree.txt, 1.1 translating_help.t


From: skwashd
Subject: [Phpgroupware-cvs] old/squirrelmail/doc tree.txt, 1.1 translating_help.txt, 1.1 translating.txt, 1.1 themes.txt, 1.1 README.russian_apache, 1.1 addressbook.txt, 1.1 ie_ssl.txt, 1.1 plugin.txt, 1.1 mime.txt, 1.1 index.html, 1.1
Date: Thu, 5 May 2005 02:56:00 +0200

Update of old/squirrelmail/doc

Added Files:
     Branch: MAIN
            tree.txt 
            translating_help.txt 
            translating.txt 
            themes.txt 
            README.russian_apache 
            addressbook.txt 
            ie_ssl.txt 
            plugin.txt 
            mime.txt 
            index.html 

Log Message:
cvs clean up

====================================================
Index: tree.txt
So what is this tree stuff?
===========================

In order to get correct folder deletion across the board for all
different RFC2060 compliant IMAP servers, deleting of folders
needed to work by deleting subfolders (inferiors) first, working
up to the top folder that is desired to be deleted.

The best way to do this was to use a tree, and walk the thing in
preorder to get subfolders first (leaves), working our way up the
tree.  I chose to use an array for the tree structure.

The array has the following elements:
$tree[0]["value"]             = <full folder name>
$tree[0]["doIHaveChildren"]   = boolean
$tree[0]["subNodes"]          = indexes of the array that are
                                  child nodes of this node

The trickiest part was finding the correct parent node when creating
a new node in the tree.  Check the documentation in the code for
more info on this.

Basically all we had to do as loop through each of the items that
need to be in the tree (folders, subfolders), find their parent,
let their parent know it has a new child, and insert the values
into the child.

Once the tree is generated, a simple preorder or postorder walk
of the tree can be done doing whatever function you desire (delete,
create, etc).

Preorder walking gives you the tree from the leaves up.  Postorder
walks the tree from the root node down to the leaves.

====================================================
Index: translating_help.txt
Translating the help files.
===========================

I have tried to write the help files in plain english with good grammer.
Since English is not my strong point you probably can't tell, but I hope it
helps.

The help files, at this point, are devided into functional areas.
Each .hlp file represents a different functional block of how the program looks
to the user.

Hopefully as SquirrelMail is more widely used,
non-english translations will be used to make other non-english translations.
You might want to keep this in mind when writing yours. Remember that these will
be used all over the world and in many different environments so local language
dialects might confuse someone else.

File Structure
==============

All translated files should be placed under the help directory.  Under the help
directory create another directory. This directory MUST be named to the two 
letter
standard abbreviation for the language. English is "en" and Polish would be "pl"
for example.

The help files are written in a basic xml format.  Don't worry, XML isn't hard
at all.  All it does is contain values inside tags like <start> and </start>.
For these help files, the tags must be on their own line like this:
   <tag>
      Value for this tag
   </tag>

There are two types of main tags: <chapter> and <section>.  There can be only
one <chapter> tag in a .hlp file.  However, there can be many <section> tags.
Inside both of these tags, their can be any combination of any of the following
tags:  <title>, <description>, <summary>.  Here is an example:

                     | <chapter>
 The title can only  |    <title>
 be one line long    |       My first chapter
                     |    </title>
 Summary may be many |    <summary>
 lines, but is short |       Just a brief summary
                     |    </summary>
                     |    <description>
 Description can be  |       This is a more detailed description that
 very long.  It is   |       can span many lines.  Usually this is the
 the main part of    |       bulk of the help section or chapter description.
 the help section.   |    </description>
                     | </chapter>


Translating
===========

To translate, just copy all the .hlp files from help/en into your new directory
that you created for this language (i.e.  help/pl).  You only need to translate
what is inbetween the tags.  Do not translate the actual tags such as <chapter>
or <summary>.  The tag names need to remain in English.  You should only 
translate
the text between tags.

Often there may be other HTML tags such as <b> for bold or <a href...> to make
a link.  If you see any of these tags, just leave them and don't translate
them either.  Only what is contained inside them if needed.

That should be all!!

====================================================
Index: translating.txt
How to translate SquirrelMail into another language?
====================================================

This document does not deal with CVS and how to upload translations to
the repository.

1. First time translation
-------------------------

a) You must have gettext installed. If it is not installed you can
   download the soources from
   <URL:ftp://ftp.gnu.org/pub/gnu/gettext/>.

b) Find the language code for the language you are going to translate
   into. A list of language codes can be found at
   <URL:http://lcweb.loc.gov/standards/iso639-2/langhome.html>. If
   there is a 2 letter code for the language, use this.

   Create a directory squirrelmail/locale/language_code/LC_MESSAGES/.
   Copy squirrelmail/po/squirrelmail.po into this directory. This is the
   file that is going to be translated.

c) To translate the actual strings fill inn the msgstr after each
   msgid with the appropiate translation. There are a few tools which
   kan make this job a bit easier at
   <URL:http://i18n.kde.org/translation-howto/gui-specialized-apps.html>.

   Convert the translated squirrelmail.po into a binary file by
   running the command "msgfmt -o squirrelmail.mo squirrelmail.po" in
   the directory where the translated squirrelmail.po is residing.

d) Add the language name and language code to the array at the top of
   squirrelmail/functions/i18n.php.

There is also a small script in the po/ directory that can help in
creating charset mappings from the mappings files that are provided by
the Unicode consortium.

2. Maintaining translations
---------------------------

the text strings in the program will change over time. This means that
strings that are already translated is no longer used and new strings
are added. Therefore it is neccessary to maintain the translations.

a) There should always be an updated template containing all strings
   in SquirrelMail in squirrelmail/squirrelmail.po. To merge all new
   strings in this file into an existing translation run the command

msgmerge squirrelmail/locale/language/LC_MESSAGES/squirrelmail.po \
squirrelmail/po/squirrelmail.po > \
squirrelmail/locale/language/LC_MESSAGES/squirrelmail.po.new

   This should keep all strings that are unchanged and comment out all
   strings that are no longer in use. You might want to make a copy
   before doing this.

b) Rung msgfmt again to create a new binary file.


3. Updating the template
------------------------

This script comes from Serek:

#!/bin/bash
xgettext --keyword=_ -keyword=N_ \
  --default-domain=squirrelmail/po/squirrelmail \
  -C squirrelmail/src/*.php
xgettext --keyword=_ -keyword=N_ \
  --default-domain=squirrelmail/po/squirrelmail \
  -C -j squirrelmail/functions/*.php


====================================================
Index: themes.txt
Themes
======

To create a theme, it is very simple.  Just go into the themes/ directory
and create a file called yourtheme_theme.php.  You then need to create an
array with 12 elements (0-11).  Below is an example followed by a
description of what the different entries are for.

---<START>---
<?php

   #  My Theme
   #  Author:  My Name
   #  Date:  Today's Date
   #
   #  Optional description

   $color[0]   = "#xxxxxx";
   $color[1]   = "#xxxxxx";
   $color[2]   = "#xxxxxx";
   $color[3]   = "#xxxxxx";
   $color[4]   = "#xxxxxx";
   $color[5]   = "#xxxxxx";
   $color[6]   = "#xxxxxx";
   $color[7]   = "#xxxxxx";
   $color[8]   = "#xxxxxx";
   $color[9]   = "#xxxxxx";
   $color[10]  = "#xxxxxx";
   $color[11]  = "#xxxxxx";

?>
---<END>---

And here is a description of what the different entries in the array
are color of:

  0: Title Bar at the top of the page header
  1: <not currently used>
  2: Error messages (usually red)
  3: Left folder list background color
  4: Normal background color
  5: Header of the message index (From, Date, Subject)
  6: Normal text on the left folder list
  7: Links in the right frame
  8: Normal text (usually black)
  9: Darker version of #0
 10: Darker version of #9
 11: Special folders color (Inbox, Trash, Sent)

Next all you have to do is run conf.pl and add the theme to the list
of themes available to you.  If you would like your theme to be
included in the distribution of SquirrelMail, just email it to
<address@hidden> and I will review it.

====================================================
Index: README.russian_apache
HOW TO CONFIGURE SQUIRREL-MAIL WITH RUSSIAN APACHE
--------------------------------------------------

This text is available in Russian at
http://www.mricon.com/SM/russian_apache.html

*****
NOTE: Russian Apache will recode all attachments, even if they
are binary, thus corrupting them. To fix this problem, refer to
Russian Apache FAQ: http://apache.lexa.ru/faq.html#5
*****

This howto is for people who are using Russian Apache and
who use charsets other than koi8-r for their source documents.
If you _do_ use KOI8-R as default encoding for all your source
documents, you don't need to do anything. Otherwise, here's
a very simple way to make this work.

The general idea is to tell Russian Apache that everything
residing in the squirrel-mail directory is in koi8-r. This
way all input submitted by users will be automagically
converted by mod_charset from anything into koi8-r.
Squirrel-Mail will then correctly stamp it with
"Charset=koi8-r" and send off without any additional
conversion.

There are two equally efficient ways to do it:


1. THE HTTPD.CONF WAY.
-----------------------

In your httpd.conf, add the following declaration for the
server that handles the squirrel-mail:

<Directory /path/to/your/squirrel-mail>
CharsetSourceEnc koi8-r
</Directory>

Warning: If you use CharsetByExtension elsewhere, it will
override the CharsetSourceEnc directive. In that case you will
have to put this directive instead of the above:

<Directory /path/to/your/squirrel-mail>
CharsetByExtension koi8-r .php
</Directory>

It is advised to use the CharsetSourceEnc declaration instead
of the other one. Use the CharsetByExtension only if the
other fails.

2. THE .HTACCESS WAY (PREFERRED).
----------------------------------

Create a .htaccess file in your squirrel-mail directory. In it,
simply put this line:

CharsetSourceEnc koi8-r

That's it. Note the warning about the ChatsetByExtension directive
in the previous section. If you used CharsetByExtension declaration
elsewhere and it's active for this server, then you will have to
put this line in your .htaccess instead:

CharsetByExtension koi8-r .php

But again, this is only if the CharsetSourceEnc fails.

I mark this method "Preferred" simply because you don't have to
restart your server if you use .htaccess. However, if you've
specified "AllowOverride None" in your Server config, then you
will have to go with "the httpd.conf way".


If you have any questions or problems, please address them to
the address@hidden to have them
promptly answered. ;)

--
Konstantin Riabitsev (a.k.a. Graf)
address@hidden

====================================================
Index: addressbook.txt
SquirrelMail Addressbook Internals
==================================

This document describe how the SquirrelMail address book works. It is
primarily intended for developers.


1. The Basics
-------------

The address book is written using PHP classes, with one class,
AddressBook, that use one or more "backend" classes to access
different address books.

All operations, such as search, lookup, add etc., are performed by
calling the appropriate methods from the AddressBook object. The
operation will then be distributed by calling the correct method in
the appropriate backend(s).

To initialize the address book, the function addressbook_init() from
functions/addressbook.php is called. This function will create an
AddressBook object, add one backend for a personal address book (file
based storage), and add the LDAP backends defined in the $ldap_server
configuration directive (is any).

An addressbook can also be initialized like this if you want to:

  $abook = new AddressBook;

  // Add one file based backend (personal address book)
  $abook->add_backend("local_file", Array("filename" => $filename,
                                          "create"   => true));

  $abook->add_backend("ldap_server", <array with parameters>);

  $res = $abook->search("John Doe");

  echo $res[0]["name"] . " " . $res[0]["email"];



2. The AddressBook class
------------------------

This class acts as the glue for the address book. The following public
methods are provided:

  add_backend(NAME, PARAMETERS)

     NAME - The name of the backend to add. A file with a
     class abook_NAME must be included before this can
     be done.

     PARAMETERS - A mixed variable that is passed on to
     the backend class constructor. See each backend
     for docs.

   This method will return a backend ID number (not usable at the
   moment), or false if it failed.


  search(QUERY, [BNUM])

     QUERY - Something to search for. At the moment, only
     a string is allowed here, but advanced expressions
     will be supported through an array of parameters.

     BNUM  - Optional backend number to search.

   This method will return an array of result arrays (see below), an
   empty array if nothing was found, or false if the search failed.


  s_search(QUERY, [BNUM])

   The same as search(), but the result array is sorted by backend and
   fullname before it is returned.


  lookup(NICKNAME, [BNUM])

     NICKNAME - Return the user identified by NICKNAME in
     the addressbook.

     BNUM - ID of the backend to look in (optional).

   This method will return one result array (see below), an empty
   array if nothing was found, or false if the search failed. The
   lookup is only performed in "local" type backends.


  list_addr()

   This method will return an array of result arrays (see below) for
   all addresses in the addressbook, or false if it failed. Only
   addresses in "local" type backends are returned.


  add(USERDATA, BNUM)

     USERDATA - An array with user data. Must contain the following
     keys: nickname, firstname, lastname, email, label
     See below for information about the keys.

     BNUM - ID of the backend, as returned by add_backend, to add this
     data to.

   This method will return the backend ID of the backend where data
   was added, or false if it failed.


  remove(NICKNAME, BNUM)

     NICKNAME - Delete the user identified by NICKNAME in the
     addressbook or, if NICKNAME is an array, all users indentified by
     nthe nicknames in the array.

     BNUM - ID of the backend, as returned by add_backend, to remove
     the user(s) from.

   This method will retrun true if the user(s) was removed, or false
   if removal failed.


  modify(NICKNAME, USERDATA, BNUM)

     NICKNAME - Update the user identified by NICKNAME in the
     addressbook.

     USERDATA - Array with user data. The exisiting data for the user
     will be replaced with this.

     BNUM - ID of the backend, as returned by add_backend, to update
     the user in.

   This method will retrun true if the user was modified, or false if
   something failed.


If one of the above methods fail, an error message is available in the
AddressBook->error variable. Feel free to ignore it.


For the result of a search, lookup or list_addr, one or more result
arrays are used. These arrays contain the following keys:

  nickname:  Unique identifier for this name in this backend. Onlu
             usable for the local_file backend, and possibly LDAP.
  name:      Person's full name.
  email:     Person's e-mail address.
  backend:   Backend ID where this was found
  source:    Name of the backend where this was found

In addition, the following keys may exist for some backends:

  label:     Additional information about the person
  firstname: Person's first name
  lastname:  Person's last name


3. The backend classes
----------------------

... more later ...

Ask address@hidden if you have any questions on how to build
new address book backends.

====================================================
Index: ie_ssl.txt
Internet Explorer and SSL
Luke Ehresman <address@hidden>
=====================================

I've just spent the last few days trying to track down the now famous bug
with IE and SSL.  The problem lies in the fact that PHP sends some no-cache
headers whenever a session is started.  IE chokes when trying to download a
file that it can't cache over SSL.  We use session management to store many
things, one being the key to decypher the password.

Once we had figured out that it was sessions in PHP that was causing the
problem, we tried turning the session management off in the download script
in Squirrelmail.  This introduced another problem for us because we NEEDED
sessions to decypher the key so we could log into the IMAP server and
download the attachment.

Next we tried leaving the sessions turned off, but passed the key in through
a GET parameter.  This worked, but is obviously not a very secure way of
handling things.

Our quest continued for a good solution.  Finally, I was browsing through
the source of PHP, I noticed the 2 headers it was sending were "Pragma" and
"Cache-Control".  I had the crazy idea of defining these again after the
session had been started, and lo and behold, it worked!  Below is the code
that made this work:

     session_start()
         header("Pragma: ");
         header("Cache-Control: cache");

With all the testing I have done, this works, and works very well for all
browsers.


This was submitted by Marcin Jessa <address@hidden>
====================================================
  Reading INSTALL file of SqWebMail i found following note:

  Tweak the web server for MSIE
     The MSIE browser has a number of bugs in its HTTP/1.1 implementation,
     at least as of MSIE 4.x and 5.x. You must configure your web server to
     use HTTP/1.0 when talking to any MSIE browser (at least until MSIE
     gets fixed). The problem has to do with downloading attachments.
     Apparently, MSIE forgets how MIME works, when it uses HTTP/1.1. For
     the Apache server, insert the following directive in httpd.conf:

     BrowserMatch "MSIE" nokeepalive downgrade-1.0 force-response-1.0

     Recent versions of Apache already have a similar directive for a
     specific version of MSIE, MSIE 4.0b2. Just replace it with a
     browsermatch for any MSIE version.

====================================================
Index: plugin.txt
A FEW NOTES ON THE PLUGIN ARCHITECTURE
======================================

The plugin architecture of SquirrelMail is designed to make it
possible to add new features without having to patch SquirrelMail
itself. At the moment the plugin part of SquirrelMail should be
considered "alpha" or "beta" quality code.

Until the functionality and code is more stable, be prepared for
plugins to suddenly stop working.

Functionality like password changing, displaying ads and calendars
should be possible to add as plugins.


The idea
--------

The idea is to be able to run random code at given places in the
SquirrelMail code. This random code should then be able to do whatever
needed to enhance the functionality of SquirrelMail. The places where
code can be executed are called "hooks".

There are some limitations in what these hooks can do. It is difficult
to use them to change the layout and to change functionality that
already is in SquirrelMail.

Some way for the plugins to interact with the help subsystem and
translations will be provided.


The implementation
------------------

In the main SquirrelMail files the file functions/plugin.php. In
places where hooks are made available they are executed by calling the
function do_hook("hookname").

The do_hook traverses the array $squirrelmail_plugin_hooks["hookname"]
and executes all the functions that are named in that array.

A plugin must reside in a subdirectory in the plugins/ directory. The
name of the subdirectory is considered the name of the plugin.

To start using a plugin, its name must be added to the $plugins array
in config.php like this:

  $plugins[0] = "plugin_name";

When a plugin is registered the file plugins/plugin_name/setup.php is
included and the function squirrelmail_plugin_init_plugin_name is
called with no parameters.


Writing plugins
---------------

A plugin must consist of at least a file called setup.php. All other
files the plugin consist of should also be in the plugin directory.

The function squirrelmail_plugin_init_plugin_name is called to
initalize a plugin. This function could look something like this:

function squirrelmail_plugin_init_demo () {
  global $squirrelmail_plugin_hooks;

  $squirrelmail_plugin_hooks["generic_header"]["demo"] = "plugin_demo_header";
  $squirrelmail_plugin_hooks["menuline"]["demo"] = "plugin_demo_menuline";
}

Note that the SquirrelMail files assume that all other SquirrelMail
files are available as ../directory/file. This means that if some file
in the plugin directory is requested, it must do a chdir("..") before
including any of the standard SquirrelMail files.


Hook Data Passed
----------------
Hooks, when executed, are called with one parameter, an array of data
that is passed to the hook.  The first element in the array is the name
of the hook that is being called.  Any other elements in the array are
dependant on the type of hook that is being called.

Some of the information in the array may be changed.  By default, the
plugins should never change data unless it is documented otherwise.


List of hooks
-------------
  generic_header                  functions/page_header.php
  menuline                        functions/page_header.php
  compose_button_row              src/compose.php
  compose_bottom                  src/compose.php
  compose_form                    src/compose.php
  left_main_before                src/left_main.php
  left_main_after                 src/left_main.php
  * options_save                  src/options.php  (see note on options)
  * options_link_and_description  src/options.php  (see note on options)
  * options_highlight_bottom      src/options_highlight.php
  * options_personal_bottom       src/options_personal.php
  * options_personal_inside       src/options_personal.php
  * options_personal_save         src/options_personal.php
  * options_display_bottom        src/options_display.php
  * options_display_inside        src/options_display.php
  * options_display_save          src/options_display.php
  * options_folders_bottom        src/options_folders.php
  * options_folders_inside        src/options_folders.php
  * options_folders_save          src/options_folders.php
  logout                          src/signout.php
  login_before                    src/webmail.php
  login_verified                  src/webmail.php
  loading_prefs                   src/load_prefs.php
  mailbox_index_before            functions/mailbox_display.php
  mailbox_index_after             functions/mailbox_display.php
  mailbox_form_before             functions/mailbox_display.php
  subject_link                    functions/mailbox_display.php
  right_main_after_header         src/index.php
  right_main_bottom               src/index.php
  login_top                       src/login.php
  login_bottom                    src/login.php
  html_top                        src/read_body.php
  read_body_top                   src/read_body.php
  read_body_bottom                src/read_body.php
  html_bottom                     src/read_body.php
  read_body_header                src/read_body.php
  search_before_form              src/search.php
  search_after_form               src/search.php
  search_bottom                   src/search.php
  help_top                        src/help.php
  help_bottom                     src/help.php
  help_chapter                    src/help.php
  addrbook_html_search_below      src/addrbook_search_html.php
  addressbook_bottom              src/addressbook.php
  ^ attachment $type0/$type1      functions/mime.php (see note on attachments)


(*) Options
-----------
There are two ways to do options for your plugin.  First, you can incorporate it
into an existing section of the preferences (Display, Personal, or Folders).
The second way, you create your own section that they can choose from and it
displays its own range of options.


First:  Integrating into existing options
-----------------------------------------
There are two hooks you need to use for this one:

1.  options_YOUCHOOSE_inside
    This is the code that goes inside the table for the section you choose.  
Since
    it is going inside an existing table, it must be in this form:
    ------cut here-------
      <tr>
         <td>
            OPTION_NAME
         </td>
         <td>
            OPTION_INPUT
         </td>
      </tr>
    ------cut here-------

2.  options_YOUCHOOSE_save
    This is the code that saves your preferences into the users' preference
    file.  For an example of how to do this, see src/options.php.


Second:  Create your own section
-------------------------------
It is possible to create your own options sections with plugins.  There are
three hooks you will need to use.

1.  options_link_and_description
    This creates the link and has a description that are shown on the options
    page.  This should output HTML that looks like this:

    -----cut here-----
      function my_function() {
         global $color
         ?>
         <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
            <tr>
               <td bgcolor="<? echo $color[9] ?>">
                  <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR 
OPTIONS NAME</a>
               </td>
            </tr>
            <tr>
               <td bgcolor="<? echo $color[0] ?>">
                  YOUR DESCRIPTION
               </td>
            </tr>
         </table>
         <?php
      }
    -----cut here-----

2.  options_save
    Here is the code that you need to do to save your options in the
    preference files or manipulate whatever data you are trying to change
    through the options section.  You can look at options.php for details
    on how this is to be done.

3.  loading_prefs (optional)
    If you are wanting to save preferences to the preference files, then
    you need to do this step as well.  Otherwise if you are manipulating
    other data, ignore this step.

    You should put the code in here that loads your preferences back
    into usable variables.  Examples of this can be found in the file
    src/load_prefs.php


(^) Attachment Hooks
--------------------
When a message has attachments, this hook is called with the MIME types.  For
instance, a .zip file hook is "attachment application/x-zip".  The hook should
probably show a link to do a specific action, such as "Verify" or "View" for a
.zip file.

This is a breakdown of the data passed in the array to the hook that is called:

  [0] = Hook's name ('attachment text/plain')
  [1] = Array of links of actions (more below) (Alterable)
  [2] = Used for returning to mail message (startMessage)
  [3] = Used for finding message to display (id)
  [4] = Mailbox name, urlencode()'d (urlMailbox)
  [5] = Entity ID inside mail message (ent)
  [6] = Default URL to go to when filename is clicked on (Alterable)
  [7] = Filename that is displayed for the attachment
  [8] = Sent if message was found from a search (where)
  [9] = Sent if message was found from a search (what)

To set up links for actions, you assign them like this:

  $Args[1]['your_plugin_name']['href'] = 'URL to link to';
  $Args[1]['your_plugin_name']['text'] = 'What to display';


====================================================
Index: mime.txt
SquirrelMail MIME Support Introduction
======================================

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 ...

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 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.

A simple text/plain message would have a BODYSTRUCTURE similar to the
following:

   ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152 23)

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")
   "<address@hidden>" "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.

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

Getting the Body
----------------
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]".

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.

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:
address@hidden

====================================================
Index: index.html
<h2>SquirrelMail Documentation</h2>
<p>
Sorry for the lack of cohesion in the SquirrelMail documentation, but here is a 
conglomeration
of all the docs that we have accumulated so far.  Maybe some time in the future 
we will put
together a good documentation system.  This is just meant to get you up and 
running.  If you find
mistakes, please email them to <a href="address@hidden">address@hidden</a>.
</p>


<ul>
   <a href="translating.txt">Translating</a>
   <ul>
      If you would like to make a translation of SquirrelMail, here are some 
guidelines to help
          you along the way.  These were compiled, thanks to Gustav Foseid.
   </ul>
</ul>

<ul>
   <a href="translating_help.txt">Translating the Help System</a>
   <ul>
      We have a rather extensive help system in SquirrelMail now.  This 
document contains
      information about translating those help documents.
   </ul>
</ul>

<ul>
   <a href="tree.txt">The Mailbox Tree</a>
   <ul>
      This explains the algorithms and arrays behind the mailbox tree used in 
deleting folders.
          This was compiled thanks to Nathan Ehresman.
   </ul>
</ul>

<ul>
   <a href="addressbook.txt">The Addressbook</a>
   <ul>
      This explains how the addressbook works internally.
   </ul>
</ul>

<ul>
   <a href="mime.txt">MIME</a>
   <ul>
      Ever wonder how SquirrelMail handles MIME support?  You need not search
      any longer.  This document gives an overview of how it works and how
      we decode MIME encoded messages.
   </ul>
</ul>

<ul>
   <a href="plugin.txt">Plugins</a>
   <ul>
      If you would like to create plugins for SquirrelMail, this is the place
      to start.  It gives an overview and tells what needs to be in place for
      all plugins.
   </ul>
</ul>

<ul>
   <a href="themes.txt">Themes</a>
   <ul>
      You can create your own color themes and add them in the themes/ directory
      if you wish.  This describes the format of the theme files.
   </ul>
</ul>

<ul>
   <a href="README.russian_apache">Russian Apache</a>
   <ul>
      There are special instructions if you are running Russian Apache.  This
      document, thanks to Konstantin Riabitsev, will help you out.
   </ul>
</ul>

<ul>
   Basic documentation that comes with distrbution:
   <ul>
      <a href="../AUTHORS">AUTHORS</a><br>
      <a href="../INSTALL">INSTALL</a><br>
      <a href="../UPGRADE">UPGRADE</a><br>
      <a href="../README">README</a><br>
      <a href="../COPYING">COPYING</a><br>
      <a href="../ChangeLog">ChangeLog</a><br>
   </ul>
</ul>






reply via email to

[Prev in Thread] Current Thread [Next in Thread]