This is a "plugin" for the Video Disk Recorder (VDR).

Written by:         Alexander Rieger <Alexander.Rieger at inka.de>

Project's homepage: http://sites.inka.de/~seca/vdr

Latest version available at the homepage.

See the file COPYING for license information.

(last edited: $Date: 2004/01/24 17:34:36 $)

Contents:
=========

1.  Description
2.  License / Disclaimer
3.  Installation / Troubleshooting
4.  Configuration
4.1  Starting vdr with the plugin
4.2  Configuration of the plugin
4.3  General settings of the plugin
4.4  Setting up mail accounts
5.  Usage
5.1  Overview
5.2  mailbox-view
5.3  mail-list-view
5.4  mail-view
6.  Known Problems / Todo
7.  Thanks

1. Description:
===============

"mailbox" is a mail reader plugin for the Video Disk Recorder (VDR) of
Klaus Schmidinger.

The intended purpose of this plugin is to access multiple IMAP mail
accounts and to read the mails on the OSD of VDR.

To access the mailboxes this plugin uses the c-client-library from the
IMAP server from Mark Crispin at the University of Washington (UW IMAP).

Since c-client-library supports also POP3 this plugin is also able to
access POP3 mail accounts. But as the POP3 protocol is less powerful
than IMAP, some of the features are not available with POP3 mailboxes.

As I only use IMAP to access mail, usage with POP3 accounts is rarely
tested - the support for POP3-mailboxes is more or less a side effect
of using c-client-library.

The plugin supports the following features:

- Access to mail accounts with IMAP and POP3.

- Support of multiple mail accounts with different protocols.

- 'mailbox-view' to display a list of all mail accounts with the number
  of new and the total number of mails for every mail account.
  (For POP3 accounts all mails are displayed as new.)

- 'mail-list-view' to display a list of all mails in a mailbox with
  subject, sender and state/flags of every mail.

- 'mail-view' to display one single mail with subject, sender, date,
  flags and mail text.

- Mails encoded in 'quoted-printable' are displayed correctly (tested
  at least with german umlauts).

- The parameter "format=flowed" is honored when wrapping mails at
  the osd boundaries (see RFC 2646).

- IMAP/POP3: when displaying a multipart mail, only parts with content-
  type text are displayed.

- IMAP: when displaying multipart mails, only parts with content-type
  text are fetched.

- IMAP: when a mail is displayed in the 'mail-view', the \Seen flag
  for this mail is set automatically (configurable).

- Jump to next/previous new (not \Seen) mail in the 'mail-list-view'
  and in the 'mail-view'.

- IMAP/POP3: set/clear the flags \Seen, \Flagged and \Deleted for
  mails in the "mail-list-view" and the "mail-view".

- Expunge mails with the \Deleted flag set when a mailbox is closed
  (configurable).

- Check for new mails in the background and start an external
  application when the number of new mails changed since the
  last check.

2. License / Disclaimer:
========================

mailbox-plugin - IMAP/POP3 mail-reader plugin for vdr

Copyright (C) 2003 Alexander Rieger

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
Or, point your browser to http://www.gnu.org/copyleft/gpl.html

The University of Washington states in its "Free-Fork License"
concerning the UW IMAP (and therefore c-client-library too) the
following:

--- snip ---
This software is made available "as is", and

THE UNIVERSITY OF WASHINGTON DISCLAIMS ALL WARRANTIES, EXPRESS OR
IMPLIED, WITH REGARD TO THIS SOFTWARE, INCLUDING WITHOUT LIMITATION
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE, AND IN NO EVENT SHALL THE UNIVERSITY OF
WASHINGTON BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, TORT (INCLUDING
NEGLIGENCE) OR STRICT LIABILITY, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
--- snip ---
(full text at http://www.washington.edu/imap/legal.html)

The same applies analogously for the author of the mailbox-plugin.

3. Installation / Troubleshooting
=================================

The installation instructions are located in the separate file INSTALL.

4.  Configuration
=================

4.1  Starting vdr with the plugin
---------------------------------

If you want the the plugin to check for new mail in the background
and start an external programm/script whenever the number of new mails
changed, you have to give the path/name of the script to the plugin with
the command line parameter -m.

A sample script 'mailcmd.sh' is located in the source directory of the
plugin. 'mailcmd.sh' logs the given parametes to the syslog using the
logger command and sends a message 'New mail in <Accountname>' to the
osd of vdr using 'svdrpsend.pl' and the MESG command.

The external command is started with the follwing parameters:

  Param 1: <name of the account>
  Param 2: <user name>
  Param 3: 'dummy', reserved for later use
  Param 4: 'dummy', reserved for later use
  Param 5: <number of new mails in the account>
  Param 6: <total-number of mails in the account>

Before starting the mailbox-plugin with the external command, please
check that your script works as expected by calling it from a shell with

  $ mailcmd.sh AccountName UserName dummy dummy 1 1

The background checking feature of the plugin must be enabled in the
'common settings' menu of the plugin. Additionally you have to enable
the background checking for every mail account in the setup menu
of the accounts.

If you enable the background checking feature, the plugin starts a
separate thread to check in given intervals for new mail (identifies
itself as 'mail-checker-thread' in the syslog). This thread is stopped
when you enter the mailbox-plugin or the configuration of the plugin.
Whenever you leave the plugin or the settings of the plugin the thread
is started again.

A few seconds after the mail-checker-thread is started, it checks for
mails for the first time and starts the external command for all mail
accounts. Afterwards the external command is only started if the number
of new mails in an account changed. Therefore the external command
is also started for all configured mail accounts shortly after you
leave the mailbox plugin or the settings of the plugin.

4.2 Configuration of the plugin
-------------------------------

In the setup menu of the plugin you can configure global settings of
the plugin and several mail accounts.

Depending on the selected line the following keys are available:

  [Red   ] edit the general settings or the selected account
  [Green ] create a new account
  [Yellow] delete the current account, vdr asks for confirmation

4.3 General settings of the plugin
----------------------------------

Following options are available in the general settings of the plugin:

  ----- General settings -------------------------------------
  'Check every (minutes)'
  'Log c-client-callbacks'
  ----- MailBox-View -----------------------------------------
  'Font'
  ----- Mail-List-View ---------------------------------------
  'Sort order'
  'Font'
  ----- Mail-View --------------------------------------------
  'Header font'
  'Body font'
  'Scroll lines'
  'Word-wrap mode'

Note: Some entries are only available in special configurations:
- 'Check every (minutes)' is only available if the plugin was
  started with the -m option.
- The four 'Font' entries are only available with vdr-1.2.6+ElchiAIO3c
  and vdr-1.3.x.
- 'Log c-client-callbacks' is only available if vdr was started
  with log-level 3 ('-l 3').

The options:

- General settings: 'Check every (minutes)'
  Sets the interval (in minutes) for the mail-checker-thread
  to check for new mail.
  Values: 0..60, 0 disables this feature, default is 0 (= off)

- General settings: 'Log c-client-callbacks'
  Enables additional logging in the c-client library.
  Values: 'yes'/'no', default is 'no'

- MailBox-View: 'Font'
- Mail-List-View: 'Font'
- Mail-View: 'Header font'
- Mail-View: 'Body font'
  Use normal or small osd-fonts in the osd menus.
  Values: 'normal'/'small', default is 'normal'

- Mail-List-View: 'Sort order'
  Sort the mails in ascending or descending order in the
  mail-list-view.
  Values: 'ascending'/'descending', default is 'ascending'

- Mail-View: 'Scroll lines'
  Number of lines to scroll when cursor up or down is pressed.
  Values: 1..5, default is 1

- Mail-View: 'Word-wrap mode'
  Select the mode for word-wrapping at osd boundaries in mail-view.
  There are 4 modes/levels to adjust the word wrapping:
  (higher levels include the lower levels)
  0: wrapping as before
  1: when a quoted line (a line that starts with one or more '>')
     must be wrapped at the osd boundaries, the same number
     of quote-characters are prepended to the second part of
     the wrapped line.
  2: Lines that end with 'soft breaks' (SPACE + CRLF) in
     mail-parts that have the parameter "format=flowed" set, are
     treated as 'flowed lines' and therefore concatenated with the
     following line (see RFC 2646).
  3: Two consecutive lines are concatenated if the first line ends with
     a lower character ('a'-'z') and the following line starts with a
     lower character and both lines start with the same number of quote
     characters.

  The default-value is 2 as (the implementation of) this level is
  more or less compliant to a standard.

4.4 Setting up mail accounts
----------------------------
If you press [red] when a mail account is selected or [green] in
the configuration menu, vdr displays another dialog to edit the
settings for the new or the existing account.

The following data fields are currently present:

  Account-Name    : A readable string for the account. This is used to
                    display information on the osd and has no further
                    meaning.
  User-Name       : Name of the user to login to the mail server
  Password        : Password of the user to login to the mail server
  MailBox         : Name of the mailbox to access, see below.
  AutoMarkSeen    : Flag: if true the plugin marks every mail
                    automatically as read (\Seen) when displayed.
                    (only with IMAP accounts)
  CleanupOnClose  : Flag: if true the plugin deletes all mails which
                    have the \Deleted flag set when a mailbox is closed.
  Background check: Disable the background check of this mail-account
                    with 'off' or select the action that should be
                    executed whenever the number of new mails changed.
                    Currently the only possible action is 'ext. app.'
                    to start the external program/script which must
                    be given to the plugin with the option '-m'.
                    Note: This option is only available if 'Check
                    every (minutes)' in the general settings is enabled.
                    Default is 'off'

The 'MailBox' field needs some more explanation:

The mailbox plugin directly forwards the string in this field to the
c-client-library, which itself uses this string to reach the mail
account. C-client supports different ways of connecting to a mail
account, such as using certificates with TLS/SSL, rsh and plain text
passwords.

Note: I exclusively use the transmission of plain text passwords, as I
consider my local network relatively secure. So I didn't bother about
the more secure ways to connect to the mail server. Therefore I don't
know (right now) how these mechanisms work and I don't know if these
can be used with the mailbox-plugin.

If you consider this unsecure either deal with this security mechanisms
and find out if they can be used with this plugin (and drop me a mail
about your experiences) or simply don't use this plugin at all.

For an explanation of the format of the 'Mailbox' string, have a look
at http://www.washington.edu/imap/documentation/naming.txt.html

For short:
To simply login to the mail server using plain text password
transmission you could use something like

for IMAP:

  MailBox: {<MailServer>/imap/notls/norsh}

for POP3:

  MailBox: {<MailServer>/pop3/notls}

Please replace the '<MailServer>' with the hostname of your mail server.

c-client by default tries first the most secure ways to connect to the
mail server. By setting the options "/notls" and "/norsh" we simply
disable these options.

IMAP accounts only: This plugin currently doesn't support browsing
through folders of an account. Nevertheless it's possible to show mails
of folders. Therefore you simply have to configure another account and
enter the name of the folder in the 'MailBox' string.

For example with the following MailBox name it's possible to reach the
folder Lists.vdr in the INBOX.

  MailBox: {<MailServer>/imap/notls/norsh}INBOX.Lists.vdr

This works if the "hierarchy delimiter" (see RFC 3501) of your IMAP
server is a dot ('.'), which is the case for the courier imapd. If
your IMAP server uses another character for directory separation,
you'll probably have to use this character.

When you are finished editing the settings for a mail account, press
OK to leave the mail account settings dialog. The settings for the
accounts are only saved, if you press OK again to leave the setup dialog
of the plugin.

ATTENTION: The account settings are stored in a plain text file in a
directory 'plugins/mailbox' below the directory where vdr stores its
setup files. The file will be created with umask 0x600, so only the
user which executes vdr is able to read this file.

If you consider this unsecure, don't use this plugin!

5. Usage:
=========

5.1 Overview
------------

Generally there are three different osd-menus when using the mailbox-
plugin:

- mailbox-view  : displays a list of all configured mail accounts
                  with the number of new mails and the total number
                  of mails.

- mail-list-view: displays a list of all mails within a mailbox with
                  status flags, subject and sender.

- mail-view     : displays the subject, sender, date/time and text
                  of one mail.

When the plugin is activated from the main menu of vdr the mailbox-
view is displayed. After selecting the desired mail account and
pressing appropriate key the mail-list-view displays all mails within
the selected account. From within the mail-list-view the mail-view
can be activated to display the selected mail.

5.2 mailbox-view
----------------

When the main menu entry is selected, the mailbox-plugin checks the
number of new (not \Seen) mails and the total number of mails for all
configured mail accounts and displays them in a list.

Following keys are usable within mailbox-view:

  [Cursor keys] select a mail account.
  [OK]          open mail-list-view for the selected account
                and display all mails.
  [Red]         not used (will become the function 'open mail
                account to view all new mails')
  [Green]       open mail-list-view for the selected account
                and display all mails.
  [Blue]        refresh all mail accounts
  [Back]        close mailbox-plugin, return to vdr's main menu


5.3 mail-list-view
------------------

The plugin reads the headers (Flags/Subject/From) of all mails
within the selected mailbox. In the mail-list-view the plugin displays
a list of all mails with status flags, subject- and from-line.

The flags are displayed with the following characters:

  'N' - \Seen     is not set ('N' for *N*ew)
  'F' - \Flagged  is set
  'A' - \Answered is set
  'D' - \Deleted  is set

Following keys are usable within the 'mail-list-view':

  [Cursor keys] select a mail
  [OK]          open a mail with the 'mail-view'
  [Back]        close 'mail-list-view' and return to 'mailbox-view'
  [Green  | 7]  jump to the previous new mail
  [Yellow | 9]  jump to the next new mail
  [Blue]        activate alternative functions for the color-keys
                to set the status flags of the selected mail (see below)

Green and Yellow were chosen to behave similar to watch a recording
where these do 'big' jumps (60sec) backwards and forwards. The keys
7 and 9 were chosen to work as if working with the cut marks, where
7 and 9 do 'big' jumps between the cut marks.

If the user presses the [Blue] key in the view above, the color-keys
have the following functions:

  [Red]         toggle the 'New' (not \Seen) state of the selected mail
  [Green]       toggle the \Flagged state of the selected mail
  [Yellow]      toggle the \Deleted state of the selected mail
  [Blue]        get back the functions of the color-keys as described
                above

Note: For POP3-accounts the states \Flagged and \Seen aren't stored
at the mail server.

If you press 'Back' to close the mailbox and if you configured
'CleanupOnClose' in the setup menu of this account, all mails with
the \Deleted flag set will get expunged from this mailbox.

5.4 mail-view
-------------

The plugin reads the mail from the server and displays the 'Subject'-,
'From'-line, date/time and the body of the mail. If the mail is a
single-part-mail the whole message text gets fetched. If the mail
is a multipart mail only the parts with content-type text are fetched
(IMAP only).
Note: The plugin only displays mail-parts with content-type text.

When displaying a mulitpart mail the plugin separates the parts by
lines indicating the part number, content-type, encoding and sub-
type. Such a separator looks for example like this:
'---[P 2: TEXT/7BIT/PLAIN]----------------'

Following keys are used within the 'mail-view':

  [Cursor keys] scroll within the mail text
  [Back]        close 'mail-view' and return to 'mail-list-view'
  [FastRev| 4]  jump to the previous mail
  [FastFF | 6]  jump to the next mail
  [Green  | 7]  jump to the previous new mail
  [Yellow | 9]  jump to the next new mail
  [Blue]        activate alternative functions for the color-keys
                to set the status flags of the selected mail (see below)
  [0]           switch through the different word-wrap modes.

Green and Yellow were chosen to behave similar to watch a recording
where these do 'big' jumps (60sec) backwards and forwards.
FastRev / FastFF do the 'small movements'. The keys 4, 6, 7 and 9
were chosen to work as if working with the cut marks, where 4 and 6
do 'small' jumps between P|I-(or whatever they are called)-frames
and 7 and 9 do 'big' jumps between the cut marks.

If your configured 'AutoMarkSeen' in the setup menu of this mail
account the \Seen flag will be set for every mail which is displayed
in the 'mail-view'.

If the user presses the [Blue] key in the view above, the color-keys
have the following functions:

  [Red]         toggle the 'New' (not \Seen) state of the current mail
  [Green]       toggle the \Flagged state of the current mail
  [Yellow]      toggle the \Deleted state of the current mail
  [Blue]        get back the functions of the color-keys as described
                above

Note: For POP3-accounts the states \Flagged and \Seen aren't stored
at the mail server.

The mail is wrapped at the osd boundaries according to the selected
'Word-wrap mode' in the 'General settings' of the plugin. With the
key '0' it's possible to switch through the different word-wrap
modes for the current 'mail-view'.


6. Known Problems / Todo:
=========================
(not in order of priority, no promises if these will ever get
implemented!)

- When opening a folder the plugin loads the headers of all mails and
  creates an osdItem for every mail. If the folder has very much (1000
  is ok, 20000 is bad) mails, the plugin/vdr gets into trouble (very
  slowly). As it doesn't make sense to to create that much items anyhow,
  the handling of mailboxes should be improved.

- Only view/download new messages in the 'mail-list-view' and the
  'mail-view' (to improve performance when handling folders with
  many mails)

- Browse in the 'directory' tree of an imap account to select a
  mail folder.

- Allow the user to optionally assign a numerical code to every
  mail account. These mail accounts with codes can only be opened or
  edited after entering the numerical code with the remote.
  (this has a very low priority for me!)

7.  Thanks
==========
Last but not least, I want to thank Klaus Schmidinger for his
incredible work on VDR, the plugin-developers, the developers of
the DVB-drivers and Mark Crispin for developing the c-client-library,
all the users for their valuable feedback and everyone else I may
have forgotten...

Have fun,
  Alex
