1 /*

     2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: Email services API to be used through Qt Highway.

    15 *

    16 */

    17 

    18 #ifndef EMAIL_SERVICES_API_H

    19 #define EMAIL_SERVICES_API_H

    20 

    21 // Qt

    22 #include <QMetaType>

    23 #include <QString>

    24 

    25 // Platform

    26 #include <xqaiwdeclplat.h>

    27 

    28 

    29 /*!

    30     The flags which can be used with the service interfaces.

    31 */

    32 enum EmailServiceInterfaceFlags {

    33     EmailNoFlags = 0x0,

    34     EmailBackReturnsToMessageList = 0x1

    35 };

    36 

    37 Q_DECLARE_METATYPE(EmailServiceInterfaceFlags)

    38 

    39 

    40 /*!

    41     Keys for mail send service data.

    42 */

    43 static const QString emailSendSubjectKey = "subject";

    44 static const QString emailSendToKey = "to";

    45 static const QString emailSendCcKey = "cc";

    46 static const QString emailSendBccKey = "bcc";

    47 

    48 // MIME type for body text, e.g. "text/html". If this key is not defined,

    49 // emailSendBodyValueKey is treated as "text/plain".

    50 static const QString emailSendBodyMimeTypeKey = "mimeType";

    51 

    52 static const QString emailSendBodyTextKey = "body";

    53 static const QString emailSendAttachmentKey = "attachment";

    54 

    55 /*!

    56     Mail service name

    57 */

    58 static const QString emailServiceName("nmail");

    59 

    60 /*!

    61     Mail send service interface name.

    62 */

    63 static const QString emailFullServiceNameSend = emailServiceName + "." + XQI_EMAIL_MESSAGE_SEND;

    64 

    65 /*!

    66     Mailbox service full name.

    67 */

    68 static const QString emailFullServiceNameMailbox = emailServiceName + "." + XQI_EMAIL_INBOX_VIEW;

    69 

    70 

    71 /*!

    72     Message service full name.

    73 */

    74 static const QString emailFullServiceNameMessage = emailServiceName + "." + XQI_EMAIL_MESSAGE_VIEW;

    75 

    76 

    77 /*!

    78     \fn send(QVariant data)

    79     \param data The email message data e.g. recipients.

    80     \return 1 if success, 0 otherwise.

    81 

    82     The method opens the mail editor view and adds the given data into the view.

    83 

    84     The data is of type QMap<QString, QVariant> where the keys define the type

    85     of the data (e.g. recipient or mail subject). The values in the map for

    86     recipients (to, cc and bcc) may contain either strings (for a single

    87     recipient) or string lists (for multiple recipients).

    88 

    89     The method supports the following mail data:

    90         - recipients (to, cc and bcc) and

    91         - mail subject.

    92 

    93     This service is used via Qt Highway.

    94 

    95     Usage example:

    96 

    97         bool syncronous;

    98 

    99         XQServiceRequest request(emailFullServiceNameSend,

   100                                  XQOP_EMAIL_MESSAGE_SEND,

   101                                  syncronous);

   102 

   103         QMap<QString, QVariant> map;

   104 

   105         QStringList recipients;

   106         QString subject;

   107 

   108         ...

   109 

   110         map.insert(emailSendToKey, QVariant::fromValue(recipients));

   111         map.insert(emailSendSubjectKey, QVariant(subject));

   112 

   113         QList<QVariant> data;

   114         data.append(map);

   115         request.setArguments(data);

   116 

   117         QVariant returnValue;

   118         bool retVal = request.send(returnValue);

   119 */

   120 

   121 

   122 /*!

   123     \fn displayInboxByMailboxId(QVariant data)

   124     \param data The ID of the mailbox to open

   125     \return 1 if mailbox opened. 0 if mailbox ID was incorrect.

   126 

   127     This method opens a view for displaying the inbox of the given mailbox.

   128     It is intended to be used via Qt Highway.

   129 

   130     Usage example:

   131 

   132     XQServiceRequest request(

   133         emailFullServiceNameMailbox,

   134         XQOP_EMAIL_INBOX_VIEW,

   135         syncronous);

   136 

   137     QList<QVariant> list;

   138     list.append(QVariant(id));

   139     request.setArguments(list);

   140 

   141     QVariant returnValue;

   142     bool rval = request.send(returnValue);

   143 */

   144 

   145 

   146 /*!

   147     \fn viewMessage(QVariant idList, QVariant flags)

   148 

   149     This method opens the mail viewer view containing the specific message.

   150     It is intended to be used via Qt Highway.

   151 

   152 

   153     \param idList A list containing the required IDs for locating the wanted

   154                   message. The ID are the following (and should be placed in

   155                   the following order): mailbox ID, folder ID and message ID.

   156 

   157     \param flags The flags which can contain any values defined by

   158                  EmailServiceInterfaceFlags enumeration. The only flag

   159                  acknowledged by this interface is EmailBackReturnsToMessageList,

   160                  which, if given, will add the message list (according to the

   161                  given mailbox and folder IDs) into the view stack. This means

   162                  that when the back button is pressed from the viewer view, the

   163                  message list view will be shown.

   164 

   165     \return 1 if message was opened. 0 if one of the IDs was incorrect.

   166 

   167 

   168     Usage example:

   169 

   170     XQServiceRequest request(

   171        emailFullServiceNameMessage,

   172        XQOP_EMAIL_MESSAGE_VIEW,

   173        synchronous);

   174 

   175     QVariantList idList;

   176     idList.append(mailboxId);

   177     idList.append(folderId);

   178     idList.append(messageId);

   179     QVariant idListAsVariant = QVariant::fromValue(idList);

   180 

   181     // Add the message list view into the view stack. If the list view should

   182     // not be added into the stack, use "quint64 flags(EmailNoFlags);" instead.

   183     quint64 flags(EmailBackReturnsToMessageList);

   184 

   185     QList<QVariant> argumentList;

   186     argumentList.append(idListAsVariant);

   187     argumentList.append(flags);

   188 

   189     request.setArguments(argumentList);

   190 

   191     QVariant returnValue;

   192 

   193     bool rval = request.send(returnValue);

   194 */

   195 

   196 

   197 #endif // EMAIL_SERVICES_API_H