// Copyright (c) 2004-2009 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:

//

/**

 @file

 @publishedPartner

 @released

*/

#ifndef TARGETSELECTORPLUGININTERFACE_H

#define TARGETSELECTORPLUGININTERFACE_H

#include <e32base.h>

class MRemConTargetSelectorPluginObserver;

class TRemConAddress;

class TClientInfo;

class TBearerSecurity;

class TClientInfoConstIter;

/**

The UID of this version of the Target Selector Plugin interface.

*/

const TInt KRemConTargetSelectorInterface1 = 0x10208BCD;

/**

Abstract base class for target selector plugins.

*/

class MRemConTargetSelectorPluginInterface

	{

public:

	/**

	Called by RemCon to get the TSP to address an outgoing command (from a 

	connectionless controller client) to zero or more remotes. The implementor 

	should add zero or more items to aConnections and then call 

	OutgoingCommandAddressed on the observer with an appropriate error.

	Note that only one of AddressOutgoingCommand and PermitOutgoingCommand is 

	outstanding at once.

	The implementor is responsible for the capability check. For this reason, 

	aSender contains the client's current send message, and aBearerSecurity 

	contains all the bearer security policies. To reiterate, RemCon does no 

	security check on the client's send request either before calling 

	AddressOutgoingCommand.

	@param aInterfaceUid The UID of the client interface.

	@param aOperationId The operation ID of the command.

	@param aSender The TClientInfo of the sending session.

	@param aConnections An empty collection of connections. NB On completion, 

	an actual (bearer-level) connection does not need to exist for each item 

	in the collection- RemCon passes responsibility to the bearer(s) for 

	creating the specified connections. On successful completion, RemCon takes 

	ownership of any items in the collection- new TRemConAddresses must be 

	made on the heap.

	@param aBearerSecurity Contains all the bearer security policies.

	*/

	virtual void AddressOutgoingCommand(

		TUid aInterfaceUid,

		TUint aOperationId, 

		const TClientInfo& aSender,

		TSglQue<TRemConAddress>& aConnections,

		TSglQue<TBearerSecurity>& aBearerSecurity) = 0;

	/**

	Called by RemCon to find out from the TSP whether the given 

	connection-oriented controller client is permitted to send the given 

	command to the given remote at this time. The implementor should call 

	PermitOutgoingCommand with either ETrue, if the send is permitted, or 

	EFalse, if the send is not permitted.

	Note that only one of AddressOutgoingCommand and PermitOutgoingCommand is 

	outstanding at once.

	Note that a capability check will have been done by RemCon before 

	PermitOutgoingCommand is called- actually at GoConnectionOriented time. 

	@param aInterfaceUid The UID of the client interface.

	@param aOperationId The operation ID of the command.

	@param aSender The TClientInfo of the sending session.

	@param aConnection The remote the command will be sent over if permission 

	is granted.

	*/

	virtual void PermitOutgoingCommand(

		TUid aInterfaceUid,

		TUint aOperationId, 

		const TClientInfo& aSender,

		const TRemConAddress& aConnection) = 0;

	/** 

	Called by RemCon to cancel the current AddressOutgoingCommand or 

	PermitOutgoingCommand command.

	On receipt, the TSP must stop dereferencing any data given in the 

	AddressOutgoingCommand or PermitOutgoingCommand request. The TSP should 

	not subsequently call OutgoingCommandAddressed or 

	OutgoingCommandPermitted, except in response to a subsequent new 

	AddressOutgoingCommand or PermitOutgoingCommand command.

	If an AddressOutgoingCommand request is currently being processed, the TSP 

	is responsible for deleting any TRemConAddresses it has already created.

	*/

	virtual void CancelOutgoingCommand() = 0;

	/**

	Called by RemCon to get the TSP to address an incoming command (from a 

	remote to zero or more target clients). The implementor should add or 

	remove zero or more items from aClients and then call 

	IncomingCommandAddressed on the observer with a suitable error. 

	@param aInterfaceUid The UID of the client interface.

	@param aOperationId The operation ID of the command.

	@param aClients A collection of existing target clients. The implementor 

	may wish to start further target client(s) and add their process ID(s) to 

	this collection. New TClientInfo items must be made on the stack. Note 

	that when adding a TClientInfo to aClients, only the process ID needs to 

	be correctly populated.

	There is no 'cancel' method for AddressIncomingCommand. RemCon will only 

	want to 'cancel' this when the server is terminating, at which point it 

	will destroy the TSP anyway.

	*/

	virtual void AddressIncomingCommand(

		TUid aInterfaceUid,

		TUint aOperationId, 

		TSglQue<TClientInfo>& aClients) = 0;

	};

/**

The UID of this version of the Target Selector Plugin interface.

*/

const TInt KRemConTargetSelectorInterface2 = 0x102858CF;

/**

Additional functions for TSP Interface V2

*/

class MRemConTargetSelectorPluginInterfaceV2: public MRemConTargetSelectorPluginInterface

	{

public:

	/**

	Called by RemCon to get the TSP to decide which client should be

	allowed to respond to a command.

	This function is called as soon as each client returns a response, so

	the order in which clients are offered to the TSP is not predetermined.

	Since AV/C expects only a single response, the first response allowed by 

	the TSP is the one which will be sent on-air.

	The initial list of clients will be populated from the TSP's response 

	to AddressIncomingCommand().

	@param aInterfaceUid The UID of the client interface.

	@param aOperationId The operation ID of the command.

	@param aClient The client which is trying to send a response

	@param aClients A list of clients which are still expected to respond,

	including the one specified in aClient

	*/

	virtual void PermitOutgoingResponse(

			TUid aInterfaceUid,

			TUint aOperationId,

			const TClientInfo& aClient,

			TClientInfoConstIter& aClients) = 0;

	/**

	Called by RemCon to get the TSP to address an incoming notify (from a 

	remote to zero or more target clients). The implementor should call 

	IncomingNotifyAddressed on the observer with a pointer to the chosen

	client (or NULL if no client is to be addressed) from the list, and a

	suitable error.

	@param aInterfaceUid The UID of the client interface.

	@param aOperationId The operation ID of the command.

	@param aClients A collection of existing target clients. The implementor 

	may wish to start a target client and call IncomingNotifyAddressed

	with a new TClientInfo. The new TClientInfo item must be made on the stack. 

	Note when creating the new TClientInfo, only the process ID needs to 

	be correctly populated.

	*/

	virtual void AddressIncomingNotify(

		TUid aInterfaceUid,

		TUint aOperationId, 

		TSglQue<TClientInfo>& aClients) = 0;

	/** 

	Called by RemCon to cancel the current PermitOutgoingResponse request.

	On receipt, the TSP must stop dereferencing any data given in the 

	PermitOutgoingResponse request. The TSP should not subsequently call

	OutgoingResponsePermitted, except in response to a subsequent new 

	PermitOutgoingResponse request.

	*/

	virtual void CancelOutgoingResponse() = 0;

	};

/**

The UID of this version of the Target Selector Plugin interface.

*/

const TInt KRemConTargetSelectorInterface3 = 0x102858D3;

/**

Additional functions for TSP Interface V3

This interface must be implemented if the TSP wishes to support outgoing

Notify commands (local role controller).

*/

class MRemConTargetSelectorPluginInterfaceV3

	{

public:

	/**

	Called by RemCon to get the TSP to address an outgoing notify command (from a 

	connectionless controller client) to zero or one remote. The implementor 

	need to get the connection list from which to chose the only one target device and then call 

	OutgoingNotifyCommandAddressed on the observer with an appropriate error.

	Note that only one of AddressOutgoingNotifyCommand and PermitOutgoingNotifyCommand is 

	outstanding at once.

	The implementor is responsible for the capability check. For this reason, 

	aSender contains the client's current send message, and aBearerSecurity 

	contains all the bearer security policies. To reiterate, RemCon does no 

	security check on the client's send request either before calling 

	AddressOutgoingNotify.

	@param aInterfaceUid The UID of the client interface.

	@param aOperationId The operation ID of the command.

	@param aSender The TClientInfo of the sending session.

	@param aBearerSecurity Contains all the bearer security policies.

	*/

	virtual void AddressOutgoingNotify(

			TUid aInterfaceUid,

			TUint aOperationId, 

			const TClientInfo& aSender,

			TSglQue<TBearerSecurity>& aBearerSecurity) = 0;

	/** 

	Called by RemCon to cancel the current AddressOutgoingNotify or 

	PermitOutgoingNotifyCommand command.

	On receipt, the TSP must stop dereferencing any data given in the 

	AddressOutgoingNotify or PermitOutgoingNotifyCommand request. The TSP should 

	not subsequently call OutgoingNotifyCommandAddressed or 

	OutgoingNotifyCommandPermitted, except in response to a subsequent new 

	AddressOutgoingNotify or PermitOutgoingNotifyCommand command.

	If an AddressOutgoingNotify request is currently being processed, the TSP 

	is responsible for deleting any TRemConAddresses it has already created.

	*/

	virtual void CancelOutgoingNotifyCommand() = 0;

	/**

	Called by RemCon to find out from the TSP whether the given 

	connection-oriented controller client is permitted to send the given notify

	command to the given remote at this time. The implementor should call 

	PermitOutgoingNotifyCommand with either ETrue, if the send is permitted, or 

	EFalse, if the send is not permitted.

	Note that only one of AddressOutgoingNotify and PermitOutgoingNotifyCommand is 

	outstanding at once.

	Note that a capability check will have been done by RemCon before 

	PermitOutgoingNotifyCommand is called- actually at GoConnectionOriented time. 

	@param aInterfaceUid The UID of the client interface.

	@param aOperationId The operation ID of the command.

	@param aSender The TClientInfo of the sending session.

	@param aConnection The remote the command will be sent over if permission 

	is granted.

	*/

	virtual void PermitOutgoingNotifyCommand(

			TUid aInterfaceUid,

			TUint aOperationId, 

			const TClientInfo& aSender,

			const TRemConAddress& aConnection) = 0;

	};

/**

The UID of this version of the Target Selector Plugin interface.

*/

const TInt KRemConTargetSelectorInterface4 = 0x10286A7;

/**

Additional functions for TSP Interface V4

This interface must be implemented if the TSP wishes to support addressing

by the bearer.  Bearer addressing will always be used if supported by the

bearer.  When bearer addressing is used the TSP will not be given any

option over which client receives a command, however if it implements this

interface it has visibility of where each command goes and can reject the 

command if it is not acceptable.

If this interface is not implemented default implementations of these functions 

will be used which will allow the command to be addressed to the bearer's 

selected client.  This means that if the TSP does not implement this interface

it will not see any commands which have been addressed by the bearer.

Regardless of whether this interface is implemented commands which are not 

addressed by the bearer will continue to be addressed by the TSP via earlier 

versions of MRemConTargetSelectorPluginInterface.

*/

class MRemConTargetSelectorPluginInterfaceV4

	{

public:

	/**

	Called by RemCon to get the TSP to permit an incoming command. This is called

	if the bearer has provided a target client for the command.  

	The implementor should decide if they wish to allow this command and then call

	IncomingCommandPermitted on the observer with a suitable error. 

	@param aInterfaceUid The UID of the client interface.

	@param aOperationId The operation ID of the command.

	@param aClient a TClientInfo referring to the selected client

	*/

	virtual void PermitIncomingCommand(

		TUid aInterfaceUid,

		TUint aOperationId, 

		const TClientInfo& aClient) = 0;

	/**

	Called by RemCon to get the TSP to permit an incoming Notify. This is called

	if the bearer has provided a target client for the Notify.  

	The implementor should decide if they wish to allow this Notify and then call

	IncomingNotifyPermitted on the observer with a suitable error. 

	@param aInterfaceUid The UID of the client interface.

	@param aOperationId The operation ID of the Notify.

	@param aClient a TClientInfo referring to the selected client

	*/

	virtual void PermitIncomingNotify(

		TUid aInterfaceUid,

		TUint aOperationId, 

		const TClientInfo& aClient) = 0;

	/** 

	Called by RemCon when a bearer that can address commands wishes to

	inform the system that there has been a remote user action to 

	select a different addressed client.

	The bearer will then route addressed commands to this client until

	such time as SetRemoteAddressedClient is called again or the TSP

	calls SetLocalAddressedClient.

	@param aBearerUid The bearer that has changed its addressed client

	@param aClient The RemCon client that is now selected by the bearer

	*/

	virtual void SetRemoteAddressedClient(const TUid& aBearerUid, 

			const TClientInfo& aClient) = 0;

	};

/**

The UID of this version of the Target Selector Plugin interface.

*/

const TInt KRemConTargetSelectorInterface5 = 0x2002e6e1;

class MRemConTargetSelectorPluginInterfaceV5

	{

public:

	/** Called by RemCon when a new target client has connected.

	 @aClientInfo The information about the new client.

	 */

	virtual void TargetClientAvailable(const TClientInfo& aClientInfo) = 0;

	/** Called by RemCon when a target client has disconnected. 

	 @aClientInfo The information about the client that has disconnected.

	 */

	virtual void TargetClientUnavailable(const TClientInfo& aClientInfo) = 0;

	/** Called by RemCon when a bearer wishes to begin being informed when

	the locally addressed player changes.  Once this function has been called

	the TSP should inform RemCon via SetLocalAddressedPlayer each time the

	player to which incoming commands from aBearer would be routed changes.

	This might occur for example if a new application is launched, or if the

	foreground application changes, depending on what the TSP's rules are

	for deciding the target of the incoming message.  These updates should

	occur until UnregisterLocalAddressedClientObserver is called.

	@param aBearerUid The bearer that wishes to be informed of updates

	*/

	virtual TInt RegisterLocalAddressedClientObserver(const TUid& aBearerUid) = 0;

	/** Called by RemCon when a bearer wishes to stop being informed of 

	changes to the local addresse client.

	@param aBearerUid The bearer that no longer wishes to be informed of updates

	*/

	virtual TInt UnregisterLocalAddressedClientObserver(const TUid& aBearerUid) = 0;

	};

#endif // TARGETSELECTORPLUGININTERFACE_H