1 /*

     2 * Copyright (c) 2004 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:  Thin templated RGenericObserverArray.

    15 *

    16 */

    17 

    18 #ifndef __RGENERICOBSERVERARRAY_H__

    19 #define __RGENERICOBSERVERARRAY_H__

    20 

    21 //  INCLUDES

    22 #include <E32Base.h>

    23 #include "RGenericObserverArrayBase.h"

    24 

    25 

    26 

    27 // CLASS DECLARATION

    28 /**

    29  * Strictly typed observer notify mediator.

    30  *

    31  * Template typed interface to manage observer notifications

    32  * and notify errors. Typical mediator implementation

    33  * should notify given observer with type specific way.

    34  *

    35  * Notify mediator encapsulates the observer array management

    36  * (done by RGenericObserverArray) from observer type specific

    37  * notify details (implemented by concrete notify mediator).

    38  *

    39  * @since 3.0

    40  */

    41 template < class T >

    42 class MGenObserverNotifyMediator

    43     {

    44     public:

    45 

    46         /**

    47          * Observer notification.

    48          *

    49          * Template method to implement observer notification.

    50          * If notification handling leaves, the leave error

    51          * is reported back for the to same observer using the

    52          * MediateNotifyError() method.

    53          *

    54          * @since 3.0

    55          * @param aObserverToNotify The observer to notify.

    56          * @param aNotifyData Data to use in notification.

    57          */

    58         virtual void MediateNotifyL( T& aObserverToNotify ) = 0;

    59 

    60 

    61         /**

    62          * Observer notification from error.

    63          *

    64          * Reports the leave error propagated from

    65          * previous MediateNotifyL() call, back to mediator.

    66          *

    67          * @since 3.0

    68          * @param aObserverToNotify The notified observer which leaved.

    69          * @param aLeaveError The propagated leave code.

    70          */

    71         virtual void MediateNotifyError( T& aObserverToNotify, TInt aLeaveError ) = 0;

    72 

    73 

    74 

    75     protected:

    76 

    77         /**

    78          * Protected destructor.

    79          */

    80         virtual ~MGenObserverNotifyMediator() {}

    81     };

    82 

    83 

    84 

    85 

    86 // CLASS DECLARATION

    87 /**

    88  * Type templated generic observer array to manage

    89  * and notify observers.

    90  *

    91  * Generic observer array to manage observers and notify them

    92  * Adds type safety with thin template to generic

    93  * RGenericObserverArrayBase. Observer notification is done

    94  * trough generic MGenObserverNotifyMediatorBase notify

    95  * mediator. Array functionality supports observer remove and

    96  * add during the notify loop. Array doesn't own registered

    97  * observers.

    98  *

    99  * @since 3.0

   100  */

   101 template < class T >

   102 class RGenericObserverArray :

   103             private RGenericObserverArrayBase       // CSI: 70 #

   104     {

   105     public: //Constructor / destructor.

   106 

   107         /**

   108          * C++ constructor.

   109          */

   110         inline RGenericObserverArray();

   111 

   112 

   113         /**

   114          * Closes the array.

   115          *

   116          * Closes the array and frees all memory allocated to it.

   117          * The function must be called before this array object

   118          * goes out of scope.

   119          *

   120          * NOTE!

   121          * The function does not delete the observers whose pointers

   122          * are contained in the array.

   123          */

   124         void Close();

   125 

   126 

   127     public:  //Methods to maintain observers

   128 

   129 

   130         /**

   131          * Adds observer, handles errors by returning

   132          * error code.

   133          *

   134          * Adds observer, observer must point to valid

   135          * object. If aObserver is NULL, returns KErrArgument.

   136          *

   137          * @since 3.0

   138          * @see AddObserverL

   139          * @param aObserver The observer to add.

   140          * @return KErrNone is successful.

   141          * KErrNoMemory if out of memory.

   142          * KErrArgument if aObserver is NULL.

   143          */

   144         inline TInt AddObserver( const T* aObserver );

   145 

   146 

   147         /**

   148          * Adds observer, handles errors by leaving.

   149          *

   150          * Adds observer, observer must point to valid

   151          * object. If aObserver is NULL, leaves with

   152          * KErrArgument.

   153          *

   154          * @since 3.0

   155          * @see AddObserver

   156          * @param aObserver The observer to add.

   157          */

   158         inline void AddObserverL( const T* aObserver );

   159 

   160 

   161         /**

   162          * Removes observer.

   163          *

   164          * @since 3.0

   165          * @param aObserver The observer to remove.

   166          * @return KErrNone if observer was found, else KErrNotFound.

   167          */

   168         inline TInt RemoveObserver( T* aObserver );

   169 

   170 

   171         /**

   172          * Observer count.

   173          *

   174          * Gets observer count.

   175          *

   176          * @since 3.0

   177          * @return Current observer count.

   178          */

   179         inline TInt Count();

   180 

   181 

   182     public:  //Methods to notify observers

   183 

   184         /**

   185          * Observer notify implementation.

   186          *

   187          * Notifies registered observers using given

   188          * observer notify mediator. Prior notify

   189          * loop protects the internal observer array

   190          * state against loop time observer removing.

   191          *

   192          * @since 3.0

   193          * @param aNotifyMediator The notify mediator to

   194          * use to notify the observers. Usage of mediator

   195          * separates the real notify details from observer

   196          * array managing details.

   197          */

   198         inline void NotifyObservers( MGenObserverNotifyMediator< T >& aNotifyMediator );

   199 

   200 

   201 

   202 

   203         /**

   204          * Observer notify implementation.

   205          *

   206          * Notifies registered observers using given

   207          * observer notify mediator from given error.

   208          * Prior notify loop protects the internal

   209          * observer array state against loop time

   210          * observer removing.

   211          *

   212          * @since 3.0

   213          * @param aNotifyMediator The notify mediator to

   214          * use to notify the observers. Usage of mediator

   215          * separates the real notify details from observer

   216          * array managing details.

   217          * @param aError The error to mediate to error observers.

   218          */

   219         inline void NotifyErrorObservers( MGenObserverNotifyMediator< T >& aNotifyMediator,

   220                                           TInt aError );

   221 

   222 

   223 

   224         /**

   225          * Checks is the notify loop running.

   226          *

   227          * @return ETrue if notify loop is running. Else EFalse.

   228          */

   229         inline TBool NotifyLoopRunning() const;

   230 

   231     };

   232 

   233 

   234 // Inline methods

   235 #include "RGenericObserverArray.inl"

   236 

   237 #endif      //__RGENERICOBSERVERARRAY_H__

   238 //  End of File

   239 

   240