iptel_plat/cch_client_api/inc/cchui.h
changeset 0 a4daefaec16c
equal deleted inserted replaced
-1:000000000000 0:a4daefaec16c
       
     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