1 // Copyright (c) 2004-2010 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 // Remote Control client side.

    15 // 

    16 //

    17 

    18 /**

    19  @file

    20  @internalComponent

    21 */

    22 

    23 #ifndef REMCONCLIENT_H

    24 #define REMCONCLIENT_H

    25 

    26 #include <remcon/clienttype.h>

    27 #include <remcon/messagetype.h>

    28 #include <remcon/playertype.h>

    29 #include "operationinformation.h"

    30 #include "remconserver.h"

    31 

    32 class TRemConAddress;

    33 

    34 /**

    35 The abstract base class for RemCon session handles.

    36 */

    37 NONSHARABLE_CLASS(RRemCon) : public RSessionBase

    38 	{

    39 public:

    40 	/**

    41 	Connect the handle to the server.

    42 	Must be called before all other methods (except Version and Close).

    43 	@return Error.

    44 	*/

    45 	IMPORT_C TInt Connect();

    46 

    47 	/**

    48 	Connect the handle to the server.

    49 	Must be called before all other methods (except Version and Close).

    50 	@param aPlayerType  The type of client player

    51 	@param aPlayerSubType The sub-type of the client player

    52 	@param aName The name of client player

    53 	@return Error.

    54 	*/

    55 	IMPORT_C TInt Connect(const TPlayerType& aPlayerType, const TPlayerSubType& aPlayerSubType, const TDesC8& aName);

    56 	/**

    57 	Getter for the version of the server.

    58 	@return Version of the server.

    59 	*/

    60 	virtual TVersion Version() const = 0;

    61 

    62 	/**

    63 	Sends a message (command or response) to the remote device.

    64 	@param aStatus TRequestStatus for asynchronous completion.

    65 	@param aInterfaceUid The UID of the interface to which the message 

    66 	belongs.

    67 	@param aOperationId The ID of the message. RemCon needs to know this, 

    68 	separately from the arbitrary data, so it can (a) match up any incoming 

    69 	response to this client (if the message is a command), and (b) match this 

    70 	message up to the target (if this message is a response).

    71 	@param aNumRemotes On success only, the number of remotes the message was 

    72 	successfully sent to (at the bearer level). If the message is a command 

    73 	from a connection-oriented controller, then on success aNumRemotes will be 

    74 	1. [For consistency, this pattern holds if the message is a response, even 

    75 	though the information is redundant.] If the message is a command from a 

    76 	connectionless controller, then aNumRemotes will be zero or more, 

    77 	depending on what the TSP said should be done with the message and how 

    78 	many of the TSP-nominated bearers successfully sent the message.

    79 	@param aData Data associated with the message.

    80 	*/

    81 	IMPORT_C void Send(TRequestStatus& aStatus, 

    82 		TUid aInterfaceUid, 

    83 		TUint aOperationId, 

    84 		TUint& aNumRemotes,

    85 		TRemConMessageSubType aSubType,

    86 		const TDesC8& aData = KNullDesC8());

    87 	

    88 	IMPORT_C void SendNotify(TRequestStatus& aStatus, 

    89 			TUid aInterfaceUid, 

    90 			TUint aOperationId, 

    91 			TRemConMessageSubType aSubType,

    92 			const TDesC8& aData = KNullDesC8());

    93 	

    94 	IMPORT_C TInt SendUnreliable(	TUid aInterfaceUid, 

    95 			TUint aOperationId,

    96 			TRemConMessageSubType aSubType,

    97 			const TDesC8& aData = KNullDesC8());

    98 

    99 	/**

   100 	Cancels interest in the completion of an outstanding Send operation.

   101 	@return KErrNone.

   102 	*/

   103 	IMPORT_C TInt SendCancel();

   104 

   105 	/**

   106 	Receive a message (command or response) from the remote device. Note that 

   107 	RemCon server queues both commands and responses so that none are ever 

   108 	thrown away just because the client didn't have a Receive outstanding when 

   109 	they arrived.

   110 	@param aStatus TRequestStatus for asynchronous completion.

   111 	@param aReceivePackage A struct containing the received message.

   112 	@param aData Data associated with the message.

   113 	*/

   114 	IMPORT_C void Receive(TRequestStatus& aStatus, 

   115 		TRemConClientReceivePackage& aReceivePackage,

   116 		TDes8& aData);

   117 

   118 	/**

   119 	Cancels interest in the completion of an outstanding Receive operation.

   120 	@return KErrNone.

   121 	*/

   122 	IMPORT_C TInt ReceiveCancel();

   123 

   124 	/**

   125 	Getter for the current set of connections in the system (not just those 

   126 	associated with this session). The client is responsible for cleaning up 

   127 	the collection- the addresses are on the client's heap.

   128 	@param aConnections A collection of remote addresses, representing all the 

   129 	currently extant connections. Must be empty when this function is called.

   130 	@return Error.

   131 	*/

   132 	IMPORT_C TInt GetConnections(TSglQue<TRemConAddress>& aConnections);

   133 

   134 	/**

   135 	Notification for changes in the set of connections.

   136 	This completes whenever the set of connections changes in some way. 

   137 	If they wish to know what specifically changed, the client must call 

   138 	GetConnections and do their own analysis of the results from that.

   139 	Changes to the connection history of the system are logged internally so 

   140 	that the client will not 'miss' any changes by not reposting the 

   141 	notification quickly enough. However, if more than one bearer-level 

   142 	connection change occurs in the server before the notification is reposted 

   143 	by the client, then the following notification completion may 'cover' more 

   144 	than one actual state change. 

   145 	@param aStatus TRequestStatus for asynchronous completion.

   146 	*/

   147 	IMPORT_C void NotifyConnectionsChange(TRequestStatus& aStatus);

   148 

   149 	/**

   150 	Cancels interest in the completion of an outstanding 

   151 	NotifyConnectionsChange operation.

   152 	@return KErrNone.

   153 	*/

   154 	IMPORT_C TInt NotifyConnectionsChangeCancel();

   155 

   156 	/** 

   157 	 Tells the server in which APIs the client is interested. The server 

   158 	 will only deliver incoming commands of these APIs to the client.

   159 	 @param aNumAPIs The number of APIs to be registered

   160 	 @param aAPIs A concatenated string of UIDs for the interfaces present. 

   161 	 @return The error code returned from the server.

   162 	 */

   163 	IMPORT_C TInt RegisterInterestedAPIs(const TDesC8& aAPIs);

   164 	

   165 	/**

   166 	Marks the start of heap cell checking in the server's heap. In release 

   167 	builds, just returns KErrNone.

   168 	@return Error.

   169 	*/

   170 	IMPORT_C TInt __DbgMarkHeap();

   171 

   172 	/**

   173 	Checks that the number of allocated cells on the server's heap is correct. 

   174 	The server is panicked if not. In release builds, just returns KErrNone.

   175 	@param aCount The expected number of allocated heap cells.

   176 	@return Error.

   177 	*/

   178 	IMPORT_C TInt __DbgCheckHeap(TInt aCount);

   179 

   180 	/**

   181 	Marks the end of heap cell checking. Checks that the number of heap cells 

   182 	allocated since the last __DbgMarkHeap() is aCount; the most common value 

   183 	to pass here is zero. In release builds, just returns KErrNone.

   184 	@param aCount The expected number of allocated heap cells.

   185 	@return Error.

   186 	*/

   187 	IMPORT_C TInt __DbgMarkEnd(TInt aCount);

   188 

   189 	/**

   190 	Simulates memory allocation failure in the server. In release builds, just 

   191 	returns KErrNone.

   192 	@param aCount The number of allocations after which memory allocation 

   193 	should fail.

   194 	@return Error.

   195 	*/

   196 	IMPORT_C TInt __DbgFailNext(TInt aCount);

   197 

   198 protected:

   199 	/**

   200 	@param aType The type of the session.

   201 	*/

   202 	RRemCon(TRemConClientType aType);

   203 

   204 private: // utility

   205 	TInt DoConnect();

   206 	TInt SetPlayerType(const TPlayerType& aPlayerType, const TPlayerSubType& aPlayerSubType, const TDesC8& aName);

   207 

   208 private: // owned

   209 	const TRemConClientType iClientType;

   210 

   211 	/** 

   212 	Used by Send.

   213 	*/

   214 	TPckg<TUint> iNumRemotesPckg;

   215 	TPckgBuf<TOperationInformation> iOpInfoPckg;

   216 	

   217 	/** 

   218 	Used by Receive.

   219 	*/

   220 	TPckg<TRemConClientReceivePackage> iReceivePckg;

   221 	TPckgBuf<TPlayerTypeInformation> iPlayerTypePckg;

   222 	};

   223 

   224 /**

   225 The concrete session class for RemCon controllers.

   226 Controller sessions are connectionless when opened. This means that addressing 

   227 of commands is done by the Target Selector Plugin (TSP). A controller may 

   228 alternatively be connection-oriented, which means that addressing of commands 

   229 is done using a member of the server-side session which specifies a connection 

   230 to a remote device. [NB Just because a session 'points to' a connection in 

   231 this way does not means that the connection necessarily exists at the bearer 

   232 level or at any other level.]

   233 To make a controller session connection-oriented, call GoConnectionOriented. 

   234 On success, the session's remote address member will have been set to the 

   235 requested remote address.

   236 To make a session connectionless again, use GoConnectionless. On success, the 

   237 remote address member will be null, indicating that the TSP will be used to 

   238 address our commands.

   239 To control bearer-level connections, use ConnectBearer and DisconnectBearer. 

   240 Note that real connections may, depending on the bearer, be torn down by the 

   241 remote end outside of our control. Use GetConnections (and the associated 

   242 notification) to get information about the current state of the real 

   243 connections. Note however that the client is not _required_ to be interested 

   244 in this level of control as RemCon is responsible for making sure the required 

   245 connection exists at the bearer level before sending the message. The level of 

   246 control mentioned is provided to the client so that it can, for instance, 

   247 ensure adequate responsiveness of the first command sent.

   248 ConnectBearerCancel and DisconnectBearerCancel merely cancel interest in the 

   249 corresponding request. They do not change the state of the system, bearers, 

   250 connections, or member data in any other way. They operate as pure Symbian OS 

   251 asynchronous cancel methods.

   252 */

   253 NONSHARABLE_CLASS(RRemConController) : public RRemCon

   254 	{

   255 public:

   256 	IMPORT_C RRemConController();

   257 

   258 	/**

   259 	Makes the session connection-oriented. On success, the given connection 

   260 	data will be used for sending commands.

   261 	@param aBearerUid The UID of the bearer to use.

   262 	@param aData Optional bearer-specific connection data.

   263 	@return Error.

   264 	*/

   265 	IMPORT_C TInt GoConnectionOriented(const TRemConAddress& aConnection);

   266 

   267 	/**

   268 	Makes the session connectionless. On success, the TSP will be used for 

   269 	sending commands.

   270 	@return Error.

   271 	*/

   272 	IMPORT_C TInt GoConnectionless();

   273 

   274 	/** 

   275 	Establish a bearer-level connection using the information supplied in 

   276 	GoConnectionOriented.

   277 	@param aStatus Used by the server to indicate completion of the request.

   278 	*/	

   279 	IMPORT_C void ConnectBearer(TRequestStatus& aStatus);

   280 

   281 	/**

   282 	Cancels interest in the completion of an outstanding ConnectBearer 

   283 	request. Does not affect the state of the bearer-level connection.

   284 	@return KErrNone.

   285 	*/

   286 	IMPORT_C TInt ConnectBearerCancel();

   287 

   288 	/** 

   289 	Triggers bearer-level disconnection of the connection specified in 

   290 	GoConnectionOriented.

   291 	@param aStatus Used by the server to indicate completion of the request.

   292 	*/	

   293 	IMPORT_C void DisconnectBearer(TRequestStatus& aStatus);

   294 

   295 	/**

   296 	Cancels interest in the completion of an outstanding DisconnectBearer 

   297 	request. Does not affect the state of the bearer-level connection.

   298 	@return KErrNone.

   299 	*/

   300 	IMPORT_C TInt DisconnectBearerCancel();

   301 

   302 	/** Returns the version of the RemCon server interface this session supports.

   303 	@return Supported version

   304 	*/

   305 	TVersion Version() const;

   306 	};

   307 

   308 /**

   309 The concrete session class for RemCon targets.

   310 */

   311 NONSHARABLE_CLASS(RRemConTarget) : public RRemCon

   312 	{

   313 public:

   314 	IMPORT_C RRemConTarget();

   315 	

   316 	/** Returns the version of the RemCon server interface this session supports.

   317 	@return Supported version

   318 	*/

   319 	TVersion Version() const;

   320 	};

   321 

   322 #endif // REMCONCLIENT_H