--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/accessoryservices/remotecontrolfw/client/common/remconclient.h	Tue Feb 02 00:53:00 2010 +0200
@@ -0,0 +1,313 @@
+// 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:
+// Remote Control client side.
+// 
+//
+
+/**
+ @file
+ @internalComponent
+*/
+
+#ifndef REMCONCLIENT_H
+#define REMCONCLIENT_H
+
+#include <remcon/clienttype.h>
+#include <remcon/messagetype.h>
+#include <remcon/playertype.h>
+#include "operationinformation.h"
+#include "remconserver.h"
+
+class TRemConAddress;
+
+/**
+The abstract base class for RemCon session handles.
+*/
+class RRemCon : public RSessionBase
+	{
+public:
+	/**
+	Connect the handle to the server.
+	Must be called before all other methods (except Version and Close).
+	@return Error.
+	*/
+	IMPORT_C TInt Connect();
+
+	/**
+	Connect the handle to the server.
+	Must be called before all other methods (except Version and Close).
+	@param aClientType  The type of client player
+	@param aClientSubType The sub-type of the client player
+	@param aName The name of client player
+	@return Error.
+	*/
+	IMPORT_C TInt Connect(const TPlayerType& aClientType, const TPlayerSubType& aClientSubType, const TDesC8& aName);
+	/**
+	Getter for the version of the server.
+	@return Version of the server.
+	*/
+	IMPORT_C TVersion Version() const;
+
+	/**
+	Sends a message (command or response) to the remote device.
+	@param aStatus TRequestStatus for asynchronous completion.
+	@param aInterfaceUid The UID of the interface to which the message 
+	belongs.
+	@param aOperationId The ID of the message. RemCon needs to know this, 
+	separately from the arbitrary data, so it can (a) match up any incoming 
+	response to this client (if the message is a command), and (b) match this 
+	message up to the target (if this message is a response).
+	@param aNumRemotes On success only, the number of remotes the message was 
+	successfully sent to (at the bearer level). If the message is a command 
+	from a connection-oriented controller, then on success aNumRemotes will be 
+	1. [For consistency, this pattern holds if the message is a response, even 
+	though the information is redundant.] If the message is a command from a 
+	connectionless controller, then aNumRemotes will be zero or more, 
+	depending on what the TSP said should be done with the message and how 
+	many of the TSP-nominated bearers successfully sent the message.
+	@param aData Data associated with the message.
+	*/
+	IMPORT_C void Send(TRequestStatus& aStatus, 
+		TUid aInterfaceUid, 
+		TUint aOperationId, 
+		TUint& aNumRemotes,
+		TRemConMessageSubType aSubType,
+		const TDesC8& aData = KNullDesC8());
+	
+	IMPORT_C void SendNotify(TRequestStatus& aStatus, 
+			TUid aInterfaceUid, 
+			TUint aOperationId, 
+			TRemConMessageSubType aSubType,
+			const TDesC8& aData = KNullDesC8());
+	
+	IMPORT_C TInt SendUnreliable(	TUid aInterfaceUid, 
+			TUint aOperationId,
+			TRemConMessageSubType aSubType,
+			const TDesC8& aData = KNullDesC8());
+
+	/**
+	Cancels interest in the completion of an outstanding Send operation.
+	@return KErrNone.
+	*/
+	IMPORT_C TInt SendCancel();
+
+	/**
+	Receive a message (command or response) from the remote device. Note that 
+	RemCon server queues both commands and responses so that none are ever 
+	thrown away just because the client didn't have a Receive outstanding when 
+	they arrived.
+	@param aStatus TRequestStatus for asynchronous completion.
+	@param aReceivePackage A struct containing the received message.
+	@param aData Data associated with the message.
+	*/
+	IMPORT_C void Receive(TRequestStatus& aStatus, 
+		TRemConClientReceivePackage& aReceivePackage,
+		TDes8& aData);
+
+	/**
+	Cancels interest in the completion of an outstanding Receive operation.
+	@return KErrNone.
+	*/
+	IMPORT_C TInt ReceiveCancel();
+
+	/**
+	Getter for the current set of connections in the system (not just those 
+	associated with this session). The client is responsible for cleaning up 
+	the collection- the addresses are on the client's heap.
+	@param aConnections A collection of remote addresses, representing all the 
+	currently extant connections. Must be empty when this function is called.
+	@return Error.
+	*/
+	IMPORT_C TInt GetConnections(TSglQue<TRemConAddress>& aConnections);
+
+	/**
+	Notification for changes in the set of connections.
+	This completes whenever the set of connections changes in some way. 
+	If they wish to know what specifically changed, the client must call 
+	GetConnections and do their own analysis of the results from that.
+	Changes to the connection history of the system are logged internally so 
+	that the client will not 'miss' any changes by not reposting the 
+	notification quickly enough. However, if more than one bearer-level 
+	connection change occurs in the server before the notification is reposted 
+	by the client, then the following notification completion may 'cover' more 
+	than one actual state change. 
+	@param aStatus TRequestStatus for asynchronous completion.
+	*/
+	IMPORT_C void NotifyConnectionsChange(TRequestStatus& aStatus);
+
+	/**
+	Cancels interest in the completion of an outstanding 
+	NotifyConnectionsChange operation.
+	@return KErrNone.
+	*/
+	IMPORT_C TInt NotifyConnectionsChangeCancel();
+
+	/** 
+	 Tells the server in which APIs the client is interested. The server 
+	 will only deliver incoming commands of these APIs to the client.
+	 @param aNumAPIs The number of APIs to be registered
+	 @param aAPIs A concatenated string of UIDs for the interfaces present. 
+	 @return The error code returned from the server.
+	 */
+	IMPORT_C TInt RegisterInterestedAPIs(const TDesC8& aAPIs);
+	
+	/**
+	Marks the start of heap cell checking in the server's heap. In release 
+	builds, just returns KErrNone.
+	@return Error.
+	*/
+	IMPORT_C TInt __DbgMarkHeap();
+
+	/**
+	Checks that the number of allocated cells on the server's heap is correct. 
+	The server is panicked if not. In release builds, just returns KErrNone.
+	@param aCount The expected number of allocated heap cells.
+	@return Error.
+	*/
+	IMPORT_C TInt __DbgCheckHeap(TInt aCount);
+
+	/**
+	Marks the end of heap cell checking. Checks that the number of heap cells 
+	allocated since the last __DbgMarkHeap() is aCount; the most common value 
+	to pass here is zero. In release builds, just returns KErrNone.
+	@param aCount The expected number of allocated heap cells.
+	@return Error.
+	*/
+	IMPORT_C TInt __DbgMarkEnd(TInt aCount);
+
+	/**
+	Simulates memory allocation failure in the server. In release builds, just 
+	returns KErrNone.
+	@param aCount The number of allocations after which memory allocation 
+	should fail.
+	@return Error.
+	*/
+	IMPORT_C TInt __DbgFailNext(TInt aCount);
+
+protected:
+	/**
+	@param aType The type of the session.
+	*/
+	RRemCon(TRemConClientType aType);
+
+private: // utility
+	TInt DoConnect();
+	TInt SetClientType();
+	TInt SetClientType(const TPlayerType& aClientType, const TPlayerSubType& aClientSubType, const TDesC8& aName);
+
+private: // owned
+	const TRemConClientType iClientType;
+
+	/** 
+	Used by Send.
+	*/
+	TPckg<TUint> iNumRemotesPckg;
+	TPckgBuf<TOperationInformation> iOpInfoPckg;
+	
+	/** 
+	Used by Receive.
+	*/
+	TPckg<TRemConClientReceivePackage> iReceivePckg;
+	TPckgBuf<TPlayerTypeInformation> iPlayerTypePckg;
+	};
+
+/**
+The concrete session class for RemCon controllers.
+Controller sessions are connectionless when opened. This means that addressing 
+of commands is done by the Target Selector Plugin (TSP). A controller may 
+alternatively be connection-oriented, which means that addressing of commands 
+is done using a member of the server-side session which specifies a connection 
+to a remote device. [NB Just because a session 'points to' a connection in 
+this way does not means that the connection necessarily exists at the bearer 
+level or at any other level.]
+To make a controller session connection-oriented, call GoConnectionOriented. 
+On success, the session's remote address member will have been set to the 
+requested remote address.
+To make a session connectionless again, use GoConnectionless. On success, the 
+remote address member will be null, indicating that the TSP will be used to 
+address our commands.
+To control bearer-level connections, use ConnectBearer and DisconnectBearer. 
+Note that real connections may, depending on the bearer, be torn down by the 
+remote end outside of our control. Use GetConnections (and the associated 
+notification) to get information about the current state of the real 
+connections. Note however that the client is not _required_ to be interested 
+in this level of control as RemCon is responsible for making sure the required 
+connection exists at the bearer level before sending the message. The level of 
+control mentioned is provided to the client so that it can, for instance, 
+ensure adequate responsiveness of the first command sent.
+ConnectBearerCancel and DisconnectBearerCancel merely cancel interest in the 
+corresponding request. They do not change the state of the system, bearers, 
+connections, or member data in any other way. They operate as pure Symbian OS 
+asynchronous cancel methods.
+*/
+class RRemConController : public RRemCon
+	{
+public:
+	IMPORT_C RRemConController();
+
+	/**
+	Makes the session connection-oriented. On success, the given connection 
+	data will be used for sending commands.
+	@param aBearerUid The UID of the bearer to use.
+	@param aData Optional bearer-specific connection data.
+	@return Error.
+	*/
+	IMPORT_C TInt GoConnectionOriented(const TRemConAddress& aConnection);
+
+	/**
+	Makes the session connectionless. On success, the TSP will be used for 
+	sending commands.
+	@return Error.
+	*/
+	IMPORT_C TInt GoConnectionless();
+
+	/** 
+	Establish a bearer-level connection using the information supplied in 
+	GoConnectionOriented.
+	@param aStatus Used by the server to indicate completion of the request.
+	*/	
+	IMPORT_C void ConnectBearer(TRequestStatus& aStatus);
+
+	/**
+	Cancels interest in the completion of an outstanding ConnectBearer 
+	request. Does not affect the state of the bearer-level connection.
+	@return KErrNone.
+	*/
+	IMPORT_C TInt ConnectBearerCancel();
+
+	/** 
+	Triggers bearer-level disconnection of the connection specified in 
+	GoConnectionOriented.
+	@param aStatus Used by the server to indicate completion of the request.
+	*/	
+	IMPORT_C void DisconnectBearer(TRequestStatus& aStatus);
+
+	/**
+	Cancels interest in the completion of an outstanding DisconnectBearer 
+	request. Does not affect the state of the bearer-level connection.
+	@return KErrNone.
+	*/
+	IMPORT_C TInt DisconnectBearerCancel();
+	};
+
+/**
+The concrete session class for RemCon targets.
+*/
+class RRemConTarget : public RRemCon
+	{
+public:
+	IMPORT_C RRemConTarget();
+	};
+
+#endif // REMCONCLIENT_H