/*

* Copyright (c) 2008-2008 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:  This file contains the header file of the MCchUi class.

*

*/

#ifndef M_CCHUI_H

#define M_CCHUI_H

#include <cch.h>

#include <cchuiobserver.h>

/**

 *  Virtual interface of cchui.

 *

 *  @code

 *   // One way to use CCHUI API is to configure which notes it shows

 *   // and after that do normal enable through CCH

 *   iCch = CCch::NewL();

 *   

 *   // Allow connectivity notes to be shown when enabling service

 *   iCch->SetConnectivityDialogsAllowed( ETrue );

 * 

 *   // Get handle to cchui api

 *   iCchUi = &iCch->CchUiApi(); // iCchUi is pointer to MCchUi

 * 

 *   // Set observer to listen cchui events.

 *   iCchUi->AddObserverL( *this );  // parameter is MCchUiObserver

 *   

 *   // Configure CCHUI API to show all notes/dialogs except connecting note.

 *   // Also configure that only VoIP and IM subservices are allowed (notes are

 *   // shown only for those).

 *   RArray<MCchUiObserver::TCchUiDialogType> allowedNotes;

 *   RArray<MCchUiObserver::TCchUiDialogType> allowedSubServices;

 *   CleanupClosePushL( allowedNotes );

 *   CleanupClosePushL( allowedSubServices );

 * 

 *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeAuthenticationFailed );

 *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeNoConnectionDefined );

 *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeNoConnectionAvailable );

 *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeChangeConnection );

 *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeDefectiveSettings );     

 *   

 *   allowedSubServices.AppendL( ECCHVoIPSub );

 *   allowedSubServices.AppendL( ECCHIMSub );

 * 

 *   iCchUi->ConfigureVisualizationL( 

 *       allowedNotes, allowedSubServices );

 *   

 *   CleanupStack::PopAndDestroy( &allowedNotes );

 *   

 *   CCchService* service = iCch->GetService( serviceId );

 *   service->Enable( ECCHUnknown );

 * 

 * 

 * 

 * 

 *   // Another way to use CCHUI API is to just show specific notes.

 *   iCch = CCch::NewL();

 *   

 *   // Get handle to cchui api

 *   iCchUi = &iCch->CchUiApi(); // iCchUi is pointer to MCchUi

 * 

 *   // Set observer to listen cchui events.

 *   iCchUi->AddObserverL( *this );  // parameter is MCchUiObserver

 * 

 *   // Show connecting dialog.

 *   iCchUi->ShowDialogL( 

 *       serviceId, 

 *       MCchUiObserver::ECchUiDialogTypeConnecting );

 * 

 *   // disable note by cancelling

 *   iCchUi->CancelNotes();

 * 

 *   // Remove observer

 *   iCchUi->RemoveObserver();  

 * 

 *  @endcode

 * 

 *  @lib cch.lib

 *  @since S60 5.0

 */

class MCchUi

    {

    public:

        /**

        * destructor

        */

        virtual ~MCchUi( ) {};

    public:

        /**

         * Adds observer for listening cchui events.

         *

         * @since S60 5.0

         * @param aObserver Event observing class

         */

        virtual void AddObserverL( MCchUiObserver& aObserver ) = 0;

        /**

         * Removes the observer of cchui events.

         * 

         * @since S60 5.0

         * @param aObserver Event observing class

         */

        virtual void RemoveObserver( MCchUiObserver& aObserver ) = 0;

        /**

         * Shows global note/dialog. See observer definition for available notes. 

         *

         * @since S60 5.0

         * @param aServiceId service id of the service that the dialog is 

         *        shown for. Service id is used to fetch service specific data.

         * @param aDialog defines which dialog is shown.

         * @leave KErrAlreadyExists Failed to show dialog because another 

         * note already shown.

         */

        virtual void ShowDialogL( 

            TUint32 aServiceId, 

            MCchUiObserver::TCchUiDialogType aDialog ) = 0;

        /**

         * Allows client to configure visualization of connectivity events. This

         * only effects the automatically shown connectivity notes. Client can

         * still use seperate methods in this API to show specific notes by

         * itself. 

         * 

         * By default all notes are allowed.

         *

         * @since S60 5.0

         * @param aAllowedNotes array of allowed notes

         */

        virtual void ConfigureVisualizationL( 

            RArray<MCchUiObserver::TCchUiDialogType>& aAllowedNotes,

            RArray<TCCHSubserviceType>& aAllowedSubServices ) = 0;    

        /**

         * Cancels all notes shown by CCH UI. 

         * If there is nothing to dismiss, call to this method does nothing.

         *

         * @since S60 5.0

         */

        virtual void CancelNotes() = 0;         

        /**

         * Reserved for future use.

         *

         * @since S60 5.0

         */    

        virtual void Reserved1() = 0;         

        /**

         * Reserved for future use.

         *

         * @since S60 5.0

         */    

        virtual void Reserved2() = 0;

    };

#endif // M_CCHUI_H