Documentation »  ACCESS Linux Platform Native Development »  Messaging Guide »  Email

The Email component of Postal Services is handled by two plug-ins: the POP plug-in, which can receive email from POP3 servers, and the IMAP plug-in, which can synchronize email with IMAP4 servers. Both plug-ins are described in this chapter. Unless otherwise noted, "POP" and "IMAP" are used interchangeably; information about the POP plug-in applies to the IMAP plug-in.

Email Capabilities ^TOP^

With the POP Email plug-in, client applications can create and manage a list of email accounts in the Postal Services database. Accounts should meet these requirements:

• Accounts must include certain POP3 (or IMAP4 settings) as defined in postal_pop_account.h, but may optionally include SMTP server settings as well.
• After an account is created in the Postal Services database, the plug-in must "validate" it. After an account is validated, the plug-in may use the account to receive or synchronize email data with a remote email server.

The POP plug-in also provides utilities for managing sessions, such as retrieving a list of active sessions and cancelling sessions. Like all Postal Services plug-ins, sending and receiving email data is a background activity that only requires the email client application to start, monitor, or cancel sessions, but not to run them.

Managing Email Accounts ^TOP^

Email accounts are managed with a combination of common Postal Services APIs used by all Messaging plug-ins, and by APIs specific to Email plug-ins. This section supplements the generic Postal Services information in Chapter 2, "Programming Messaging Applications" by providing details specific to Email services.

Creating, Updating, and Listing Email Accounts ^TOP^

Email plug-ins use the common APIs provided by Postal Services to handle Account objects. To create, update, or list an email account, therefore, you can refer to postal_account.h, or see Chapter 2, "Programming Messaging Applications." The chapter describes how to work with Postal Services Account objects, and includes sample code. For example, Listing 2.1 illustrates how to create an account.

Note that the while Email plug-ins make use of common Postal Services APIs, they use only one generic Postal Services Account property: ALP_POSTAL_PROPERTY_ACCOUNT_NAME. All other Email plug-in account properties are defined in postal_pop_account.h. The header file also defines SMTP server properties, which can be used with email accounts that can both send and receive email.

Deleting an Email Account ^TOP^

Before a client application can delete an email account, the client must perform the following operations:

1. Attempt to cancel any sessions that may be active for that account.

   For example, to delete an Email account, the client application calls alp_postal_pop_get_session_info_list() to obtain a list of active POP sessions for the account. The client then calls alp_postal_pop_session_cancel() on each active session.

   Note that the client should allow a few seconds for each "cancel" operation to complete before deleting the account itself.

2. Remove any Attention Manager alerts for the account.

   The following code provides an example of how to remove Attention Manager alerts:

   ---

   alp_status_t err = ALP_STATUS_OK; 
   char alertHandleP[10]; 
    
   // Clear any Attention Manager items for the given account 
   sprintf(alertHandleP, "%d", deleteAccountId); 
   err = 
   alp_attn_alert_delete(ALP_POSTAL_EMAIL_ATTENTION_SOURCE, 
       ALP_POSTAL_EMAIL_ATTENTION_NAME, alertHandleP);  
   

   ---

3. Delete the Postal Account database record, after all references to the account have been removed.

   ---

   // Delete the account from Postal database 
   err = alp_postal_account_delete(
       deleteAccountServiceId, deleteAccountId); 
   

   ---

Validating an Email Account ^TOP^

Validation is required for newly created email accounts. Client applications cannot request that an Email plug-in begin sending or receiving data until the account has been validated.

Account validation ensures that the user has provided appropriate input. A validation session includes these steps:

1. Connect to the mail server (POP or IMAP and SMTP, if SMTP server settings were provided)
2. Check that the mail server supports the minimum capabilities required by the Email plug-in
3. Attempt to authenticate the user using the credentials and login settings provided
4. Disconnect from the mail server

When an email account is created, the ALP_POSTAL_POP_PROPERTY_ACCOUNT_VALIDATED property should be set to false. After alp_postal_pop_session_validate_account() is called, the Email plug-in will change the property to true if account validation is successful. The client application may then allow the user to send and receive information using the new account.

Sending and Receiving Email ^TOP^

Starting a Session ^TOP^

To send or receive data, you must start a session by allocating a new sessionID value and passing it to the appropriate Postal session APIs (e.g., alp_postal_pop_session_send()).

The following code sample illustrates how to start a new session on a POP account to send everything in the Outbox, and then receive new email:

alp_postal_session_id_t sessionId; 
alp_status_t err; 
 
err = alp_postal_service_create_session(serviceId, accountId,
    &sessionId); 
err = alp_postal_pop_session_send_and_receive_all(sessionId,
    true, NULL);  

The true parameter passed to alp_postal_pop_session_send_and_recieve_all() indicates to the plug-in that the session was requested by a manual sync operation, as opposed to an automated or scheduled sync operation. The plug-in requires information about the type of sync operation (manual or automated) for two reasons:

• To assist the ACCESS Linux Platform Jumplist application in killing the session.

  Jumplist shows which applications are currently active on a device, and allows users to cancel manual sync operations. If the session was automated, additional warnings appear when Jumplist attempts to cancel the operation.

• To guide the email plug-in when opening a new connection with the Connection Manager.

  When a manual sync operation is initiated, the Email plug-in assumes the user is present and available to interact with the device. Therefore, during a manual sync, the client attempts to connect with the Connection Manager to turn on the device display. Through a message on the display, the user can then be prompted to turn on the radio, if necessary.

Most callers will probably not want to rely on an asynchronous reply callback, which is why NULL is passed into the function alp_postal_pop_session_send_and_recieve_all(). In many cases, the caller's process may have ended before the session completes and before the asynchronous reply callback can be called.

Alternatively, the client application can register an observer for one of the special email postal notifications: ALP_POSTAL_POP_NOTIFICATION_SESSION_FINISHED. This notification is sent by the plug-in when the session finishes, and contains all relevant information about the session and the result.

Understanding Offline Commands ^TOP^

Offline commands record actions that occur when the email client is offline: marking a message "read" or deleting a message from the device, for example. While developers cannot interact with offline commands on ACCESS Linux Platform, you should be aware of how Email plug-ins handle offline commands in response to the user's management of messages and performance of sync operations.

Email plug-ins keep track of offline commands by intercepting generic postal service APIs, which create "Offline Command" entries in the Postal database for each email account. When a sync operation is performed, the plug-in will attempt to process all offline commands for the given account, and then synchronizes those changes to the server.

For IMAP accounts, a sync operation performed on a specific folder within an email account will execute offline commands for the entire account, not just commands that apply to the selected folder.

Table 4.1  Operations that Generate Offline Commands

Listing and Cancelling Sessions ^TOP^

The Email plug-in provides a function to get detailed information about sessions that are in progress: alp_postal_pop_get_session_info_list(). Using this function, you can find all active sessions, or discover active sessions of a certain type.

To cancel any type of active online session, the plug-in must call alp_postal_pop_session_cancel(). The function instructs the session to cancel, and the API immediately returns after making the request. Note that the session may continue briefly to clean up resources and disconnect from the server. The session's AlpPostalEmailSessionFinishedNotificationCallback will be called with ALP_POSTAL_EMAIL_RESULT_USER_CANCEL when the session is ultimately finished.

Using Notifications and Alerts ^TOP^

Postal Services provide generic notifications and alerts that can be used by all messaging plug-ins. The notifications and alerts described in this section are specific to Email plug-ins.

Sending and Receiving Postal Notifications ^TOP^

Email services define three notifications that can be used by Email plug-ins:

• ALP_POSTAL_POP_NOTIFICATION_SESSION_STARTING
• ALP_POSTAL_POP_NOTIFICATION_SESSION_FINISHED

  Like all Postal Services plug-ins, Email plug-ins generate generic notifications when a session starts and ends. However, Email plug-ins also use email-specific versions, which provide additional information about the session. The "starting" and "finished" notifications are broadcast just before connecting a session, and just after the session has disconnected.

• ALP_POSTAL_POP_NOTIFICATION_SYNC_PROGRESS

  This notification provides information about what occurs during a given session. The notification includes the account details, type of service, the sessionId value and session type, whether or not a cancel request has been received, and detailed information about the current state of the session.

  Note that these notifications are only generated by the plug-in if one or more clients has enabled them by calling alp_postal_pop_service_enable_sync_progress_notifications(). Because notifications are expensive in terms of performance, clients should only enable these notifications when they plan to use them to display data. For example, a client might use this notification to support drawing a sync progress dialog. This notifications should not be used to collect and store information for later processing, as generating it will slow down the system.

Handling Attention Manager Alerts ^TOP^

The Email plug-ins communicate directly with the Attention Manager, which is described in the ACCESS Linux Platform Application Programming Guide. When a new email message is received and the main email client is running as the primary application, no Attention Manager alerts are generated. When the main email client is not running, the Email plug-ins will post an Attention Manager item indicating receipt of a new email message for the given account. Each email account can have a maximum of one "new email" alert. When the user launches the primary email client and opens any folder for a given account, the client should clear the Attention Manager item by calling alp_postal_service_create_session() and alp_postal_pop_session_send_and_receive_all() for that account, as described in "Starting a Session."

The main email client can indicate to Email plug-ins whether or not it is running by calling alp_postal_pop_service_post_attention_alerts() and passing false when the application launches, which will suppress attention alerts. The client should pass true when the application exits, which allows alerts to be generated again.

For more information about interacting with Email alerts, see postal_email_attention.h and hiker/exgmgr_verbs.h.