--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/msg_pub/open_new_message_notification_api/inc/MNcnNotification.h Thu Dec 17 08:44:11 2009 +0200
@@ -0,0 +1,179 @@
+/*
+* 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