/*
* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  This API is used for creating mappings between remote
*                 control clients.
*
*/


#ifndef TSPCLIENTMAPPER_H
#define TSPCLIENTMAPPER_H

// INCLUDES
#include <e32base.h>
#include <e32std.h>

// CLASS DECLARATION

/**
* The tsp client mapper component is used to create mappings between remote
* control clients. The tsp client mapper is used in such cases where a client
* could not be correctly mapped by it's default information. For example if a
* remote control event is listened by the active audio client but the actual
* remote control client is in a different process than the one that is
* listening the remote control events. In this case a mapping has to be created
* between the active audio process and the remote control client. This mapping
* is created simply by setting the process identifier of the remote control
* client of the active audio to this api.
* Mapping types define the different states for the tsp clients. The states are
* defined in TTspClientMappingType. After one state is completed the mapping
* should be removed or set to another state. In the following an example
* where a value is set when a player is registered.
* @code
* CTspClientMapper* mapper = CTspClientMapper::NewLC();
* RThread client;
* RMessage2& message = aMessage;
* // Message from the client
* RProcess process;
* client.Process( process );
* TProcessId processId = proceess.Id();
* mapper->SetTspTargetClient( processId,
*                             CTspClientMapper::ERegisteredClients );
* CleanupStack::PopAndDestroy( mapper );
* @endcode
* 
* An example of changing the state of the remote control client:
*
* @code
* CTspClientMapper* mapper = CTspClientMapper::NewLC();
* RThread client;
* RMessage2& message = aMessage;
* // Message from the client
* RProcess process;
* client.Process( process );
* TProcessId processId = proceess.Id();
* mapper->SetTspTargetClientToOtherType( processId,
*                                        CTspClientMapper::EPlayingClients );
* CleanupStack::PopAndDestroy( mapper );
* @endcode
*
* An example of removing a tsp mapping client:
*
* @code
* CTspClientMapper* mapper = CTspClientMapper::NewLC();
* RThread client;
* RMessage2& message = aMessage;
* // Message from the client
* RProcess process;
* client.Process( process );
* TProcessId processId = proceess.Id();
* mapper->RemoveTspTargetClient( processId,
*                                CTspClientMapper::EPlayingClients );
* CleanupStack::PopAndDestroy( mapper );
* @endcode
* 
* @since S60 5.0
*/

class CTspClientMapper : public CBase
  {
public:
    
    friend class CRemConTspController;
    
    /**
    * Enumerations for tsp mapping types.
    *
    * EPlayingClients is used when the client is in playing state.
    * ERegisteredClients is used when the client is in registered state.
    * EStoppedClients is used when the client is in stopped state.
    */
    enum TTspClientMappingType
        {
        EPlayingClients = 0,
        ERegisteredClients,
        EStoppedClients
        };
    
    /**
    * Symbian two phased constructor.
    */
    IMPORT_C static CTspClientMapper* NewL();
    
    /**
    * Symbian two phased constructor. Puts the instance to cleanup stack.
    */
    IMPORT_C static CTspClientMapper* NewLC();
    
public: 

    /**
    * This function is used to set a target client for TSP. This way Target
    * Selector Plugin creates a mapping to the correct client.
    *
    * @param    aMappingType @see TspClientMappingType
    * @param    aProcessId is the process identifier of the client. If the
    *           process id is already in the array the process id that needs
    *           to be set is moved to the first place in the array.
    */
    virtual void SetTspTargetClient( 
        TTspClientMappingType aMappingType,
        TProcessId aProcessId ) = 0;
    
    /**
    * This function is used to set a TSP target client for another type then it
    * was originally set for. This way targets don't have to be removed from
    * one type and then added to another.
    *
    * @param    aMappingType is the type this client has to be set for
    * @param    aProcessId is the process identifier of the client
    * @return   KErrNotSupported if invalid mapping type. KErrNotFound if this
    *           ProcessId is not found from any of the arrays.
    */
    virtual TInt SetTspTargetClientToOtherType( 
        TTspClientMappingType aMappingType,
        TProcessId aProcessId ) = 0;
    
    /**
    * This function is used to remove a target client from TSP. This way Target
    * Selector Plugin creates a mapping to the correct client. The process id's
    * that are set to the tsp client mapper must be removed from the array
    * after the state is finished with this function. The mappings aren't
    * destroyed automatically in the destructor.
    *
    * @param    aMappingType @see TspClientMappingType
    * @param    aProcessId is the process identifier of the client
    * @return   KErrNotSupported if invalid mapping type, KErrNotFound if
    *           process id is not found in the array.
    */
    virtual TInt RemoveTspTargetClient(  
        TTspClientMappingType aMappingType,
        TProcessId aProcessId ) = 0;
    
    
    
private:
    
    /**
    * This function is used to get the audio clients that are currently
    * playing audio. The function is used by TSP.
    *
    * @param    aMappingType @see TspClientMappingType
    * @param    aPidArray is given as a reference. The playing audio clients
    *           are added to this array.
    * @return   aPidArray is returned with the asked process identifiers.
    *           KErrNotSupported if invalid mapping type.
    */
    virtual TInt GetTspTargetClients(  
        TTspClientMappingType aMappingType,
        RArray<TProcessId>& aPidArray ) = 0;

protected:    
    
    /**
    * Default Constructor 
    */
    CTspClientMapper();
    
    };

#endif // TSPCLIENTMAPPER_H

// End of File