Unread count problems

About

IMAP has the STATUS command which can give you the amount of messages in a folder (MESSAGES parameter) and the amount of messages in a folder that are note flagged with SEEN (UNSEEN parameter). You can find out about STATUS in the IMAP RFC at section 6.3.10.

The application developer of an E-mail client, however, wants to know the amount of unread E-mails and by that his user means: the amount of unread E-mails that are not marked for removal (a lot E-mail clients hide the ones that are marked for removal and present the user with a Trash folder in stead).

With ESEARCH we could compose a query for this, but by far are not all IMAP servers in the field capable of serving you ESEARCH queries. We could count the messages that we have locally, but this has some problems:

  • Mobile E-mail clients are usually the secondary E-mail client of the end user, this means that another E-mail client can have marked messages as deleted behind our back. Our local cache store means nothing. We'd need to combine that with the local cache store of the primary E-mail client of the user. This is of course not available on the mobile device.
  • We don't always have this, for example at initial state (never synchronized)
  • Synchronizing is expensive on bandwidth. Especially on GPRS and especially for large folders and huge folder lists.
  • Even with ESEARCH we still have the first problem

Neglecting our local cache store is also a bad option (if we have one):

  • We don't count the items that got removed in this session (before the expunge and store happened)
  • Reading the ESEARCH and neglecting the local cache store yields incorrect results depending on the synchronization actions that have been undertaken already

Conclusion: depending on interpretation, availability of capabilities on the IMAP server and availability of local synchronized data we can often only approximately determine the actual unread count. Sometimes we can provide an exact unread count, though. We'll need a way for the application developer to know about the approximation.

This is a proposal, this is not yet how it is right now:

TnyFolder

The tny_folder_get_unread_count needs a byref certainty parameter indicating how certain we are. For example: 

typedef struct {
   /* Maybe have a type that tells the developer when a synchronization happened and how? */
   TNY_FOLDER_UNREAD_CERTAINTY_APPROXIMATE = 0,
   TNY_FOLDER_UNREAD_CERTAINTY_CERTAIN = 1,
} TnyFolderUnreadCertainty;

TnyFolder *folder = ...
gint unread;
TnyFolderUnreadCertainty certainty;
unread = tny_folder_get_unread_count (folder, &certainty);

Optionally, this should also be possible: 

unread = tny_folder_get_unread_count (folder, NULL);

TnyFolderStats

The tny_folder_stats_get_unread_count API needs a byref flags parameter just like tny_folder_get_unread_count. For example: 

TnyFolder *folder = ...
TnyFolderStats *stats;
gint unread;
TnyFolderUnreadCertainty certainty;
stats = tny_folder_get_stats (folder);
unread = tny_folder_stats_get_unread_count (folder, &certainty);
g_object_unref (stats);

Optionally, this should also be possible: 

unread = tny_folder_stats_get_unread_count (folder, NULL);

TnyGtkFolderStoreTreeModel

The TnyGtkFolderStoreTreeModel needs an extra column called unread_certainty: 

GtkTreeIter iter;
GtkTreeModel *model;
gint unread;
TnyFolderUnreadCertainty certainty;

gtk_tree_selection_get_selected (selection, &model, &iter);

gtk_tree_model_get (model, &iter, 
	TNY_GTK_FOLDER_STORE_TREE_MODEL_UNREAD_CERTAINTY_COLUMN, 
	&certainty, -1);
gtk_tree_model_get (model, &iter, 
	TNY_GTK_FOLDER_STORE_TREE_MODEL_UNREAD_COLUMN, 
	&unread, -1);