1 /*

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

    19 

    20 

    21 /**

    22  @file

    23  @publishedPartner 

    24  @released

    25 */

    26 

    27 #ifndef MAUDIOCONTEXTOBSERVER_H

    28 #define MAUDIOCONTEXTOBSERVER_H

    29 

    30 #include <a3f/a3fbase.h>

    31 

    32 const TUid KUidA3FContextCommitUpdate		= {0x1028343E};

    33 const TUid KUidA3FContextPreEmptedCommit	= {0x1028343F};

    34 const TUid KUidA3FContextPreEmption			= {0x10283440};

    35 const TUid KUidA3FContextPreEmptionUpdate	= {0x10283441};

    36 const TUid KUidA3FContextUpdateComplete		= {0x10283442};

    37 const TUid KUidA3FContextAbort				= {0x10283443};

    38 

    39 /**

    40  * KUidA3FContextCommitUpdate - Follows a Commit() call. Signals that Commit() has been successfully received by MMRC 

    41  * and that update callbacks are about to follow.  Note will still be called if MMRC rejects the request for policy reasons 

    42  * – in which case, the callbacks will show the original value. 

    43  *if aError is not KErrNone, then the implementation tried to apply the change but this failed 

    44  * so that the implementation is “rolled-back” to the previous. However, KErrAbort says that this roll-back failed, 

    45  * and streams have been placed in a Dead state.

    46  *

    47  * KUidA3FContextPreEmptedCommit -  Follows a Commit() call, but signals that that MMRC is doing a simultaneous pre-emption. 

    48  * Update callbacks are about to follow, but these relate to the pre-emption. The original request is lost.

    49  * An error of KErrAbort says that the change MMRC requested failed, and typically streams are placed in a “Dead” mode.

    50  *

    51  * KUidA3FContextPreEmption -  Initial indication to the client that it is to be pre-empted. 

    52  * The client should treat the Context and its Components as “locked” – see below. 

    53  *

    54  * KUidA3FContextPreEmptionUpdate - Will follow a KUidA3FContextPreEmption and indicates that callbacks 

    55  * are about to start to indicate the update. An error of KErrAbort says that the change MMRC requested failed, 

    56  * and typically streams are placed in a “Dead” mode.

    57  * 

    58  * KUidA3FContextUpdateComplete - Signals that all callbacks are complete – Commit() can be called again, if required.

    59  *

    60  * KUidA3FContextAbort - Error occurred due to the commit or pre-emption cycle itself – 

    61  * that is something to do with the associated message passing mechanism etc. 

    62  * this terminates the whole cycle, whatever the current state. It should leave the context in a “reasonable state” 

    63  *– usually the original state.  aError gives the associated reason for this.

    64  */

    65 

    66 /*

    67  * Following Commit() or ContextEvent(KUidA3FContextPreEmption), the associated Context should be considered “locked” 

    68  * until the receipt of events KUidA3FContextCommitUpdate, KUidA3FContextPreEmptedCommit or KUidA3FContextPreEmptionUpdate. 

    69  * By locked it is meant that no changes shall be requested by the Client from the Context nor its associated Components, 

    70  * nor Commit() called.

    71  *

    72  * Following events KUidA3FContextCommitUpdate, KUidA3FContextPreEmptedCommit or KUidA3FContextPreEmptionUpdate, 

    73  * the Client can be requested changes to the Context and associated Components, but Commit() cannot be called.

    74  * 

    75  * Following event KUidA3FContextUpdateComplete Commit() can be called.

    76  *

    77  * Following the receipt of event KUidA3FContextPreEmptedCommit or KUidA3FPreEmptionUpdate, 

    78  * any pending requested changes to the Context or its Components are lost – there is an implied call to MAudioContext::Reset(). 

    79  */

    80 

    81 

    82 /**

    83  * Defines the interface for observing context states.

    84  */

    85 class MAudioContextObserver

    86 	{

    87 public:

    88 	/**

    89 	 * Callback to context observer to show progression through Commit() and pre-emption cycles.

    90 	 *

    91 	 * @param a Uid giving the specific event.

    92 	 * @param  an error code. KErrNone if successful, otherwise one of the system wide error codes.

    93 	*/

    94 	virtual void ContextEvent(TUid aEvent, TInt aError)=0;

    95 	};

    96 

    97 #endif // MAUDIOCONTEXTOBSERVER_H