1 /*

     2 * Copyright (c) 2006 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:  

    15 *       Public ECom notification API for NcnList.

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef __MNCNNOTIFICATION_H__

    22 #define __MNCNNOTIFICATION_H__

    23 

    24 //  INCLUDES

    25 #include <e32base.h>

    26 #include <msvstd.h>

    27 #include <bamdesca.h>

    28 #include <ecom/ecom.h>

    29 #include <ecom/ecomresolverparams.h>

    30 

    31 // FORWARD DECLARATIONS

    32 

    33 // UID of this interface

    34 const TUid KNcnNotificationInterfaceUid = {0x101f8855};

    35 

    36 // CLASS DECLARATION

    37 

    38 /**

    39  * Public ECom notification API.

    40  * This API allows the notification of new message(s) to the NcnList.

    41  * It's main purpose is to provide a mechanism for an email MTM to broadcast the arrival of new messages

    42  * and give the user an opportunity to navigate to the email folder

    43  *

    44  * Example usage

    45  *

    46  * @code

    47  * #include <badesca.h>	// CDesCArray

    48  * #include <mncnnotification.h>	// ECOM interface to notification system

    49  *

    50  *  // Get an instance of the ECOM interface to the notification system.

    51  *  MNcnNotification* notifyNewMessageEcom = 0;

    52  *  TRAP(err, notifyNewMessageEcom = MNcnNotification::CreateMNcnNotificationL());

    53  *

    54  *  // Check for errors

    55  *  if(notifyNewMessageEcom && err == KErrNone)

    56  *      {

    57  *      // The interface is supported on this phone.

    58  *      CleanupDeletePushL(notifyNewMessageEcom);

    59  *

    60  *      // Now notify the framework that new messages have been received

    61  *      // First create a descriptor array for aInfo - even though it isn't used presently.

    62  *      CDesCArray* tempArray = new (ELeave) CDesCArrayFlat(3);

    63  *      CleanupStack::PushL(tempArray);

    64  *

    65  *      // Notify the framework that there are new messages.

    66  *		// This can return an error value.

    67  *      err = notifyNewMessageEcom->NewMessages(aServiceId, MNcnNotification::EIndicationNormal, *tempArray);

    68  *

    69  *      // Cleanup the descriptor array.

    70  *      CleanupStack::PopAndDestroy(tempArray);

    71  *

    72  *      // Clean up the ECOM interface now.

    73  *      CleanupStack::PopAndDestroy(notifyNewMessageEcom);

    74  *      }

    75  * @endcode

    76  *

    77  * The example above shows the interface object being created and then destroyed immediately after use.

    78  * However, it is not necessary to create a new interface object for every function call. It is done here to

    79  * demonstrate correct useage of the CleanupStack

    80  */

    81 class MNcnNotification

    82     {

    83     private: // Enumerations

    84         /**

    85          * Indication type bit enumeration.

    86          */

    87         enum TIndicationTypeBits

    88             {

    89             /* Icon bit */

    90             EIndicationIconBit = 0x1,

    91 

    92             /* Tone bit */

    93             EIndicationToneBit = 0x2,

    94 

    95             /* Soft note bit */

    96             EIndicationSoftNoteBit = 0x4

    97             };

    98 

    99     public: // Enumerations

   100         /**

   101          * Indication type enumeration.

   102          */

   103         enum TIndicationType

   104             {

   105             /* Icon indication */

   106             EIndicationIcon = EIndicationIconBit,

   107 

   108             /* Normal indication */

   109             EIndicationNormal = EIndicationIconBit | EIndicationToneBit | EIndicationSoftNoteBit,

   110 

   111             /* Tone and icon indication */

   112             EIndicationToneAndIcon = EIndicationIconBit | EIndicationToneBit

   113             };

   114 

   115     public: // Constructor and destructor

   116 

   117        /**

   118         * ECom implementation class factory method.

   119         * Caller takes the ownership of the created object.

   120         * If interface needs to be pushed into CleanupStack,

   121         * remember to use the CleanupDeletePushL() function!

   122         * DO NOT USE CleanupStack::PushL()!!

   123         * @return ECom implementation instance

   124         *

   125         *

   126         */

   127         static MNcnNotification* CreateMNcnNotificationL();

   128 

   129        /**

   130         * Destructor.

   131         */

   132         virtual ~MNcnNotification();

   133 

   134     public: // Interface

   135 

   136 		/**

   137          * Called by Messaging Server -compatible 3rd party Email plugins

   138          * to inform NcnList that there is a new message (or more than one message).

   139          * It should not (necessarily) be called for each new message but, say, at the

   140          * end of synchronisation when one or more new messages have been received.

   141          * It displays a 'New email' message with softkeys allowing direct

   142          * navigation to the email folder

   143          * Parameter aInfo is reserved for future use and is not handled in any way currently.

   144          * Implementation of aIndicationType may vary between devices

   145          *

   146          * @param aMailBox        The service id of the email MTM

   147          * @param aIndicationType Indication type for new messages. May be any combination

   148          *                        of enumeration TIndicationType values.

   149          * @param aInfo           Optional info about message (subject, sender etc.). Not supported

   150          *

   151          * @return                KErrNone for success, or system error code

   152          */

   153         virtual TInt NewMessages( const TMsvId& aMailBox,

   154                                   TIndicationType aIndicationType,

   155                                   const MDesCArray& aInfo ) = 0;

   156 

   157         /**

   158          * Called by Messaging Server -compatible 3rd party Email plugins

   159          * wanting to make a request to mark certain new messages as unread.<BR>

   160          * Essentially, it sets the new message counter to zero for the given mailbox <BR>

   161          * The new messages  become 'old' messages but they remain marked as 'unread'.

   162          * @param aMailBox The id identifying the mailbox or mail

   163          *                 folder containing the message(s) to be marked as unread.

   164          *

   165          * @return         KErrNone for success, or some error code

   166          */

   167         virtual TInt MarkUnread( const TMsvId& aMailBox ) = 0;

   168 

   169     private: // data

   170 

   171         // for ECom to identify plug-in instance

   172         TUid iDtor_ID_Key;

   173     };

   174 

   175 #include <mncnnotification.inl>

   176 

   177 #endif // __MNCNNOTIFICATION_H__

   178 

   179 // End of File