S60 Platform: POP/IMAP Example v1.2
-----------------------------------------------------------------------------

This example application shows how to retrieve e-mail from a remote mailbox 
to an S60 mobile device. The application contains both IMAP and 
POP implementations, which differ only slightly from each other due to 
the generic messaging framework in Symbian OS.

The application has a complete user interface and offers rich functionality 
for the user, because it uses the generic messaging architecture views 
through UiMtm->OpenL(). This means that the user can send, edit, and delete 
e-mail the same way it could be done with a built-in messaging application.

An example on how to use CAknWaitDialog and CAknInformationNote is included.

The application also shows how to get the correct MTM context for 
a message entry. A pointer is used to cast a derived class to a base class 
(CBaseMtm) so that the identity and members of the derived class are 
preserved. Either POP or IMAP utilizing the same code can be used.

The updated example has been modified to support S60 5th Edition and touch 
UI.

-----------------------------------------------------------------------------

PREREQUISITES

- Symbian C++ basics.

- For protocol details, go to http://www.ietf.org/rfc.html and refer to the 
  following specifications: 
    IMAP4: RFC-2060 
    POP3: RFC-1939 

-----------------------------------------------------------------------------

IMPORTANT FILES/CLASSES

CInternetEmailEngine.cpp     - Main state handler module.
CInternetEmailContainer.cpp  - Main UI module.

Classes:
CMsvSession
CClientMtmRegistry
CMtmUiRegistry
CMsvOperation
CMsvEntrySelection
CMsvEntry
CBaseMtm

-----------------------------------------------------------------------------

TOUCH UI SUPPORT

To support touch UI, touch event handling 
(MEikListBoxObserver::EEventItemDoubleClicked) was added into the 
CInternetEmailContainer::HandleListBoxEventL() method.

-----------------------------------------------------------------------------

KNOWN ISSUES

Generic messaging architecture support - some features of this 
architecture are not supported in this example application:

    If a message is deleted using this application, the view 
    is not updated. In other words, the view does not show that the message 
    has been deleted. However, the deleted message will disappear in the next
    synchronization.

    If an e-mail is forwarded using this example application, the 
    notification 'Message box in use' appears on the screen.

Incorrect service settings and corrupted MTM indexes:
        
    If the user has changed, for example, the IMAP settings in the 
    middle of an operation, and then tries to fetch the body of a message 
    whose header has been retrieved with the old settings, the outcome 
    is not defined. This application does not handle this 
    situation in a safe way. 

Server issues:

    This example has been tested against several common IMAP [port 143]
    and POP [port 110] servers. 

    NOTE: All tests were conducted without using extended authentication 
    methods, such as APOP. This should not cause any problems since 
    the extended authentication methods are supported by the device 
    protocol stacks.

    Common IMAP servers with IMAP4REV1 capability should work without 
    problems. On some servers, if the IMAP protocol is used, the call 
    chain generated from UiMtm->OpenL() will deadlock when 
    the progress dialog shows "updating inbox". The workaround solution 
    is to use another server and/or different server settings, or only 
    the POP protocol.

-----------------------------------------------------------------------------

PRECONDITIONS AND CONFIGURATION

The following settings must be configured for the example application:

Internet access point with TCP/IP (note that WAP settings are not 
sufficient). The Internet access point is usually received from the operator.
It might even be a built-in feature of the device (such as in the Nokia 6600
in some countries), or it can be set manually in the devices control panel 
via Tools > Settings > Connections > Access points. If necessary, refer to 
the users guide of the device.

For IMAP/POP settings in the built-in messaging application, select 
Messaging > Mailbox > Settings.

NOTE 1: This example application always uses the first IMAP and/or POP 
service entry that has been set. This means that you can have more than one 
service entry of each type but only the first entry of each type is used.

NOTE 2: The required e-mail service settings are username, 
password, and the URL of the receiving server. The protocol type must be 
either IMAP or POP. All other fields can contain the default value or any 
string. However, the configuration must correspond with the e-mail server 
used and the features it supports. If you want to send e-mail using the 
generic view, remember to also set the sending server, which should be the 
SMTP server.

-----------------------------------------------------------------------------

GMAIL IMAP SETTINGS

This is how to setup GMail IMAP settings in the Nokia N95:

   1. Enable IMAP in your Gmail settings.
   
   2. Select Messaging > Options > Settings > E-mail > Mailboxes.
   
   3. If you have never set up e-mail on your phone before, select Yes to 
      define a new mailbox. If you already have other mailboxes, select 
      Options > New mailbox.
      
   4. Select Start to begin the setup wizard.
   
   5. Select IMAP4 and then select Next.
   
   6. Enter your full Gmail address (including '@gmail.com') as the e-mail 
      address and select Next. For Google Apps users, enter your full address
      in the format 'username@your_domain.com'.
      
   7. Enter imap.gmail.com as the incoming mail server and select Next.
   
   8. Enter smtp.gmail.com as the outgoing mail server and select Next.
   
   9. Select the appropriate access point and then select Next.
   
  10. Enter a descriptive name for the e-mail account mailbox.
  
  11. Once your mailbox is set up, select it from the email mailbox settings 
      screen via Messaging > Gmail.
  
  12. Select Options > E-Mail Settings > Connection settings > 
      Incoming e-mail.
  
  13. Select SSL/TLS for your security (ports) and define your port as 993.
  
  14. Select Back.
  

For more information, see: 
http://mail.google.com/support/bin/answer.py?answer=78887&topic=12761

-----------------------------------------------------------------------------

RUNNING THE EXAMPLE

After you have configured the Internet and e-mail service settings, open the 
example application. You should see a blank screen with two basic choices: 
Options and Back. 

Select the protocol to use from Options > Set Protocol > POP3/IMAP4. If 
you have already retrieved messages to your local inbox, the messages 
should appear. Otherwise, the screen will be blank except for the new options
Exit and Get Mail.

To retrieve message headers from your remote inbox, select Get Mail. This 
feature requires an Internet connection. Retrieving messages may be time-
consuming - the more messages there are in the remote mailbox, the 
longer it will take to retrieve them. For this reason, the example 
application draws a modal progress dialog (CAknWaitDialog) on the screen.

To edit, view, send, or retrieve message bodies for a given header, select 
the message from the listbox in the main view.

-----------------------------------------------------------------------------

BUILD AND INSTALLATION INSTRUCTIONS

To build and install the example application, follow the standard 
procedures for installing Symbian OS applications.

--Mobile device:
    cd to /InternetEmail/group/
    bldmake bldfiles
    abld build gcce urel
    cd to /InternetEmail/sis/
    makesis InternetEmail_S60.pkg InternetEmail_v30.sis
    
    Sign the SIS package:
         For example, Signsis InternetEmail_v30.sis InternetEmail_v30.sis 
            DevCert_xx.cer Access.key 12345678

    Install the signed SIS package on the device.

--Emulator:
    cd to /InternetEmail/group/
    bldmake bldfiles
    abld build winscw udeb
    
    Start the emulator.

-----------------------------------------------------------------------------

COMPATIBILITY

    S60 5th Edition
    S60 3rd Edition, Feature Pack 2   
    S60 3rd Edition, Feature Pack 1
    S60 3rd Edition

    Tested on: Nokia 5800 XpressMusic, Nokia E90 Communicator, Nokia N95.

-----------------------------------------------------------------------------

VERSION HISTORY

1.2 S60 5th SDK support added and S60 1st/2nd Edition support removed.
1.1 Application updated to support S60 3rd Edition.
1.0 First release.