1 /*

     2 * Copyright (c) 2009 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:

    15 *

    16 */

    17 

    18 #ifndef TELEPHONYAUDIOROUTING_H

    19 #define TELEPHONYAUDIOROUTING_H

    20 

    21 #include <e32base.h>

    22 

    23 class MTelephonyAudioRoutingObserver;

    24 

    25 class CTelephonyAudioRouting

    26     {

    27     

    28     public:  // DATA TYPES

    29 

    30         //Output types

    31         enum TAudioOutput

    32             {

    33             ENotActive,

    34             ENone,

    35             EHandset,

    36             ELoudspeaker,

    37             EWiredAudioAccessory,

    38             EBTAudioAccessory,

    39             ETTY

    40             };

    41             

    42     public:

    43       

    44       

    45         /**

    46         * Factory interface returning a new instance of CTelephonyAudioRouting.

    47         *

    48         * If the server is not created by the Adaptation, this leaves with KErrNotReady.

    49         * If the client does not have MultimediaDD capability, this leaves with

    50         * KErrPermissionDenied.

    51         *

    52         * Leaves on failure.

    53         *

    54         * @since Series 60 3.1

    55         */

    56         static CTelephonyAudioRouting* NewL(

    57                             MTelephonyAudioRoutingObserver& aObserver );

    58                             

    59         ~CTelephonyAudioRouting();

    60 

    61         /**

    62         * Returns array of currently available outputs.

    63         * The array contains list of following outputs depending on whether the

    64         * output is available or not at the time of query:

    65         *  - EHandset

    66         *  - ELoudspeaker

    67         *  - EWiredAudioAccessory,

    68         *  - EWiredAccessory,

    69         *  - EBTAudioAccessory

    70         *  - ETTY

    71         * Audio can be routed to any of the available outputs in the list.

    72         *

    73         * @since Series 60 3.1

    74         * @param none.

    75         * @return TArray<TAudioOutput>& Array of available outputs.

    76         */     

    77         const TArray<TAudioOutput>& AvailableOutputs();

    78 

    79         /**

    80         * Returns the current output configured by the client application to play

    81         * telephony audio.

    82         * Possible values are:

    83         *  - ENotActive : If output has not been set by any or one of the

    84         *    telephony apps has called SetOutputL(ENotActive) successfully.

    85         *  - ENone : If user has destroyed audio link by long key press on the

    86         *    BT device.

    87         *  - EHandset or ELoudspeaker or EWiredAudioAccessory or

    88         *    EBTAudioAccessory or ETTY depending on the last successful

    89         *    SetOutputL() call. EBTAudioAccessory is also returned when adaptation

    90         *    routes audio from device to BT accessory automatically when user

    91         *    initiated long key press event occurs.

    92         *

    93         * @since Series 60 3.1

    94         * @param none.

    95         * @return TAudioOutput Current output.

    96         */       

    97         TAudioOutput Output();

    98 

    99         /**

   100         * Sends an asynchronous request to Adaptation to set the output

   101         * where telephony audio will be routed. This request is completed only

   102         * when the application receives

   103         * MTelephonyAudioRoutingObserver::SetOutputComplete callback.

   104         *

   105         * If MTelephonyAudioRoutingObserver::SetOutputComplete returns KErrNone,

   106         * aOutput requested by this application is configured by Adaptation.

   107         * Otherwise there was error configuring aOutput and application should

   108         * call CTelephonyAudioRouting::Output to get the active output.

   109         *

   110         * Leaves on following cases:

   111         *   - System wide error code when failure to send request.

   112         *   - KErrArgument when parameter is ENone.

   113         *   - KErrHardwareNotAvailable if aOutput is not in the list of available

   114         *       outputs.

   115         *

   116         * @since Series 60 3.1

   117         * @param aOutput : output requested by application. This can only be any

   118         *           of the outputs from AvailableOutputs() list or ENotActive.

   119         * @return none.

   120         */

   121         void SetOutputL( TAudioOutput aOutput = ENotActive );

   122         

   123         /**

   124         * Returns the second last output that was successfully configured to

   125         * play telephony audio.

   126         * Possible values are:

   127         *  - ENotActive : If output had not been set or one of the telephony

   128         *                 apps had previously called SetOutputL(ENotActive)

   129         *                 successfully.

   130         *  - EHandset or ELoudspeaker or EWiredAudioAccessory or

   131         *    EBTAudioAccessory or ETTY depending on the second last successful

   132         *    SetOutputL() call.

   133         *

   134         * @since Series 60 3.1

   135         * @param none.

   136         * @return TAudioOutput Previous output that was configured for telephony

   137         *           audio. ENone will never be returned since telephony apps cannot call

   138         *           SetOutputL(ENone).

   139         */

   140         TAudioOutput PreviousOutput();

   141 

   142         /*

   143         * Sends the Show Note mode to server along with the next SetOutputL()

   144         * request.

   145         *

   146         * After SetOutputL() request from the Application is succesfully

   147         * processed by the server and application receives SetOutputComplete()

   148         * callback with KErrNone, it can query Show Note mode sent to server by

   149         * calling GetShowNote().

   150         *

   151         * Other observers wanting to query Show Note mode can call GetShowNote()

   152         * after receiving OutputChanged() callback.

   153         *

   154         * @since Series 60 3.1

   155         * @param TBool aMode Show Note mode. ETrue or EFalse.

   156         * @return KErrNone if succesfull, otherwise system-wide error code.

   157         */

   158         TInt SetShowNote( TBool aMode );

   159         

   160         /*

   161         * Returns the the Show Note mode for the last succesfully completed

   162         * SetOutputL() request.

   163         *

   164         * If the routing is initiated by the Adaptation with BT Long key press

   165         * this will return ETrue.

   166         *

   167         * Once the Show Note mode is sent to server along with the SetOutputL()

   168         * request, Show Note mode attribute for that client session will be

   169         * reset to EFalse. GetShowNote() function for this client session will

   170         * return EFalse until SetOutputL() request is completed and the observer

   171         * receives OutputComplete() callback. If there is no error completing

   172         * the request, GetShowNote() returns the Show Note value set by the

   173         * Application. If there is error completing the request, GetShowNote()

   174         * will return EFalse.

   175         *

   176         * For all other observers, After they receive OutputChanged() callback,

   177         * GetShowNote() will return the Show Note value set by the Application

   178         * that called SetOutputL().

   179         *

   180         * @since Series 60 3.1

   181         * @param TBool aMode. On return of this function will contain

   182         *        Show Note mode. EFalse or ETrue.

   183         * @return KErrNone if succesfull, otherwise system-wide error code.

   184         */

   185         TInt GetShowNote( TBool& aMode );    

   186     

   187     private:

   188     

   189         CTelephonyAudioRouting( MTelephonyAudioRoutingObserver& aObserver );

   190         void ConstructL();

   191     

   192     public: // stub data

   193     

   194         MTelephonyAudioRoutingObserver& iObserver;

   195     

   196         RArray<TAudioOutput> iAvailableOutputs;

   197         TAudioOutput iCurrentOutput;

   198         TAudioOutput iPreviousOutput;

   199     

   200         TBool iShowNoteMode;

   201 

   202         // If this variable is set to other value than KErrNone, next operation

   203         // with no-fail quarantee fails either by leaving or by using return 

   204         // code. Failing code is value of variable. Operation requested is not 

   205         // completed. Variable is set to KErrNone before failing simulation.

   206 		TInt iForceFailWithCode;

   207     };

   208 

   209 

   210 // CLASS DECLARATION

   211 

   212 /**

   213 *  This class defines the TAR default data structure.

   214 *

   215 *  @lib TelephonyAudioRouting.lib

   216 *  @since 3.0

   217 */

   218 class TTelephonyAudioRoutingDefaultParams

   219     {

   220     public:

   221 

   222         /**

   223         * Constructor.

   224         */

   225         TTelephonyAudioRoutingDefaultParams() : iCurrentAudio(CTelephonyAudioRouting::ENotActive),iPreviousAudio(CTelephonyAudioRouting::ENotActive),iShowNoteMode(EFalse)

   226         {}

   227 

   228 		CTelephonyAudioRouting::TAudioOutput iCurrentAudio;

   229 		CTelephonyAudioRouting::TAudioOutput iPreviousAudio;

   230 		TBool iShowNoteMode;

   231 

   232     };

   233     

   234 

   235 

   236 #endif      // TELEPHONYAUDIOROUTING_H

   237