1 /*

     2 * Copyright (c) 2006 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:  Encapsulates all the clients

    15 *

    16 */

    17 

    18 

    19 #ifndef CMPXCLIENTLIST_H

    20 #define CMPXCLIENTLIST_H

    21 

    22 // INCLUDES

    23 #include <e32base.h>

    24 #include <mpxmessage.h>

    25 #include <mpxmessage2.h>

    26 

    27 // CLASS FORWARDS

    28 class CMPXMessageQueue;

    29 class MMPXClientlistObserver;

    30 class CMPXSubscription;

    31 

    32 /**

    33 *   Manages a list of clients.

    34 *

    35 *   @lib mpxcommon.lib

    36 */

    37 class CMPXClientList : public CBase

    38     {

    39 public:

    40     /**

    41     * Two-phased constructor.

    42     *

    43     * @since S60 3.2.3

    44     * @param aObserver observer of the client list

    45     * @return object of constructed

    46     */

    47     IMPORT_C static CMPXClientList* NewL(MMPXClientlistObserver* aObserver = NULL);

    48 

    49     /**

    50     * Destructor.

    51     *

    52     * @since S60 3.2.3

    53     */

    54     IMPORT_C virtual ~CMPXClientList();

    55 

    56 public:

    57     /**

    58     * Add  another client into the list.

    59     *

    60     * @since S60 3.2.3

    61     * @param aId thread id of the client

    62     * @param aMsgQueue message queue for the client

    63     * @leave The function leaves with one of the system wide error codes,

    64     *         if the operation fails.

    65     */

    66     IMPORT_C void AddClientL(TThreadId aId,

    67                              CMPXMessageQueue* aMsgQueue);

    68 

    69     /**

    70     * Add  another client into the list.

    71     *

    72     * @since S60 3.2.3

    73     * @param aId thread id of the client

    74     * @param aMode client mode

    75     * @param aMsgQueue message queue for the client

    76     * @leave The function leaves with one of the system wide error codes,

    77     *         if the operation fails.

    78     */

    79     IMPORT_C void AddClientL(TThreadId aId,

    80                              TInt aMode,

    81                              CMPXMessageQueue* aMsgQueue);

    82 							 

    83 

    84 	/**

    85     * Add  another client into the list.

    86     *

    87     * @since S60 3.2.3

    88     * @param aId thread id of the client

    89     * @param aMode client mode

    90     * @param aMsgQueue message queue for the client

    91 	* @param aCategory category of the client, refer to TMPXCategory

    92     * @leave The function leaves with one of the system wide error codes,

    93     *         if the operation fails.

    94     */

    95     IMPORT_C void AddClientL(TThreadId aId,

    96                              TInt aMode,

    97                              CMPXMessageQueue* aMsgQueue,

    98                              const TInt aCategory);

    99 

   100     /**

   101     * Remove a client at a specified position.

   102     *

   103     * @since S60 3.2.3

   104     * @param aIndex The position within the list from where the client is to

   105     *                be removed

   106     * @panic USER 130, if aIndex is out of bound

   107     */

   108     IMPORT_C void RemoveClient(TInt aIndex);

   109 

   110     /**

   111     * The number of clients.

   112     *

   113     * @since S60 3.2.3

   114     * @return number of the clients

   115     */

   116     IMPORT_C TInt ClientCount() const;

   117 

   118     /**

   119     * A list of process ids of all the clients in this list.

   120     *

   121     * @since S60 3.2.3

   122     * @return array of process id of clients

   123     */

   124     IMPORT_C TArray<TProcessId> ClientProcessList() const;

   125 

   126     /**

   127     * Is this (denoted by thread id) a client in this list?.

   128     *

   129     * @since S60 3.2.3

   130     * @param aId thread id of the client

   131     * @return ETrue, the client is in the list

   132     */

   133     IMPORT_C TBool IsClient(TThreadId aId) const;

   134 

   135     /**

   136     * Find a client denoted by message queue in this list.

   137     *

   138     * @since S60 3.2.3

   139     * @param aMsgQueue Message queue for the client

   140     * @return The index of the client within the list

   141     *          KErrNotFound, if no matching object can be found

   142     */

   143     IMPORT_C TInt Find(const CMPXMessageQueue& aMsgQueue) const;

   144 

   145     /**

   146     * Find a client denoted by thread id in the list.

   147     *

   148     * @since S60 3.2.3

   149     * @param aId thread id of the client

   150     * @return TInt index to the client list

   151     */

   152     IMPORT_C TInt Find(TThreadId aId) const;

   153 

   154     /**

   155     * Return client mode.

   156     *

   157     * @since S60 3.2.3

   158     * @param aIndex index to the client

   159     * @return the mode of client

   160     * @panic USER 0 if aIndex out of bound

   161     */

   162     IMPORT_C TInt ClientMode(TInt aIndex) const;

   163 

   164 	/**

   165     * Return client category.

   166     *

   167     * @since S60 3.2.3

   168     * @param aIndex index to the client

   169     * @return the category of client

   170     * @panic USER 0 if aIndex out of bound

   171     */

   172     IMPORT_C TInt ClientCategory(TInt aIndex) const;

   173 

   174 

   175     /**

   176     * Dispatches message to all clients.

   177     *

   178     * @since S60 3.2.3

   179     * @param aMsg message, pointer to message, ownership not transferred.

   180     * @param aError error code

   181     */

   182     IMPORT_C void SendMsg(const CMPXMessage* aMsg, TInt aError);

   183 

   184     /**

   185     * Dispatches message to a client.

   186     *

   187     * @since S60 3.2.3

   188     * @param aIndex index to the client

   189     * @param aMsg message object, ownership not transferred.

   190     * @param aError error code

   191     */

   192     IMPORT_C void SendMsg(TInt aIndex, const CMPXMessage* aMsg, TInt aError);

   193 

   194     /**

   195      * Adds a subscription to a client identified by a specified position.

   196      *

   197      * @since S60 3.2.3

   198      * @param aIndex The position within the list where the client is.

   199      * @param aSubscription subscription to add. Ownership is transferred.

   200      */

   201     IMPORT_C void AddSubscriptionL(

   202         TInt aIndex,

   203         CMPXSubscription* aSubscription);

   204 

   205     /**

   206      * Removes a subscription from a client identified by a specified position.

   207      *

   208      * @since S60 3.2.3

   209      * @param aIndex The position within the list where the client is.

   210      * @param aSubscription subscription to remove.

   211      */

   212     IMPORT_C void RemoveSubscriptionL(

   213         TInt aIndex,

   214         const CMPXSubscription& aSubscription);

   215 

   216     /**

   217      * Removes all subscriptions from a client identified by a specified position.

   218      *

   219      * @since S60 3.2.3

   220      * @param aIndex The position within the list where the client is.

   221      */

   222     IMPORT_C void RemoveAllSubscriptionsL(TInt aIndex);

   223 

   224     /**

   225      * Convert TMPXMessage into CMPXMessage.

   226      *

   227      * @since S60 3.2.3

   228      * @param aMsg TMPXMessage message

   229      * @return CMPXMessage object

   230      * @leave The function leaves with one of the system wide error codes,

   231      *         if the operation fails.

   232      * @deprecated should not be used

   233      */

   234      inline CMPXMessage* ConvertMsgLC(const TMPXMessage& aMsg);

   235 

   236     /** 

   237     * Dispatches message to all clients.

   238     *

   239     * @since S60 3.2.3

   240     * @param aMsg message

   241     * @leave The function leaves with one of the system wide error codes,

   242     *         if the operation fails.

   243     * @deprecated Use method CMPXClientList::SendMsg(const CMPXMessage* aMsg, 

   244     *          TInt aError) instead.

   245     */

   246     inline void SendMsgL(const TMPXMessage& aMsg);

   247 

   248     /** 

   249     * Dispatches message to a client.

   250     *

   251     * @since S60 3.2.3

   252     * @param aIndex index to the client

   253     * @param aMsg message

   254     * @leave The function leaves with one of the system wide error codes,

   255     *         if the operation fails.

   256     * @deprecated Use method CMPXClientList::SendMsg(TInt aIndex, 

   257     *         const CMPXMessage* aMsg, TInt aError) instead.

   258     */

   259     inline void SendMsgL(TInt aIndex, const TMPXMessage& aMsg);

   260 

   261 private:

   262     /**

   263     *  Encapsulates a client: all the information associated with a client of

   264     *  the playback utility interface.

   265     *

   266     *  @lib mpxcommon.lib

   267     */

   268     NONSHARABLE_CLASS(CClientId): public CBase

   269         {

   270     public:

   271         /**

   272         * Constructor.

   273         *

   274         * @since S60 3.2.3

   275         * @param aTid thread id of the client

   276         * @param aPid process id of the client

   277         * @param aMsgQueue message queue for the client

   278         */

   279         CClientId(TThreadId aTid,

   280                   TProcessId aPid,

   281                   CMPXMessageQueue* aMsgQueue);

   282 

   283         /**

   284         * Constructor.

   285         *

   286         * @since S60 3.2.3

   287         * @param aTid thread id of the client

   288         * @param aPid process id of the client

   289         * @param aMode client mode

   290         * @param aMsgQueue message queue for the client

   291         */

   292         CClientId(TThreadId aTid,

   293                   TProcessId aPid,

   294                   TInt aMode,

   295                   CMPXMessageQueue* aMsgQueue);

   296 

   297 	    /**

   298         * Constructor.

   299         *

   300         * @since S60 3.2.3

   301         * @param aTid thread id of the client

   302         * @param aPid process id of the client

   303         * @param aMode client mode

   304         * @param aMsgQueue message queue for the client

   305         * @param aCategory client category

   306         */

   307         CClientId(TThreadId aTid,

   308                   TProcessId aPid,

   309                   TInt aMode,

   310                   CMPXMessageQueue* aMsgQueue,

   311                   const TInt aCategory); 

   312 

   313         /**

   314         * Constructor.

   315         *

   316         * @since S60 3.2.3

   317         * @param aMsgQueue message queue for the client

   318         */

   319         CClientId(CMPXMessageQueue* aMsgQueue);

   320 

   321         /**

   322         * Constructor.

   323         *

   324         * @since S60 3.2.3

   325         * @param aTid thread id of the client

   326         */

   327         CClientId(TThreadId aTid);

   328 

   329         /**

   330         * Constructor.

   331         *

   332         * @since S60 3.2.3

   333         * @param aPid process id of the client

   334         */

   335         CClientId(TProcessId aPid);

   336 

   337         /**

   338          * Constructor.

   339          *

   340          * @since S60 3.2.3

   341          */

   342         CClientId();

   343 

   344         /**

   345          *  Destructor.

   346          *

   347          * @since S60 3.2.3

   348          */

   349         virtual ~CClientId();

   350 

   351         /**

   352         * Assignment operator.

   353         *

   354         * @since S60 3.2.3

   355         * @param aClientId client ID instance to assign from.

   356         * @return reference to the current updated instance.

   357         */

   358         CClientId& operator=(const CClientId& aClientId);

   359 

   360         /**

   361         * Adds a subscription to the client.

   362         *

   363         * @since S60 3.2.3

   364         * @param aSubscription subscription to add. Ownership is transferred.

   365         */

   366         void AddSubscriptionL(CMPXSubscription* aSubscription);

   367 

   368         /**

   369         * Removes a subscription from the client.

   370         *

   371         * @since S60 3.2.3

   372         * @param aSubscription subscription to remove.

   373         */

   374         void RemoveSubscriptionL(const CMPXSubscription& aSubscription);

   375 

   376         /**

   377         * Removes all subscriptions from the client.

   378         *

   379         * @since S60 3.2.3

   380         */

   381         void RemoveAllSubscriptionsL();

   382 

   383 

   384     public:

   385         TThreadId iTid;

   386         TProcessId iPid;

   387         TInt iMode;

   388         TInt iCategory;

   389         CMPXMessageQueue* iMsgQueue; // Not owned

   390         RPointerArray<CMPXSubscription> iSubscriptions; // array of subscriptions

   391         };

   392 private:

   393     /**

   394     * C++ constructor.

   395     *

   396     * @since S60 3.2.3

   397     * @param aObserver observer of the client list

   398     */

   399     CMPXClientList(MMPXClientlistObserver* aObserver);

   400 

   401     /**

   402     * 2nd phase constructor.

   403     *

   404     * @since S60 3.2.3

   405     */

   406     void ConstructL();

   407 

   408     /**

   409     * Check if the msg subscribed by the client.

   410     *

   411     * @since S60 3.2.3

   412     * @param aIndex index to the client

   413     * @param aMsg message object, ownership not transferred.

   414     * @param leave leave with system error code

   415     */

   416     TBool IsMsgSubscribedL(TInt aIndex, const CMPXMessage* aMsg);

   417 

   418     /**

   419     * Comparison function. If the names are set in the client objects, then

   420     * that's used to test for equality. Otherwise, if the thread ids are set,

   421     * that's used. Else, it's assumed that the equality test is based on process

   422     * ids.

   423     *

   424     * @since S60 3.2.3

   425     * @param aClient1 client id of the client 1

   426     * @param aClient2 client id of the client 2

   427     * @return  ETrue if two ids are the same

   428     */

   429     static TBool ClientsMatch(const CClientId& aClient1,

   430                               const CClientId& aClient2);

   431 private:

   432     TIdentityRelation<CClientId> iIdentity;

   433     RPointerArray<CClientId> iClients;

   434     RArray<TProcessId> iClientProcesses;

   435     MMPXClientlistObserver* iObserver;

   436     };

   437 

   438 #include "mpxclientlist.inl"

   439 

   440 #endif // CMPXCLIENTLIST_H