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 REMCONBEAREROBSERVER_H

    23 #define REMCONBEAREROBSERVER_H

    24 

    25 #include <e32base.h>

    26 #include <remcon/messagetype.h>

    27 #include <remcon/clientid.h>

    28 

    29 class CRemConConverterPlugin;

    30 class TRemConAddress;

    31 

    32 /**

    33 Interface presented by RemCon down to bearers.

    34 The public methods are non-virtual and exported, so that they can be added to 

    35 without breaking BC for existing (non-rebuilt) bearers.

    36 */

    37 class MRemConBearerObserver

    38 	{

    39 public:

    40 	/** 

    41 	Called when an incoming response from a remote is ready to be picked up by 

    42 	RemCon.

    43 	@param aAddr The address the response came from.

    44 	@return Error. If KErrNone, RemCon is committing to collecting the message 

    45 	using GetResponse. If non-KErrNone, the message will be dropped by the 

    46 	bearer.

    47 	*/

    48 	IMPORT_C TInt NewResponse(const TRemConAddress& aAddr);	

    49 	

    50 	/** 

    51 	Called when an incoming notify response from a remote is ready to be picked up by 

    52 	RemCon.

    53 	@param aAddr The address the response came from.

    54 	@return Error. If KErrNone, RemCon is committing to collecting the message 

    55 	using GetNotifyResponse. If non-KErrNone, the message will be dropped by the 

    56 	bearer.

    57 	*/

    58 	IMPORT_C TInt NewNotifyResponse(const TRemConAddress& aAddr);	

    59 	

    60 	/** 

    61 	Called when an incoming command from a remote is ready to be picked up by 

    62 	RemCon.

    63 	@param aAddr The address the command came from.

    64 	@return Error. If KErrNone, RemCon is committing to collecting the message 

    65 	using GetResponse. If non-KErrNone, the message will be dropped by the 

    66 	bearer.

    67 	*/

    68 	IMPORT_C TInt NewCommand(const TRemConAddress& aAddr);

    69 

    70 	/** 

    71 	Called when an incoming notify command from a remote is ready to be picked up by 

    72 	RemCon.  A Notify command is different to a normal command in that it doesn't

    73 	follow the standard request / response sequence.  Instead a notify is registered

    74 	to retrieve the current state value in an interim response, then when the state

    75 	has changed relative the interim response a second response is sent containing the

    76 	new, changed, state.

    77 	

    78 	Depending on the semantics of the bearer protocol it may be able to map its 

    79 	state observation commands to plain RemCon commands, however for a reliable 

    80 	mechanism without polling this NotifyCommand is provided.  

    81 	

    82 	@param aAddr The address the command came from.

    83 	@return Error. If KErrNone, RemCon is committing to collecting the message 

    84 	using GetResponse. If non-KErrNone, the message will be dropped by the 

    85 	bearer.

    86 	*/

    87 	IMPORT_C TInt NewNotifyCommand(const TRemConAddress& aAddr);

    88 	

    89 	/** 

    90 	Called by a bearer when an incoming connection has been established. 

    91 	@param aAddr The address of the connection.

    92 	@return Error. If RemCon cannot add the connection to its internal data, 

    93 	then the bearer must logically drop the connection.

    94 	*/

    95 	IMPORT_C TInt ConnectIndicate(const TRemConAddress& aAddr);

    96 	

    97 	/**

    98 	Called by a bearer when a connection has been disconnected from the remote 

    99 	end. 

   100 	The bearer should only call this function if either (a) ConnectIndicate 

   101 	has already been called for the connection aAddr (and KErrNone returned by 

   102 	RemCon), or (b) ConnectConfirm has been called with KErrNone for the 

   103 	connection aAddr (and KErrNone has been returned by RemCon).

   104 	@param aAddr The RemCon address of the connection.

   105 	*/

   106 	IMPORT_C void DisconnectIndicate(const TRemConAddress& aAddr);

   107 	

   108 	/**

   109 	Called by a bearer to indicate completion of an outgoing connection 

   110 	request (CRemConBearerPlugin::ConnectRequest).

   111 	@param aAddr The address of the connection in question.

   112 	@param aError The success status of the connection establishment. If 

   113 	KErrNone, the connection was established. If non-KErrNone, the connection 

   114 	was not established.

   115 	@return Error. If RemCon cannot add the connection to its internal data, 

   116 	then the bearer must logically drop the connection. If aError is not 

   117 	KErrNone, then this return value is irrelevant.

   118 	*/

   119 	IMPORT_C TInt ConnectConfirm(const TRemConAddress& aAddr, TInt aError);

   120 	

   121 	/**

   122 	Called by a bearer to indicate completion of a disconnection request 

   123 	(CRemConBearerPlugin::Disconnect).

   124 	@param aAddr The address of the connection in question.

   125 	@param aError The success status of the disconnection. If KErrNone, the 

   126 	disconnection occurred. If non-KErrNone, the connection still exists.

   127 	*/

   128 	IMPORT_C void DisconnectConfirm(const TRemConAddress& aAddr, TInt aError);

   129 

   130 	/**

   131 	Called by a bearer to convert a message from an outer-layer API format to 

   132 	the bearer's format. The bearer observer finds a converter to perform 

   133 	this. 

   134 	@param aBearerUid The UID of the bearer.

   135 	@param aInterfaceUid The UID of the outer layer API to which the message 

   136 	belongs.

   137 	@param aOperationId The operation ID of the message.

   138 	@param aData The operation-specific data of the message.

   139 	@param aMsgType The type of the message.

   140 	@param aBearerData On success, the message encoded in the bearer's format.

   141 	@return Error. If a converter could not be found, KErrNotSupported, 

   142 	indicating that the message/bearer combination is not supported by the 

   143 	system.

   144 	*/

   145 	IMPORT_C TInt InterfaceToBearer(TUid aBearerUid,

   146 		TUid aInterfaceUid, 

   147 		TUint aOperationId,

   148 		const TDesC8& aData,

   149 		TRemConMessageType aMsgType, 

   150 		TDes8& aBearerData) const;

   151 	

   152 	/**

   153 	Called by a bearer to convert a message from the bearer's format to that 

   154 	of an outer-layer API. The bearer observer finds a converter to perform 

   155 	this. 

   156 	@param aBearerUid The UID of the bearer.

   157 	@param aInterfaceData Data identifying the interface in bearer-specific 

   158 	format.

   159 	@param aBearerData The message encoded in the bearer's format.

   160 	@param aInterfaceUid On success, the UID of the outer layer API to which 

   161 	the message belongs.

   162 	@param aOperationId On success, the operation ID of the message.

   163 	@param aData On success, the operation-specific data of the message.

   164 	@param aMsgType On success, the type of the message.

   165 	@return Error. If a converter could not be found, KErrNotSupported, 

   166 	indicating that the message/bearer combination is not supported by the 

   167 	system.

   168 	*/

   169 	IMPORT_C TInt BearerToInterface(TUid aBearerUid,

   170 		const TDesC8& aInterfaceData, 

   171 		const TDesC8& aBearerData,

   172 		TUid& aInterfaceUid, 

   173 		TUint& aOperationId,

   174 		TRemConMessageType& aMsgType, 

   175 		TDes8& aData) const;

   176 

   177 	/**

   178 	Called by a bearer when a new command has come in. RemCon returns a cookie 

   179 	(a transaction id), guaranteed to be unique, which the bearer may use for 

   180 	its own identification purposes.

   181 	@return A new transaction ID.

   182 	*/

   183 	IMPORT_C TUint NewTransactionId();

   184 	

   185 	/**

   186 	Called by a bearer when a command is no longer valid and should be removed

   187 	from RemCon's queues

   188 	@param aTransactionId The transaction ID of the expired command

   189 	*/

   190 	IMPORT_C void CommandExpired(TUint aTransactionId);

   191 	

   192 	/** 

   193 	Called when an incoming command from a remote is ready to be picked up by 

   194 	RemCon.

   195 	

   196 	This overload is provided for the case where the bearer supports command 

   197 	addressing.

   198 	

   199 	@param aAddr The address the command came from.

   200 	@param aTarget The application to which the command is targeted

   201 	@return Error. If KErrNone, RemCon is committing to collecting the message 

   202 	using GetResponse. If non-KErrNone, the message will be dropped by the 

   203 	bearer.

   204 	*/

   205 	IMPORT_C TInt NewCommand(const TRemConAddress& aAddr, const TRemConClientId& aClient);

   206 

   207 	/** 

   208 	Called when an incoming notify command from a remote is ready to be picked up by 

   209 	RemCon.  A Notify command is different to a normal command in that it doesn't

   210 	follow the standard request / response sequence.  Instead a notify is registered

   211 	to retrieve the current state value in an interim response, then when the state

   212 	has changed relative the interim response a second response is sent containing the

   213 	new, changed, state.

   214 	

   215 	Depending on the semantics of the bearer protocol it may be able to map its 

   216 	state observation commands to plain RemCon commands, however for a reliable 

   217 	mechanism without polling this NotifyCommand is provided.  

   218 	

   219 	This overload is provided for the case where the bearer supports command

   220 	addressing.

   221 	

   222 	@param aAddr The address the command came from.

   223 	@param aTarget The application to which the command is targeted

   224 	@return Error. If KErrNone, RemCon is committing to collecting the message 

   225 	using GetResponse. If non-KErrNone, the message will be dropped by the 

   226 	bearer.

   227 	*/

   228 	IMPORT_C TInt NewNotifyCommand(const TRemConAddress& aAddr, const TRemConClientId& aClient);

   229 

   230 	/**

   231 	Called by the bearer when it want to retrieve which interfaces are supported by a 

   232 	specific client.

   233 	@param aId A unique identifier for this client

   234 	@param aUids An RArray to be populated with the supported UIDs.  On return with 

   235 			KErrNone this array is populated with the UIDs of the interfaces which 

   236 			this client supports.  Ownership of the RArray remains with the caller.

   237 			Any existing entries in the array will be removed.

   238 	@return KErrNone on successful retrieval of supported interfaces.  System wide

   239 			error code otherwise.

   240 	*/

   241 	IMPORT_C TInt SupportedInterfaces(const TRemConClientId& aId, RArray<TUid>& aUids) ;

   242 

   243 	/**

   244 	Called by the bearer when it wants to retrieve which operations within the interface

   245 	are supported by this client.  Note that this information is not available for all

   246 	interface and client combinations.

   247 	

   248 	@param aId A unique identifier for this client

   249 	@param aInterfaceUid The interface to return the supported operations for

   250 	@param aOperations An RArray to be populated with the supported operations.  

   251 			On return with KErrNone this array is populated with the operation

   252 			ids of each supported operations within the requested interface.  

   253 			Ownership of the RArray remains with the caller.  Any existing 

   254 			entries in the array will be removed.

   255 	@return KErrNone if the supported operations could be successfully retrieved.

   256 			KErrNotSupported if the operations could not be retrieved for this 

   257 			particular client/interface combination.  System wide error code

   258 			otherwise.

   259 	*/

   260 	IMPORT_C TInt SupportedOperations(const TRemConClientId& aId, TUid aInterfaceUid, RArray<TUint>& aOperations);

   261 

   262 	/** 

   263 	Called by the bearer to inform RemCon that remote user action means that

   264 	this bearer will now route addressed commands to the specified client.

   265 	This is valid until either the bearer calls SetRemoteAddressedPlayer again

   266 	or RemCon calls SetLocalAddressedPlayer.

   267 	

   268 	@param aBearerUid The Uid of this bearer

   269 	@param aId The client to which this bearer will route addressed commands.

   270 	*/

   271 	IMPORT_C void SetRemoteAddressedClient(const TUid& aBearerUid, const TRemConClientId& aId);

   272 	

   273 	/**

   274 	Called by the bearer to indicate it would like to be informed when the 

   275 	locally addressed client changes.

   276 	*/

   277 	IMPORT_C TInt RegisterLocalAddressedClientObserver(const TUid& aBearerUid);

   278 	

   279 	/**

   280 	Called by the bearer to indicate it would no longer like to be informed when 

   281 	the locally addressed client changes.

   282 	*/

   283 	IMPORT_C TInt UnregisterLocalAddressedClientObserver(const TUid& aBearerUid);

   284 	

   285 private:

   286 	/** 

   287 	@see NewResponse.

   288 	*/

   289 	virtual TInt MrcboDoNewResponse(const TRemConAddress& aAddr) = 0;	

   290 	

   291 	/** 

   292 	@see NewNotifyResponse.

   293 	*/

   294 	virtual TInt MrcboDoNewNotifyResponse(const TRemConAddress& aAddr) = 0;

   295 	

   296 	/** 

   297 	@see NewCommand.

   298 	*/

   299 	virtual TInt MrcboDoNewCommand(const TRemConAddress& aAddr) = 0;

   300 	

   301 	/** 

   302 	@see NewNotifyCommand.

   303 	*/

   304 	virtual TInt MrcboDoNewNotifyCommand(const TRemConAddress& aAddr) = 0;

   305 

   306 	/** 

   307 	@see ConnectIndicate.

   308 	*/

   309 	virtual TInt MrcboDoConnectIndicate(const TRemConAddress& aAddr) = 0;

   310 	

   311 	/**

   312 	@see DisconnectIndicate.

   313 	*/

   314 	virtual void MrcboDoDisconnectIndicate(const TRemConAddress& aAddr) = 0;

   315 	

   316 	/**

   317 	@see ConnectConfirm.

   318 	*/

   319 	virtual TInt MrcboDoConnectConfirm(const TRemConAddress& aAddr, TInt aError) = 0;

   320 	

   321 	/**

   322 	@see DisconnectConfirm.

   323 	*/

   324 	virtual void MrcboDoDisconnectConfirm(const TRemConAddress& aAddr, TInt aError) = 0;

   325 	

   326 	/**

   327 	@see InterfaceToBearer.

   328 	*/

   329 	virtual TInt MrcboDoInterfaceToBearer(TUid aBearerUid,

   330 		TUid aInterfaceUid, 

   331 		TUint aOperationId,

   332 		const TDesC8& aData,

   333 		TRemConMessageType aMsgType, 

   334 		TDes8& aBearerData) const = 0;

   335 	

   336 	/**

   337 	@see BearerToInterface.

   338 	*/

   339 	virtual TInt MrcboDoBearerToInterface(TUid aBearerUid,

   340 		const TDesC8& aInterfaceData, 

   341 		const TDesC8& aBearerData,

   342 		TUid& aInterfaceUid, 

   343 		TUint& aOperationId,

   344 		TRemConMessageType& aMsgType, 

   345 		TDes8& aData) const = 0;

   346 	

   347 	/**

   348 	@see TransactionId.

   349 	*/

   350 	virtual TUint MrcboDoNewTransactionId() = 0;	

   351 	

   352 	/**

   353 	@see CommandExpired.

   354 	*/

   355 	virtual void MrcboDoCommandExpired(TUint aTransactionId) = 0;	

   356 	

   357 	/**

   358 	@see NewCommand

   359 	*/

   360 	virtual TInt MrcboDoNewCommand(const TRemConAddress& aAddr, const TRemConClientId& aClient) = 0;

   361 

   362 	/** 

   363 	@see NewNotifyCommand

   364 	*/

   365 	virtual TInt MrcboDoNewNotifyCommand(const TRemConAddress& aAddr, const TRemConClientId& aClient) = 0;

   366 

   367 	/**

   368 	@see SupportedInterfaces

   369 	*/

   370 	virtual TInt MrcboDoSupportedInterfaces(const TRemConClientId& aId, RArray<TUid>& aUids) = 0;

   371 

   372 	/**

   373 	@see SupportedOperations

   374 	*/

   375 	virtual TInt MrcboDoSupportedOperations(const TRemConClientId& aId, TUid aInterfaceUid, RArray<TUint>& aOperations) = 0;

   376 

   377 	/**

   378 	@see SetRemoteAddressedClient

   379 	*/

   380 	virtual void MrcboDoSetRemoteAddressedClient(const TUid& aBearerUid, const TRemConClientId& aId) = 0;

   381 	

   382 	/**

   383 	@see RegisterLocalAddressedClientObserver

   384 	*/

   385 	virtual TInt MrcboDoRegisterLocalAddressedClientObserver(const TUid& aBearerUid) = 0;

   386 	

   387 	/**

   388 	@see UnregisterLocalAddressedClientObserver

   389 	*/

   390 	virtual TInt MrcboDoUnregisterLocalAddressedClientObserver(const TUid& aBearerUid) = 0;

   391 	};

   392 

   393 #endif // REMCONBEAREROBSERVER_H