1 // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @publishedPartner

    19  @released

    20 */

    21 

    22 #ifndef TARGETSELECTORPLUGININTERFACE_H

    23 #define TARGETSELECTORPLUGININTERFACE_H

    24 

    25 #include <e32base.h>

    26 

    27 class MRemConTargetSelectorPluginObserver;

    28 class TRemConAddress;

    29 class TClientInfo;

    30 class TBearerSecurity;

    31 class TClientInfoConstIter;

    32 

    33 /**

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

    35 */

    36 const TInt KRemConTargetSelectorInterface1 = 0x10208BCD;

    37 

    38 

    39 /**

    40 Abstract base class for target selector plugins.

    41 */

    42 class MRemConTargetSelectorPluginInterface

    43 	{

    44 public:

    45 	/**

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

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

    48 	should add zero or more items to aConnections and then call 

    49 	OutgoingCommandAddressed on the observer with an appropriate error.

    50 	Note that only one of AddressOutgoingCommand and PermitOutgoingCommand is 

    51 	outstanding at once.

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

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

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

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

    56 	AddressOutgoingCommand.

    57 	@param aInterfaceUid The UID of the client interface.

    58 	@param aOperationId The operation ID of the command.

    59 	@param aSender The TClientInfo of the sending session.

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

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

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

    63 	creating the specified connections. On successful completion, RemCon takes 

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

    65 	made on the heap.

    66 	@param aBearerSecurity Contains all the bearer security policies.

    67 	*/

    68 	virtual void AddressOutgoingCommand(

    69 		TUid aInterfaceUid,

    70 		TUint aOperationId, 

    71 		const TClientInfo& aSender,

    72 		TSglQue<TRemConAddress>& aConnections,

    73 		TSglQue<TBearerSecurity>& aBearerSecurity) = 0;

    74 

    75 	/**

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

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

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

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

    80 	EFalse, if the send is not permitted.

    81 	Note that only one of AddressOutgoingCommand and PermitOutgoingCommand is 

    82 	outstanding at once.

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

    84 	PermitOutgoingCommand is called- actually at GoConnectionOriented time. 

    85 	@param aInterfaceUid The UID of the client interface.

    86 	@param aOperationId The operation ID of the command.

    87 	@param aSender The TClientInfo of the sending session.

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

    89 	is granted.

    90 	*/

    91 	virtual void PermitOutgoingCommand(

    92 		TUid aInterfaceUid,

    93 		TUint aOperationId, 

    94 		const TClientInfo& aSender,

    95 		const TRemConAddress& aConnection) = 0;

    96 

    97 	/** 

    98 	Called by RemCon to cancel the current AddressOutgoingCommand or 

    99 	PermitOutgoingCommand command.

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

   101 	AddressOutgoingCommand or PermitOutgoingCommand request. The TSP should 

   102 	not subsequently call OutgoingCommandAddressed or 

   103 	OutgoingCommandPermitted, except in response to a subsequent new 

   104 	AddressOutgoingCommand or PermitOutgoingCommand command.

   105 	If an AddressOutgoingCommand request is currently being processed, the TSP 

   106 	is responsible for deleting any TRemConAddresses it has already created.

   107 	*/

   108 	virtual void CancelOutgoingCommand() = 0;

   109 

   110 	/**

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

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

   113 	remove zero or more items from aClients and then call 

   114 	IncomingCommandAddressed on the observer with a suitable error. 

   115 	@param aInterfaceUid The UID of the client interface.

   116 	@param aOperationId The operation ID of the command.

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

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

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

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

   121 	be correctly populated.

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

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

   124 	will destroy the TSP anyway.

   125 	*/

   126 	virtual void AddressIncomingCommand(

   127 		TUid aInterfaceUid,

   128 		TUint aOperationId, 

   129 		TSglQue<TClientInfo>& aClients) = 0;

   130 			

   131 	};

   132 	

   133 /**

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

   135 */

   136 const TInt KRemConTargetSelectorInterface2 = 0x102858CF;

   137 

   138 /**

   139 Additional functions for TSP Interface V2

   140 */

   141 class MRemConTargetSelectorPluginInterfaceV2: public MRemConTargetSelectorPluginInterface

   142 	{

   143 public:

   144 	/**

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

   146 	allowed to respond to a command.

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

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

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

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

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

   152 	to AddressIncomingCommand().

   153 	@param aInterfaceUid The UID of the client interface.

   154 	@param aOperationId The operation ID of the command.

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

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

   157 	including the one specified in aClient

   158 	*/

   159 	 

   160 	virtual void PermitOutgoingResponse(

   161 			TUid aInterfaceUid,

   162 			TUint aOperationId,

   163 			const TClientInfo& aClient,

   164 			TClientInfoConstIter& aClients) = 0;

   165 	

   166 	/**

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

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

   169 	IncomingNotifyAddressed on the observer with a pointer to the chosen

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

   171 	suitable error.

   172 	@param aInterfaceUid The UID of the client interface.

   173 	@param aOperationId The operation ID of the command.

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

   175 	may wish to start a target client and call IncomingNotifyAddressed

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

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

   178 	be correctly populated.

   179 	*/

   180 	virtual void AddressIncomingNotify(

   181 		TUid aInterfaceUid,

   182 		TUint aOperationId, 

   183 		TSglQue<TClientInfo>& aClients) = 0;

   184 	

   185 	/** 

   186 	Called by RemCon to cancel the current PermitOutgoingResponse request.

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

   188 	PermitOutgoingResponse request. The TSP should not subsequently call

   189 	OutgoingResponsePermitted, except in response to a subsequent new 

   190 	PermitOutgoingResponse request.

   191 	*/

   192 	virtual void CancelOutgoingResponse() = 0;

   193 	};

   194 

   195 /**

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

   197 */

   198 const TInt KRemConTargetSelectorInterface3 = 0x102858D3;

   199 

   200 /**

   201 Additional functions for TSP Interface V3

   202 

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

   204 Notify commands (local role controller).

   205 */

   206 class MRemConTargetSelectorPluginInterfaceV3

   207 	{

   208 public:

   209 	/**

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

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

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

   213 	OutgoingNotifyCommandAddressed on the observer with an appropriate error.

   214 	Note that only one of AddressOutgoingNotifyCommand and PermitOutgoingNotifyCommand is 

   215 	outstanding at once.

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

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

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

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

   220 	AddressOutgoingNotify.

   221 	@param aInterfaceUid The UID of the client interface.

   222 	@param aOperationId The operation ID of the command.

   223 	@param aSender The TClientInfo of the sending session.

   224 	@param aBearerSecurity Contains all the bearer security policies.

   225 	*/

   226 	virtual void AddressOutgoingNotify(

   227 			TUid aInterfaceUid,

   228 			TUint aOperationId, 

   229 			const TClientInfo& aSender,

   230 			TSglQue<TBearerSecurity>& aBearerSecurity) = 0;

   231 	

   232 	/** 

   233 	Called by RemCon to cancel the current AddressOutgoingNotify or 

   234 	PermitOutgoingNotifyCommand command.

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

   236 	AddressOutgoingNotify or PermitOutgoingNotifyCommand request. The TSP should 

   237 	not subsequently call OutgoingNotifyCommandAddressed or 

   238 	OutgoingNotifyCommandPermitted, except in response to a subsequent new 

   239 	AddressOutgoingNotify or PermitOutgoingNotifyCommand command.

   240 	If an AddressOutgoingNotify request is currently being processed, the TSP 

   241 	is responsible for deleting any TRemConAddresses it has already created.

   242 	*/

   243 	virtual void CancelOutgoingNotifyCommand() = 0;

   244 	

   245 	/**

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

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

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

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

   250 	EFalse, if the send is not permitted.

   251 	Note that only one of AddressOutgoingNotify and PermitOutgoingNotifyCommand is 

   252 	outstanding at once.

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

   254 	PermitOutgoingNotifyCommand is called- actually at GoConnectionOriented time. 

   255 	@param aInterfaceUid The UID of the client interface.

   256 	@param aOperationId The operation ID of the command.

   257 	@param aSender The TClientInfo of the sending session.

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

   259 	is granted.

   260 	*/

   261 	virtual void PermitOutgoingNotifyCommand(

   262 			TUid aInterfaceUid,

   263 			TUint aOperationId, 

   264 			const TClientInfo& aSender,

   265 			const TRemConAddress& aConnection) = 0;

   266 	};

   267 

   268 /**

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

   270 */

   271 const TInt KRemConTargetSelectorInterface4 = 0x10286A7;

   272 

   273 /**

   274 Additional functions for TSP Interface V4

   275 

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

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

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

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

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

   281 command if it is not acceptable.

   282 

   283 If this interface is not implemented default implementations of these functions 

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

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

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

   287 

   288 Regardless of whether this interface is implemented commands which are not 

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

   290 versions of MRemConTargetSelectorPluginInterface.

   291 */

   292 class MRemConTargetSelectorPluginInterfaceV4

   293 	{

   294 public:

   295 	/**

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

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

   298 	

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

   300 	IncomingCommandPermitted on the observer with a suitable error. 

   301 	

   302 	@param aInterfaceUid The UID of the client interface.

   303 	@param aOperationId The operation ID of the command.

   304 	@param aClient a TClientInfo referring to the selected client

   305 	*/

   306 	virtual void PermitIncomingCommand(

   307 		TUid aInterfaceUid,

   308 		TUint aOperationId, 

   309 		const TClientInfo& aClient) = 0;

   310 	

   311 	/**

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

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

   314 	

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

   316 	IncomingNotifyPermitted on the observer with a suitable error. 

   317 	

   318 	@param aInterfaceUid The UID of the client interface.

   319 	@param aOperationId The operation ID of the Notify.

   320 	@param aClient a TClientInfo referring to the selected client

   321 	*/

   322 	virtual void PermitIncomingNotify(

   323 		TUid aInterfaceUid,

   324 		TUint aOperationId, 

   325 		const TClientInfo& aClient) = 0;

   326 	

   327 	/** 

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

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

   330 	select a different addressed client.

   331 	

   332 	The bearer will then route addressed commands to this client until

   333 	such time as SetRemoteAddressedClient is called again or the TSP

   334 	calls SetLocalAddressedClient.

   335 	

   336 	@param aBearerUid The bearer that has changed its addressed client

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

   338 	*/

   339 	virtual void SetRemoteAddressedClient(const TUid& aBearerUid, 

   340 			const TClientInfo& aClient) = 0;

   341 	};

   342 

   343 

   344 #endif // TARGETSELECTORPLUGININTERFACE_H