'Keep in Touch' Example

Files:

• keepintouch/addressfinder.cpp
• keepintouch/addressfinder.h
• keepintouch/main.cpp
• keepintouch/keepintouch.pro

This example demonstrates using the Qt Mobility Messaging API to extract useful information from the messages stored by the system.

The 'Keep in Touch' application locates people you have sent messages to in the past, but with whom you have not communicated recently. It defines a user-selected date range in the past, beginning a certain amount of time ago and finishing more recently. Any address that you sent a message to in this period is located. Any address that you sent a message to more recently than this period will not be displayed. So, now might be a good time to say hello to the people whose addresses are reported!

We find addresses when the user clicks the Search button. First of all we find the dates that define the period that the user has selected.

     QDateTime now(QDateTime::currentDateTime());
     bool useExclusionPeriod(excludeCheckBox->isChecked());

     // Determine the dates that demarcate the selected range
     QDateTime minimumDate(now);
     switch (includePeriod->currentIndex()) {
         case 0: minimumDate = minimumDate.addMonths(-12); break;
         case 1: minimumDate = minimumDate.addMonths(-9); break;
         case 2: minimumDate = minimumDate.addMonths(-6); break;
         case 3: minimumDate = minimumDate.addMonths(-3); break;
         case 4: minimumDate = minimumDate.addMonths(-1); break;
         case 5: minimumDate = minimumDate.addDays(-7); break;
         default: break;
     }

     QDateTime maximumDate(now);
     if (useExclusionPeriod) {
         // We have an exclusion period to apply
         switch (excludePeriod->currentIndex()) {
             case 0: maximumDate = maximumDate.addDays(-7); break;
             case 1: maximumDate = maximumDate.addMonths(-1); break;
             case 2: maximumDate = maximumDate.addMonths(-3); break;
             case 3: maximumDate = maximumDate.addMonths(-6); break;
             case 4: maximumDate = maximumDate.addMonths(-9); break;
             default: break;
         }
     }

We create filter objects that will constrain our message search to the date range that the user has selected:

     // We will include addresses contacted following the minimum date
     QMessageFilter includeFilter(QMessageFilter::byTimeStamp(minimumDate, QMessageDataComparator::GreaterThanEqual));
     // Windows mobile only sets a receptionTimeStamp for sent messsages
     includeFilter |= QMessageFilter::byReceptionTimeStamp(minimumDate, QMessageDataComparator::GreaterThanEqual);

     QMessageFilter excludeFilter;
     if (useExclusionPeriod) {
         // We will exclude addresses contacted following the maximum date
         excludeFilter = QMessageFilter::byTimeStamp(maximumDate, QMessageDataComparator::GreaterThanEqual);
         excludeFilter |= QMessageFilter::byReceptionTimeStamp(maximumDate, QMessageDataComparator::GreaterThanEqual);
     }

Now we combine our filters to precisely specify the messages that we would like to inspect to perform our address search:

     // We only want to match messages that we sent
     QMessageFilter sentFilter(QMessageFilter::byStandardFolder(QMessage::SentFolder));

     // Create the filter needed to locate messages to search for addresses to include
     if (useExclusionPeriod) {
         inclusionFilter = (sentFilter & includeFilter & ~excludeFilter);
     } else {
         inclusionFilter = (sentFilter & includeFilter);
     }

Now that we know what messages to search for, we use an instance of QMessageService to perform our first search:

     if (useExclusionPeriod) {
         // Create the filter needed to locate messages whose address we will exclude
         QMessageFilter exclusionFilter;
         exclusionFilter = (sentFilter & excludeFilter);

         // Start the search for messages containing addresses to exclude
         service.queryMessages(exclusionFilter);
     } else {
         // Only search for messages containing addresses to include
         service.queryMessages(inclusionFilter);

         // Clear the inclusion filter to indicate that we have searched for it
         inclusionFilter = QMessageFilter();
     }

We could have queried the QMessageManager instance directly using the queryMessages function, but that would keep our UI thread busy, and we wouldn't be able to keep our UI functioning at the same time. Using the QMessageService interface allows us to process the search asynchronously.

We receive the notification of matching messages by responding to the QMessageService::messagesFound() signal:

 void AddressFinder::messagesFound(const QMessageIdList &ids)
 {
     // Add these IDs to the relevant set
     if (!inclusionFilter.isEmpty()) {
         exclusionMessages << ids;
     } else {
         inclusionMessages << ids;
     }
 }

When the search is completed, the QMessageService::stateChanged() signal is emitted. If the user specified an exclusion period then we have to perform two searches, so when the first finishes our handler initiates the second; when the second finishes, we begin processing the results:

 void AddressFinder::stateChanged(QMessageService::State newState)
 {
     if (searchAction->isEnabled() == false) {
         if (newState == QMessageService::FinishedState) {
             if (service.error() == QMessageManager::NoError) {
                 if (!inclusionFilter.isEmpty()) {
                     // Now find the included messages
                     service.queryMessages(inclusionFilter);

                     // Clear the inclusion filter to indicate that we have searched for it
                     inclusionFilter = QMessageFilter();
                 } else {
                     // We have found the exclusion and inclusion message sets
                     if (!inclusionMessages.isEmpty()) {
                         // Begin processing the message sets
                         QTimer::singleShot(0, this, SLOT(continueSearch()));

The continueSearch function processes the results of our searches, one message at a time. Each address we sent a message to in the excluded time period is added to our exclusion list. For each address we sent a message to in our included time period, and which is not in the exclusion list, we create a set of the messages that we sent to that address.

 void AddressFinder::continueSearch()
 {
     if (!exclusionMessages.isEmpty()) {
         // Take the first message whose addreses we should exclude
         QMessageId id(exclusionMessages.takeFirst());
         const QMessage message(id);

         // All recipient addresses are to be excluded
         foreach (const QMessageAddress &address, message.to() + message.cc() + message.bcc()) {
             excludedAddresses.insert(simpleAddress(address));
         }
     } else if (!inclusionMessages.isEmpty()) {
         // Take the first message to inspect for suitable addresses
         QMessageId id(inclusionMessages.takeFirst());
         const QMessage message(id);

         QString details;

         // For each recipient of this message
         foreach (const QMessageAddress &address, message.to() + message.cc() + message.bcc()) {
             QString addressOnly(simpleAddress(address));

             // Ignore recipients whose addresses we have added to the exclusion set
             if (!excludedAddresses.contains(addressOnly)) {
                 // Link this message to this address
                 QList<QPair<QString, QMessageId> > &messageList(addressMessages[addressOnly]);
                 if (messageList.isEmpty()) {
                     addressList.append(addressOnly);

                     // Add the recipient to our visible list of contacts to keep in touch with
 #ifdef USE_CONTACTS_COMBOBOX
                     contactList->addItem(contactDisplayName(address), addressOnly);
 #else
                     QListWidgetItem* newListWidgetItem = new QListWidgetItem(contactDisplayName(address));
                     newListWidgetItem->setData(Qt::UserRole, addressOnly);
                     contactList->addItem(newListWidgetItem);
 #endif
                 }

                 if (details.isEmpty()) {
                     // Determine the properties of the message
                     details = QString("[%1] %2").arg(message.date().toString("MMM d")).arg(message.subject());
                 }
                 messageList.append(qMakePair(details, id));
             }
         }
     }

     if (!exclusionMessages.isEmpty() || !inclusionMessages.isEmpty()) {
         // There are more messages to process
         QTimer::singleShot(0, this, SLOT(continueSearch()));
     } else {
         // We're finished our search
         setSearchActionEnabled(true);
 #ifndef USE_SEARCH_BUTTON
         tabChanged(1);
 #endif

 #ifdef USE_CONTACTS_COMBOBOX
         addressSelected(contactList->currentIndex());
 #else
         addressSelected(contactList->currentRow());
 #endif
     }
 }

We will display the resulting list of contacts in our Contacts pane. If the system contains a contact definition that matches the address information we extracted, we will display the label for that contact - this matching process can be accomplished using the Qt Mobility Contacts API. If we can't find a matching contact, we fall back to using the raw address information for display:

 QString contactDisplayName(const QMessageAddress &address)
 {
     QString addressOnly(simpleAddress(address));

     // See if we can match this address to a contact
     QContactDetailFilter filter;
     if (address.type() == QMessageAddress::Email) {
         // Match contacts on email address data
         filter.setDetailDefinitionName(QContactEmailAddress::DefinitionName, QContactEmailAddress::FieldEmailAddress);
         filter.setValue(addressOnly);
         filter.setMatchFlags(QContactFilter::MatchContains);
     } else if (address.type() == QMessageAddress::Phone) {
         // Match contacts on phone number data
         filter.setDetailDefinitionName(QContactPhoneNumber::DefinitionName, QContactPhoneNumber::FieldNumber);
         filter.setValue(addressOnly);
         filter.setMatchFlags(QContactFilter::MatchPhoneNumber);
     }

     QContactManager manager;
     foreach (const QContactLocalId &contactId, manager.contactIds(filter)) {
         // Any match is acceptable
         const QContact &contact(manager.contact(contactId));
         return contact.displayLabel();
     }

     // We couldn't match anything, so return the original address
     return address.addressee();
 }

If the user selects one of these contact addresses, we fill the Messages combo box with the list of messages that were previously sent to that contact:

 void AddressFinder::addressSelected(int index)
 {
     messageCombo->clear();

     if (index == -1)
         return;

 #ifdef USE_CONTACTS_COMBOBOX
     QString address = contactList->itemData(index).toString();
 #else
     QString address = contactList->item(index)->data(Qt::UserRole).toString();
 #endif

     QString addressOnly(simpleAddress(address));

     // Add the subject of each message to this address to the message pane
     typedef QPair<QString, QMessageId> MessageDetails;
     foreach (const MessageDetails &message, addressMessages[addressOnly]) {
         messageCombo->addItem(message.first);
     }
 }

When the user has selected a message, two further actions become possible. We can use the QMessageService facility to either view the message or to compose a new message to the recipient of the earlier message. To view the message we only need to invoke the show function for the relevant QMessageId:

 void AddressFinder::showMessage()
 {
     int index = messageCombo->currentIndex();
     if (index != -1) {
         // Find the address currently selected
         const QString &selectedAddress(addressList[
 #ifdef USE_CONTACTS_COMBOBOX
                 contactList->currentIndex()
 #else
                 contactList->currentRow()
 #endif
                 ]);

         // Show the message selected
         QMessageId &messageId((addressMessages[selectedAddress])[index].second);
         service.show(messageId);
     }
 }

To compose a response, we will create a new message that forwards the existing message content to the same recipient, and requests that the system display a message composer prepared with the message content we have prepared:

 void AddressFinder::forwardMessage()
 {
     int index = messageCombo->currentIndex();
     if (index != -1) {
         // Find the address currently selected
         const QString &selectedAddress(addressList[
 #ifdef USE_CONTACTS_COMBOBOX
                 contactList->currentIndex()
 #else
                 contactList->currentRow()
 #endif
                 ]);

         // Find the selected message
         QMessageId &messageId((addressMessages[selectedAddress])[index].second);
         QMessage original(messageId);

         // Create a message which forwards the selected message to the same recipient
         QMessage fwd(original.createResponseMessage(QMessage::Forward));
         fwd.setTo(original.to());
         service.compose(fwd);
     }
 }