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 REMCONBEARERINTERFACE_H

    23 #define REMCONBEARERINTERFACE_H

    24 

    25 #include <e32base.h>

    26 #include <remcon/clientid.h>

    27 #include <remcon/messagetype.h>

    28 #include <remcon/playertype.h>

    29 

    30 class MRemConBearerObserver;

    31 class TBearerParams;

    32 class TRemConAddress;

    33 

    34 /** 

    35 The UID of the bearer API. If the bearer API ever has to change, a new UID and 

    36 associated M class will be created. New implementations of CRemConBearerPlugin 

    37 may implement the new API. Old (non-updated) bearers will still work as long 

    38 as RemCon supports the old API.

    39 */

    40 const TInt KRemConBearerInterface1 = 0x10208A78;

    41 

    42 /**

    43 Mixin for the bearer API.

    44 */

    45 class MRemConBearerInterface

    46 	{

    47 public:

    48 	/** 

    49 	Called by RemCon to retrieve a response on a connection. Must only be 

    50 	called as a result of a NewResponse up-call.

    51 	@param aInterfaceUid The UID of the outer-layer client API specifying the 

    52 	response.

    53 	@param aTransactionId The command identifier used as a cookie for command/response 

    54 	matching.

    55 	@param aOperationId The ID of the response operation in the outer-layer 

    56 	client API.

    57 	@param aData API-specific message data. On success, ownership is 

    58 	returned.

    59 	@param aAddr The connection.

    60 	@return Error.

    61 	*/

    62 	virtual TInt GetResponse(TUid& aInterfaceUid, 

    63 		TUint& aTransactionId, 

    64 		TUint& aOperationId, 

    65 		RBuf8& aData, 

    66 		TRemConAddress& aAddr) = 0;

    67 	

    68 	/** 

    69 	Called by RemCon to retrieve a command on a connection. Must only be 

    70 	called as a result of a NewCommand up-call.

    71 	@param aInterfaceUid The UID of the outer-layer client API specifying the 

    72 	command.

    73 	@param aTransactionId The command identifier used as a cookie for command/response 

    74 	matching.

    75 	@param aOperationId The ID of the command operation in the outer-layer 

    76 	client API.

    77 	@param aData API-specific message data. On success, ownership is 

    78 	returned.

    79 	@param aAddr The connection.

    80 	@return Error.

    81 	*/

    82 	virtual TInt GetCommand(TUid& aInterfaceUid, 

    83 		TUint& aTransactionId, 

    84 		TUint& aOperationId, 

    85 		RBuf8& aData, 

    86 		TRemConAddress& aAddr) = 0;

    87 

    88 	/** 

    89 	Called by RemCon to send a command on a connection. The connection is not 

    90 	assumed to exist- the bearer is responsible for bringing up the requested 

    91 	connection if necessary.

    92 	@param aInterfaceUid The UID of the outer-layer client API specifying the 

    93 	command.

    94 	@param aOperationId The ID of the command operation in the outer-layer 

    95 	client API.

    96 	@param aTransactionId The command identifier used as a cookie for command/response 

    97 	matching.

    98 	@param aData API-specific message data. On success, ownership is passed. 

    99 	@param aAddr The connection.

   100 	@return Error. This request is synchronous. It should be completed by the 

   101 	bearer when it has taken responsibility for sending the message. This will 

   102 	involve checking that the message is well-formed, and possibly actually 

   103 	trying to send it, or adding it to a queue.

   104 	*/

   105 	virtual TInt SendCommand(TUid aInterfaceUid, 

   106 		TUint aOperationId, 

   107 		TUint aTransactionId,  

   108 		RBuf8& aData, 

   109 		const TRemConAddress& aAddr) = 0;

   110 	

   111 	/** 

   112 	Called by RemCon to send a response on a connection. The connection is not 

   113 	assumed to exist- the bearer is responsible for bringing up the requested 

   114 	connection if necessary.

   115 	@param aInterfaceUid The UID of the outer-layer client API specifying the 

   116 	response.

   117 	@param aOperationId The ID of the response operation in the outer-layer 

   118 	client API.

   119 	@param aTransactionId The command identifier used as a cookie for command/response 

   120 	matching

   121 	@param aData API-specific message data. On success, ownership is passed.

   122 	@param aAddr The connection.

   123 	@return Error. This request is synchronous. It should be completed by the 

   124 	bearer when it has taken responsibility for sending the message. This will 

   125 	involve checking that the message is well-formed, and possibly actually 

   126 	trying to send it, or adding it to a queue.

   127 	*/

   128 	virtual TInt SendResponse(TUid aInterfaceUid, 

   129 		TUint aOperationId, 

   130 		TUint aTransactionId, 

   131 		RBuf8& aData, 

   132 		const TRemConAddress& aAddr) = 0;

   133 	

   134 	/** 

   135 	Called by RemCon to establish a bearer-level connection to another party. 

   136 	Completion is signalled back in ConnectConfirm.

   137 	@param aAddr The RemCon address to connect to.

   138 	*/

   139 	virtual void ConnectRequest(const TRemConAddress& aAddr) = 0;

   140 	

   141 	/** 

   142 	Called by RemCon to destroy a bearer-level connection to another party. 

   143 	Completion is signalled back in DisconnectConfirm.

   144 	@param aAddr The RemCon address to disconnect from.

   145 	*/

   146 	virtual void DisconnectRequest(const TRemConAddress& aAddr) = 0;

   147 

   148 	/**

   149 	Called by RemCon when either (a) the number of controller clients changes 

   150 	from 0 to 1 or from 1 to 0, or (b) the number of target clients changes 

   151 	from 0 to 1 or from 1 to 0.

   152 	@param aControllerPresent Is true if any controllers are present, EFalse otherwise.

   153 	@param aTargetPresent Is true if any targets are present, EFalse otherwise.

   154 	*/

   155 	virtual void ClientStatus(TBool aControllerPresent, TBool aTargetPresent) = 0;

   156 

   157 	/**

   158 	Called by RemCon to get the capabilities required to make/destroy 

   159 	connections over the bearer, and to send and receive messages over the 

   160 	bearer.

   161 	@return The bearer's security policy.

   162 	*/

   163 	virtual TSecurityPolicy SecurityPolicy() const = 0;

   164 	};

   165 	

   166 	

   167 /** 

   168 The UID of the bearer API. If the bearer API ever has to change, a new UID and 

   169 associated M class will be created. New implementations of CRemConBearerPlugin 

   170 may implement the new API. Old (non-updated) bearers will still work as long 

   171 as RemCon supports the old API.

   172 */

   173 const TInt KRemConBearerInterface2 = 0x10285AD9;

   174 

   175 	

   176 class MRemConBearerInterfaceV2 : public MRemConBearerInterface

   177 	{

   178 public:

   179 	/** 

   180 	Called by RemCon to retrieve a notify command on a connection. Must only be 

   181 	called as a result of a NewNotify up-call.

   182 	@param aInterfaceUid The UID of the outer-layer client API specifying the 

   183 	notify command.

   184 	@param aTransactionId The command identifier used as a cookie for command/response 

   185 	matching.

   186 	@param aOperationId The ID of the command operation in the outer-layer 

   187 	client API.

   188 	@param aData API-specific message data. On success, ownership is 

   189 	returned.

   190 	@param aAddr The connection.

   191 	*/

   192 	virtual TInt GetNotifyCommand(TUid& aInterfaceUid, 

   193 		TUint& aTransactionId, 

   194 		TUint& aOperationId, 

   195 		RBuf8& aData, 

   196 		TRemConAddress& aAddr) = 0;

   197 	

   198 	/**

   199 	Called by RemCon when either

   200 	a) The TSP does not address a command to any clients

   201 	b) The TSP does not permit the response from any commands

   202 	c) All the clients disconnect from remcon before the response is sent,

   203 	to send a reject on a connection. RemCon will call this function after bringing

   204 	up the connection.

   205 	@param aInterfaceUid The UID of the outer-layer client API that the command

   206 	was sent to

   207 	@param aOperationId The ID of the command operation sent to remcon

   208 	@param aTransactionId The command identifier used as a cookie for command/response 

   209 	matching.

   210 	@param aAddr The connection.

   211 	*/

   212 	virtual void SendReject(TUid aInterfaceUid, 

   213 			TUint aOperationId, 

   214 			TUint aTransactionId, 

   215 			const TRemConAddress& aAddr) = 0; 

   216 	};	

   217 

   218 /** 

   219 The UID of the bearer API. If the bearer API ever has to change, a new UID and 

   220 associated M class will be created. New implementations of CRemConBearerPlugin 

   221 may implement the new API. Old (non-updated) bearers will still work as long 

   222 as RemCon supports the old API.

   223 */

   224 const TInt KRemConBearerInterface3 = 0x10285ADB;

   225 

   226 class MRemConBearerInterfaceV3 : public MRemConBearerInterfaceV2

   227 	{

   228 public:

   229 	/** 

   230 	Called by RemCon to send a notify command on a connection. The connection is not 

   231 	assumed to exist- the bearer is responsible for bringing up the requested 

   232 	connection if necessary.

   233 	@param aInterfaceUid The UID of the outer-layer client API specifying the command.

   234 	@param aOperationId The ID of the command operation in the outer-layer client API.

   235 	@param aTransactionId The command identifier used as a cookie for command/response matching.

   236 	@param aData API-specific message data. On success, ownership is passed. 

   237 	@param aAddr The connection.

   238 	@return Error. This request is synchronous. It returns KErrNone when the 

   239 	bear has taken responsibility for sending the message. This will 

   240 	involve checking that the message is well-formed, and possibly actually 

   241 	trying to send it, or adding it to a queue.

   242 	*/

   243 	virtual TInt SendNotifyCommand(TUid aInterfaceUid, 

   244 			TUint aOperationId, 

   245 			TUint aTransactionId,  

   246 			RBuf8& aData, 

   247 			const TRemConAddress& aAddr) = 0;

   248 	

   249 	/** 

   250 	Called by RemCon to retrieve a notify response on a connection. Must only be 

   251 	called as a result of a NewNotifyResponseL up-call.

   252 	@param aInterfaceUid The UID of the outer-layer client API specifying the response.

   253 	@param aTransactionId The command identifier used as a cookie for command/response matching.

   254 	@param aOperationId The ID of the response operation in the outer-layer client API.

   255 	@param aData API-specific message data. On success, ownership is returned.

   256 	@param aAddr The connection.

   257 	@return Error.

   258 	*/

   259 	virtual TInt GetNotifyResponse(TUid& aInterfaceUid, 

   260 			TUint& aId, 

   261 			TUint& aOperationId, 

   262 			RBuf8& aCommandData, 

   263 			TRemConAddress& aAddr,

   264 			TRemConMessageSubType& aSubMessageType)=0;

   265 	

   266 	/**

   267 	Called by RemCon when a client has become available for addressing.  Once this

   268 	call has been made the bearer may use the provided TRemConClientId to address

   269 	incoming commands and notifys to this client until RemCon calls ClientNotAvailable

   270 	with this TRemConClientId.

   271 	

   272 	@param aId A unique identifier for this client, that can be used when addressing 

   273 	incoming commands.

   274 	@param aClientType The basic type of this client

   275 	@param aClientSubType More detailed type information on this client

   276 	@param aName The name of this client in UTF-8.  This remains valid until ClientNotAvailable 

   277 				 is called for this player.

   278 	*/

   279 	virtual void ClientAvailable(TRemConClientId& aId, TPlayerType aClientType, TPlayerSubType aClientSubType, const TDesC8& aName) = 0;

   280 	

   281 	/**

   282 	Called by RemCon when a client is no longer available for addressing.  Once this

   283 	call has been made the bearer shall not use this client id when addressing incoming

   284 	commands and notifys until informed that the client is available again via

   285 	ClientAvailable.

   286 	

   287 	@param aId The client that has ceased to be available.

   288 	*/

   289 	virtual void ClientNotAvailable(TRemConClientId& aId) = 0;

   290 	

   291 	/** 

   292 	Called by RemCon when the TSP has requested this bearer use a different addressed

   293 	client.

   294 	

   295 	@param aId The client to which this bearer should route addressed commands.

   296 	*/

   297 	virtual TInt SetLocalAddressedClient(TRemConClientId& aId) = 0;

   298 	

   299 	/**

   300 	Called by RemCon when a controller client is opened or closed to provide the 

   301 	current set of interfaces supported by controller sessions.  This is not

   302 	guaranteed to have changed since the last time the function was called.

   303 	

   304 	@param aSupportedInterfaces An RArray of interface UIDs.  Ownership is retained

   305 				by RemCon and its lifetime is not guaranteed to last beyond the scope

   306 				of this function.  Each supported interface appears once in the array

   307 				irrespective of how many controller sessions support that interface.

   308 	*/

   309 	virtual void ControllerFeaturesUpdated(RArray<TUid>& aSupportedInterfaces) = 0;

   310 	};

   311 

   312 #endif // REMCONBEARERINTERFACE_H