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 // CLASS DECLARATION

    27 /**

    28  * Strictly typed observer notify mediator.

    29  *

    30  * Template typed interface to manage observer notifications

    31  * and notify errors. Typical mediator implementation

    32  * should notify given observer with type specific way.

    33  *

    34  * Notify mediator encapsulates the observer array management

    35  * (done by RGenericObserverArray) from observer type specific

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

    37  *

    38  * @since 2.1

    39  */

    40 template <class T, class P>

    41 class MGenObserverNotifyMediator

    42     {

    43     public:

    44 

    45         /**

    46          * Observer notification.

    47          *

    48          * Template method to implement observer notification.

    49          * If notification handling leaves, the leave error

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

    51          * MediateNotifyError() method.

    52          *

    53          * @since 2.1

    54          * @param aObserverToNotify The observer to notify.

    55          * @param aNotifyData Data to use in notification.

    56          */

    57         virtual void MediateNotifyL( T& aObserverToNotify,

    58                                      P& aNotifyData ) = 0;

    59 

    60         /**

    61          * Observer notification from error.

    62          *

    63          * Reports the leave error propagated from

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

    65          *

    66          * @since 2.1

    67          * @param aObserverToNotify The notified observer which leaved.

    68          * @param aLeaveError The propagated leave code.

    69          */

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

    71 

    72 

    73         /**

    74          * Observer notification from error.

    75          *

    76          * Reports an error to mediator.

    77          *

    78          * @since 2.1

    79          * @param aObserverToNotify The observer to notify.

    80          * @param aError The errorcode.

    81          */

    82         virtual void MediateError( T& aObserverToNotify, TInt aError ) = 0;

    83 

    84 

    85     protected:

    86 

    87         /**

    88          * Protected destructor.

    89          */

    90         virtual ~MGenObserverNotifyMediator() {}

    91     };

    92 

    93 

    94 

    95 

    96 // CLASS DECLARATION

    97 /**

    98  * Type templated generic observer array to manage

    99  * and notify observers.

   100  *

   101  * Generic observer array to manage observers and notify them

   102  * Adds typesafety with thin template to generic

   103  * RGenericObserverArrayBase. Observer notification is done

   104  * trough generic MGenObserverNotifyMediatorBase notify

   105  * mediator. Array functionality supports observer remove and

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

   107  * observers.

   108  *

   109  * @since 2.1

   110  */

   111 template <class T, class P>

   112 class RGenericObserverArray : public RGenericObserverArrayBase

   113     {

   114     public: //Constructor / destructor.

   115 

   116         /**

   117          * C++ constructor.

   118          */

   119         inline RGenericObserverArray();

   120 

   121 

   122         /**

   123          * Closes the array.

   124          *

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

   126          * The function must be called before this array object

   127          * goes out of scope.

   128          *

   129          * NOTE!

   130          * The function does not delete the observers whose pointers

   131          * are contained in the array.

   132          */

   133         void Close();

   134 

   135 

   136     public:  //Methods to maintain observers

   137 

   138 

   139         /**

   140          * Adds observer, handles errors by returning

   141          * error code.

   142          *

   143          * Adds observer, observer must point to valid

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

   145          *

   146          * @since 2.1

   147          * @see AddObserverL

   148          * @param aObserver The observer to add.

   149          * @return KErrNone is successful.

   150          * KErrNoMemory if out of memory.

   151          * KErrArgument if aObserver is NULL.

   152          */

   153         inline TInt AddObserver( const T* aObserver );

   154 

   155 

   156         /**

   157          * Adds observer, handles errors by leaving.

   158          *

   159          * Adds observer, observer must point to valid

   160          * object. If aObserver is NULL, leaves with

   161          * KErrArgument.

   162          *

   163          * @since 2.1

   164          * @see AddObserver

   165          * @param aObserver The observer to add.

   166          */

   167         inline void AddObserverL( const T* aObserver );

   168 

   169 

   170         /**

   171          * Removes observer.

   172          *

   173          * @since 2.1

   174          * @param aObserver The observer to remove.

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

   176          */

   177         inline TInt RemoveObserver( T* aObserver );

   178 

   179 

   180         /**

   181          * Observer count.

   182          *

   183          * Gets observer count.

   184          *

   185          * @since 2.1

   186          * @return Current observer count.

   187          */

   188         inline TInt Count();

   189 

   190 

   191     public:  //Methods to notify observers

   192 

   193         /**

   194          * Observer notify implementation.

   195          *

   196          * Notifies registered observers using given

   197          * observer notify mediator. Prior notify

   198          * loop protects the internal observer array

   199          * state against loop time observer removing.

   200          *

   201          * @since 2.1

   202          * @param aNotifyMediator The notify mediator to

   203          * use to notify the observers. Usage of mediator

   204          * separates the real notify details from observer

   205          * array managing details.

   206          * @param aNotifyData The notification data to give

   207          * to mediator to do the notification. Can be e.g. a

   208          * structure containing the notify details.

   209          */

   210         inline void NotifyObservers( MGenObserverNotifyMediator<T, P>& aNotifyMediator,

   211                                      P& aNotifyData );

   212 

   213 

   214         /**

   215          * Observer notify from error implementation.

   216          *

   217          * Notifies registered observers using given

   218          * observer notify mediator from error.

   219          * Prior notify loop protects the internal

   220          * observer array state against loop time

   221          * observer removing.

   222          *

   223          * @since 2.1

   224          * @param aNotifyMediator The notify mediator to

   225          * use to notify the observers. Usage of mediator

   226          * separates the real notify details from observer

   227          * array managing details.

   228          * @param aError The error code to notify.

   229          */

   230         //Too long template name for debug

   231 #pragma warning( disable : 4786 )  // CSI: 67 # Removing compiler warning

   232         void NotifyObserversFromError( MGenObserverNotifyMediator< T, P>& aNotifyMediator,

   233                                        TInt aError );

   234 #pragma warning( default : 4786 ) // CSI: 67 # Removing compiler warning

   235     };

   236 

   237 

   238 // Inline methods

   239 #include "RGenericObserverArray.inl"

   240 

   241 #endif      //__RGENERICOBSERVERARRAY_H

   242 //  End of File

   243 

   244