/*

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

 * All rights reserved.

 * This component and the accompanying materials are made available

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

 * which accompanies this distribution, and is available

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

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  

 *       Public ECom notification API for NcnList.

 *

 */

 #ifndef __MNCNNOTIFICATION_H__

 #define __MNCNNOTIFICATION_H__

 //  INCLUDES

 #include <e32base.h>

 #include <msvstd.h>

 #include <bamdesca.h>

 #include <ecom/ecom.h>

 #include <ecom/ecomresolverparams.h>

 // FORWARD DECLARATIONS

 // UID of this interface

 const TUid KNcnNotificationInterfaceUid = {0x101f8855};

 // CLASS DECLARATION

 /**

  * Public ECom notification API.

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

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

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

  *

  * Example usage

  *

  * @code

  * #include <badesca.h>	// CDesCArray

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

  *

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

  *  MNcnNotification* notifyNewMessageEcom = 0;

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

  *

  *  // Check for errors

  *  if(notifyNewMessageEcom && err == KErrNone)

  *      {

  *      // The interface is supported on this phone.

  *      CleanupDeletePushL(notifyNewMessageEcom);

  *

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

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

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

  *      CleanupStack::PushL(tempArray);

  *

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

  *		// This can return an error value.

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

  *

  *      // Cleanup the descriptor array.

  *      CleanupStack::PopAndDestroy(tempArray);

  *

  *      // Clean up the ECOM interface now.

  *      CleanupStack::PopAndDestroy(notifyNewMessageEcom);

  *      }

  * @endcode

  *

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

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

  * demonstrate correct useage of the CleanupStack

  */

 class MNcnNotification

     {

     private: // Enumerations

         /**

          * Indication type bit enumeration.

          */

         enum TIndicationTypeBits

             {

             /* Icon bit */

             EIndicationIconBit = 0x1,

             /* Tone bit */

             EIndicationToneBit = 0x2,

             /* Soft note bit */

             EIndicationSoftNoteBit = 0x4

             };

     public: // Enumerations

         /**

          * Indication type enumeration.

          */

         enum TIndicationType

             {

             /* Icon indication */

             EIndicationIcon = EIndicationIconBit,

             /* Normal indication */

             EIndicationNormal = EIndicationIconBit | EIndicationToneBit | EIndicationSoftNoteBit,

             /* Tone and icon indication */

             EIndicationToneAndIcon = EIndicationIconBit | EIndicationToneBit

             };

     public: // Constructor and destructor

        /**

         * ECom implementation class factory method.

         * Caller takes the ownership of the created object.

         * If interface needs to be pushed into CleanupStack,

         * remember to use the CleanupDeletePushL() function!

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

         * @return ECom implementation instance

         *

         *

         */

         static MNcnNotification* CreateMNcnNotificationL();

        /**

         * Destructor.

         */

         virtual ~MNcnNotification();

     public: // Interface

 		/**

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

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

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

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

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

          * navigation to the email folder

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

          * Implementation of aIndicationType may vary between devices

          *

          * @param aMailBox        The service id of the email MTM

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

          *                        of enumeration TIndicationType values.

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

          *

          * @return                KErrNone for success, or system error code

          */

         virtual TInt NewMessages( const TMsvId& aMailBox,

                                   TIndicationType aIndicationType,

                                   const MDesCArray& aInfo ) = 0;

         /**

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

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

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

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

          * @param aMailBox The id identifying the mailbox or mail

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

          *

          * @return         KErrNone for success, or some error code

          */

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

     private: // data

         // for ECom to identify plug-in instance

         TUid iDtor_ID_Key;

     };

 #include <MNcnNotification.inl>

 #endif // __MNCNNOTIFICATION_H__

 // End of File