1 /*

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

    15 *

    16 */

    17 

    18 

    19 #ifndef M_CCHUI_H

    20 #define M_CCHUI_H

    21 

    22 #include <cch.h>

    23 #include <cchuiobserver.h>

    24 

    25 /**

    26  *  Virtual interface of cchui.

    27  *

    28  *  @code

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

    30  *   // and after that do normal enable through CCH

    31  *   iCch = CCch::NewL();

    32  *   

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

    34  *   iCch->SetConnectivityDialogsAllowed( ETrue );

    35  * 

    36  *   // Get handle to cchui api

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

    38  * 

    39  *   // Set observer to listen cchui events.

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

    41  *   

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

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

    44  *   // shown only for those).

    45  *   RArray<MCchUiObserver::TCchUiDialogType> allowedNotes;

    46  *   RArray<MCchUiObserver::TCchUiDialogType> allowedSubServices;

    47  *   CleanupClosePushL( allowedNotes );

    48  *   CleanupClosePushL( allowedSubServices );

    49  * 

    50  *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeAuthenticationFailed );

    51  *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeNoConnectionDefined );

    52  *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeNoConnectionAvailable );

    53  *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeChangeConnection );

    54  *   allowedNotes.AppendL( MCchUiObserver::ECchUiDialogTypeDefectiveSettings );     

    55  *   

    56  *   allowedSubServices.AppendL( ECCHVoIPSub );

    57  *   allowedSubServices.AppendL( ECCHIMSub );

    58  * 

    59  *   iCchUi->ConfigureVisualizationL( 

    60  *       allowedNotes, allowedSubServices );

    61  *   

    62  *   CleanupStack::PopAndDestroy( &allowedNotes );

    63  *   

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

    65  *   service->Enable( ECCHUnknown );

    66  * 

    67  * 

    68  * 

    69  * 

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

    71  *   iCch = CCch::NewL();

    72  *   

    73  *   // Get handle to cchui api

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

    75  * 

    76  *   // Set observer to listen cchui events.

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

    78  * 

    79  *   // Show connecting dialog.

    80  *   iCchUi->ShowDialogL( 

    81  *       serviceId, 

    82  *       MCchUiObserver::ECchUiDialogTypeConnecting );

    83  * 

    84  *   // disable note by cancelling

    85  *   iCchUi->CancelNotes();

    86  * 

    87  *   // Remove observer

    88  *   iCchUi->RemoveObserver();  

    89  * 

    90  *  @endcode

    91  * 

    92  *  @lib cch.lib

    93  *  @since S60 5.0

    94  */

    95 class MCchUi

    96     {

    97     public:

    98         /**

    99         * destructor

   100         */

   101         virtual ~MCchUi( ) {};

   102         

   103     public:

   104         

   105         /**

   106          * Adds observer for listening cchui events.

   107          *

   108          * @since S60 5.0

   109          * @param aObserver Event observing class

   110          */

   111         virtual void AddObserverL( MCchUiObserver& aObserver ) = 0;

   112         

   113         /**

   114          * Removes the observer of cchui events.

   115          * 

   116          * @since S60 5.0

   117          * @param aObserver Event observing class

   118          */

   119         virtual void RemoveObserver( MCchUiObserver& aObserver ) = 0;

   120         

   121         /**

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

   123          *

   124          * @since S60 5.0

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

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

   127          * @param aDialog defines which dialog is shown.

   128          * @leave KErrAlreadyExists Failed to show dialog because another 

   129          * note already shown.

   130          */

   131         virtual void ShowDialogL( 

   132             TUint32 aServiceId, 

   133             MCchUiObserver::TCchUiDialogType aDialog ) = 0;

   134            

   135         /**

   136          * Allows client to configure visualization of connectivity events. This

   137          * only effects the automatically shown connectivity notes. Client can

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

   139          * itself. 

   140          * 

   141          * By default all notes are allowed.

   142          *

   143          * @since S60 5.0

   144          * @param aAllowedNotes array of allowed notes

   145          */

   146         virtual void ConfigureVisualizationL( 

   147             RArray<MCchUiObserver::TCchUiDialogType>& aAllowedNotes,

   148             RArray<TCCHSubserviceType>& aAllowedSubServices ) = 0;    

   149            

   150         /**

   151          * Cancels all notes shown by CCH UI. 

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

   153          *

   154          * @since S60 5.0

   155          */

   156         virtual void CancelNotes() = 0;         

   157            

   158         /**

   159          * Reserved for future use.

   160          *

   161          * @since S60 5.0

   162          */    

   163         virtual void Reserved1() = 0;         

   164 

   165         /**

   166          * Reserved for future use.

   167          *

   168          * @since S60 5.0

   169          */    

   170         virtual void Reserved2() = 0;

   171     };

   172 

   173 #endif // M_CCHUI_H