/*

* 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