epoc32/include/remconinterfaceselector.h
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
     1.1 --- a/epoc32/include/remconinterfaceselector.h	Tue Nov 24 13:55:44 2009 +0000
     1.2 +++ b/epoc32/include/remconinterfaceselector.h	Tue Mar 16 16:12:26 2010 +0000
     1.3 @@ -1,1 +1,364 @@
     1.4 -remconinterfaceselector.h
     1.5 +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
     1.6 +// All rights reserved.
     1.7 +// This component and the accompanying materials are made available
     1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     1.9 +// which accompanies this distribution, and is available
    1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
    1.11 +//
    1.12 +// Initial Contributors:
    1.13 +// Nokia Corporation - initial contribution.
    1.14 +//
    1.15 +// Contributors:
    1.16 +//
    1.17 +// Description:
    1.18 +//
    1.19 +
    1.20 +
    1.21 +
    1.22 +/**
    1.23 + @file
    1.24 + @publishedAll
    1.25 + @released
    1.26 +*/
    1.27 +
    1.28 +#ifndef REMCONINTERFACESELECTOR_H
    1.29 +#define REMCONINTERFACESELECTOR_H
    1.30 +
    1.31 +#include <e32base.h>
    1.32 +#include <remcon/messagetype.h>
    1.33 +#include <remcon/clienttype.h>
    1.34 +#include <remcon/remconclient.h>
    1.35 +#include <remcon/remconinterfaceif.h>
    1.36 +#include <remconaddress.h>
    1.37 +
    1.38 +class CRemConInterfaceBase;
    1.39 +class CReceiver;
    1.40 +class MRemConErrorObserver;
    1.41 +
    1.42 +// Panic information
    1.43 +_LIT(KRemConIfSelPanicCat, "RemConIfSel");
    1.44 +enum 
    1.45 +	{
    1.46 +	/** The client has given a bad message type. */
    1.47 +	ERemConIfSelBadMessageType = 0,
    1.48 +
    1.49 +	/** The client has already called OpenTargetL successfully.
    1.50 +		
    1.51 +	This is no longer an illegal condition and so the panic will never
    1.52 +	be raised.
    1.53 +	*/
    1.54 +	ERemConIfSelTargetSessionAlreadyExists = 1,
    1.55 +
    1.56 +	/** The client has already called OpenControllerL successfully.
    1.57 +		
    1.58 +	This is no longer an illegal condition and so the panic will never
    1.59 +	be raised.
    1.60 +	*/
    1.61 +	ERemConIfSelControllerSessionAlreadyExists = 2,
    1.62 +
    1.63 +	/** The client has created (and registered) an outer layer interface of a 
    1.64 +	type which is already registered. */
    1.65 +	ERemConIfSelInterfaceOfThatTypeAlreadyRegistered = 3,
    1.66 +	
    1.67 +	/** The client has not offended- there is a defect in some layer of the 
    1.68 +	Remote Control system. */
    1.69 +	ERemConIfSelInternalError = 4,
    1.70 +
    1.71 +	/** An outer-layer interface has been instantiated (and registered with 
    1.72 +	the intermediate layer) after OpenControllerL or OpenTargetL has been 
    1.73 +	successfully called. */
    1.74 +	ERemConIfSelTardyInterfaceRegistration = 5,
    1.75 +
    1.76 +	/** OpenControllerL has not successfully been called before using an API 
    1.77 +	which expects a controller session to have been created. */
    1.78 +	ERemConIfSelNoControllerSession = 6,
    1.79 +
    1.80 +	/** OpenTargetL has not successfully been called before using an API which 
    1.81 +	expects a target session to have been created. */
    1.82 +	ERemConIfSelNoTargetSession = 7,
    1.83 +
    1.84 +	/** Neither OpenControllerL not OpenTargetL has been successfully called 
    1.85 +	before using an API which expects either a controller or a target session 
    1.86 +	to have been created. */
    1.87 +	ERemConIfSelNoSession = 8,
    1.88 +
    1.89 +	/** An outer layer DLL has instantiated CRemConInterfaceBase with an 
    1.90 +	illegal client type. */
    1.91 +	ERemConIfSelUndefinedClientType = 9,
    1.92 +
    1.93 +	/** An implementation of CRemConInterfaceBase::GetInterface does not 
    1.94 +	provide an implementation of MRemConInterfaceIf. */
    1.95 +	ERemConIfSelNoInterfaceImplementation = 10,
    1.96 +	};
    1.97 +
    1.98 +/**
    1.99 +CRemConInterfaceSelector is only instantiable via its NewL function. It is not 
   1.100 +derivable.
   1.101 +*/
   1.102 +NONSHARABLE_CLASS(CRemConInterfaceSelector) : public CBase
   1.103 +	{
   1.104 +public: 
   1.105 +	/**
   1.106 +	Factory method.
   1.107 +	@return Ownership of a new CRemConInterfaceSelector.
   1.108 +	*/
   1.109 +	IMPORT_C static CRemConInterfaceSelector* NewL();
   1.110 +
   1.111 +	/** Destructor. */
   1.112 +	IMPORT_C ~CRemConInterfaceSelector();
   1.113 +
   1.114 +public:
   1.115 +	/**
   1.116 +	Register the interface with the selector. This is called by the 
   1.117 +	interface's BaseConstructL. Takes ownership of aInterface.
   1.118 +	 This function is not to be called outside of remconinterfacebase.dll. It is available for compatibility with previous
   1.119 +	 versions, but it is intended to be called only by CRemConInterfaceBase::BaseConstructL.
   1.120 +	 CRemConInterfaceBase-derived classes should indirectly perform a RegisterInterfaceL, by calling
   1.121 +	 CRemConInterfaceBase::BaseConstructL from their construction functions.
   1.122 +	@param aInterface The interface.
   1.123 +	*/
   1.124 +	IMPORT_C void RegisterInterfaceL(CRemConInterfaceBase& aInterface);
   1.125 +	
   1.126 +	/** 
   1.127 +	Register an error observer.  This is provided to allow the client to
   1.128 +	discover when an error has occurred passively.
   1.129 +	
   1.130 +	@param aObserver An error observer to be notified on a passive error.
   1.131 +					 NULL to stop receiving notifications.
   1.132 +	*/
   1.133 +	IMPORT_C void RegisterErrorObserver(MRemConErrorObserver* aObserver);
   1.134 +
   1.135 +	/**
   1.136 +	Opens a controller session to RemCon. The session is connectionless until 
   1.137 +	such time as GoConnectionOriented may be called.
   1.138 +	@leave KErrInUse If a controller session is already open.
   1.139 +	*/
   1.140 +	IMPORT_C void OpenControllerL();
   1.141 +
   1.142 +	/**
   1.143 +	Makes the controller session (which must already exist- use 
   1.144 +	OpenControllerL) connection-oriented.
   1.145 +	@param aConnection The remote to talk to. 
   1.146 +	*/
   1.147 +	IMPORT_C void GoConnectionOrientedL(const TRemConAddress& aConnection);
   1.148 +
   1.149 +	/**
   1.150 +	Makes the controller session (which must already exist- use 
   1.151 +	OpenControllerL) connectionless.
   1.152 +	*/
   1.153 +	IMPORT_C void GoConnectionlessL();
   1.154 +
   1.155 +	/**
   1.156 +	Brings up a bearer-level connection.
   1.157 +	The controller session must already exist (use OpenControllerL) and 
   1.158 +	be connection-oriented.
   1.159 +	@param aStatus TRequestStatus for asynchronous completion.
   1.160 +	*/
   1.161 +	IMPORT_C void ConnectBearer(TRequestStatus& aStatus);
   1.162 +
   1.163 +	/**
   1.164 +	Cancels interest in the completion of a ConnectBearer request.
   1.165 +	@return KErrNone.
   1.166 +	*/
   1.167 +	IMPORT_C TInt ConnectBearerCancel();
   1.168 +
   1.169 +	/**
   1.170 +	Destroys a bearer-level connection. 
   1.171 +	The controller session must already exist (use OpenControllerL) and be 
   1.172 +	connection-oriented.
   1.173 +	@param aStatus TRequestStatus for asynchronous completion.
   1.174 +	*/
   1.175 +	IMPORT_C void DisconnectBearer(TRequestStatus& aStat);
   1.176 +
   1.177 +	/**
   1.178 +	Cancels interest in the completion of a DisconnectBearer request.
   1.179 +	@return KErrNone.
   1.180 +	*/
   1.181 +	IMPORT_C TInt DisconnectBearerCancel();
   1.182 +
   1.183 +	/**
   1.184 +	Opens a target session to RemCon.
   1.185 +	@leave KErrInUse If a target session is already open.
   1.186 +	*/
   1.187 +	IMPORT_C void OpenTargetL();
   1.188 +
   1.189 +	/**
   1.190 +	Sends a message to the remote device(s).
   1.191 +	There should be only one command and response outstanding at any one time.
   1.192 +	Send cannot be called again until aStatus is completed.
   1.193 +	@panic RemConClient 4 If a send is already outstanding
   1.194 +	@param aStatus TRequestStatus for asynchronous completion.
   1.195 +	@param aInterfaceUid The UID of the concrete (outer-layer) interface 
   1.196 +	sending the message.
   1.197 +	@param aOperationId The interface-specific operation identifier.
   1.198 +	@param aNumRemotes On success, the number of remotes the message was 
   1.199 +	successfully sent to.
   1.200 +	@param aMsgType Whether the message is a command or a response.
   1.201 +	@param aData Any associated message data in interface-specific format.
   1.202 +	*/
   1.203 +	IMPORT_C void Send(TRequestStatus& aStatus, 
   1.204 +		TUid aInterfaceUid,
   1.205 +		TUint aOperationId, 
   1.206 +		TUint& aNumRemotes,
   1.207 +		TRemConMessageType aMsgType,
   1.208 +		const TDesC8& aData = KNullDesC8());
   1.209 +
   1.210 +	/**
   1.211 +	Sends a message to the remote device(s).
   1.212 +	@param aStatus TRequestStatus for asynchronous completion.
   1.213 +	@param aInterfaceUid The UID of the concrete (outer-layer) interface 
   1.214 +	sending the message.
   1.215 +	@param aOperationId The interface-specific operation identifier.
   1.216 +	@param aNumRemotes On success, the number of remotes the message was 
   1.217 +	successfully sent to.
   1.218 +	@param aMsgType Whether the message is a command or a response.
   1.219 +	@param aMsgSubType The subtype of the command of response
   1.220 +	@param aData Any associated message data in interface-specific format.
   1.221 +	*/
   1.222 +	IMPORT_C void Send(TRequestStatus& aStatus, 
   1.223 +		TUid aInterfaceUid,
   1.224 +		TUint aOperationId, 
   1.225 +		TUint& aNumRemotes,
   1.226 +		TRemConMessageType aMsgType,
   1.227 +		TRemConMessageSubType aMsgSubType,
   1.228 +		const TDesC8& aData = KNullDesC8());
   1.229 +
   1.230 +	
   1.231 +	/**
   1.232 +	@internalTechnology
   1.233 +	Sends a message to the remote device(s), without waiting for the send to complete
   1.234 +	@param aInterfaceUid The UID of the concrete (outer-layer) interface 
   1.235 +	sending the message.
   1.236 +	@param aOperationId The interface-specific operation identifier.
   1.237 +	@param aMsgType Whether the message is a command or a response.
   1.238 +	@param aData Any associated message data in interface-specific format.
   1.239 +	*/
   1.240 +	IMPORT_C TInt SendUnreliable(
   1.241 +		TUid aInterfaceUid,
   1.242 +		TUint aOperationId, 
   1.243 +		TRemConMessageType aMsgType,
   1.244 +		const TDesC8& aData = KNullDesC8());
   1.245 +	
   1.246 +	/**
   1.247 +	@internalTechnology
   1.248 +	Sends a message to the remote device(s), without waiting for the send to complete
   1.249 +	@param aInterfaceUid The UID of the concrete (outer-layer) interface 
   1.250 +	sending the message.
   1.251 +	@param aOperationId The interface-specific operation identifier.
   1.252 +	@param aMsgType Whether the message is a command or a response.
   1.253 +	@param aMsgSubType The subtype of the command of response
   1.254 +	@param aData Any associated message data in interface-specific format.
   1.255 +	*/
   1.256 +	IMPORT_C TInt SendUnreliable(
   1.257 +		TUid aInterfaceUid,
   1.258 +		TUint aOperationId, 
   1.259 +		TRemConMessageType aMsgType,
   1.260 +		TRemConMessageSubType aMsgSubType,
   1.261 +		const TDesC8& aData = KNullDesC8());
   1.262 +	
   1.263 +	/**
   1.264 +	Cancels interest in the completion of a Send request.
   1.265 +	@param aMsgType The type of the message, the completion of the send of 
   1.266 +	which we are not interested in. This is needed because a single 
   1.267 +	CRemConInterfaceSelector may have two sends outstanding at once, one on 
   1.268 +	a controller session and another on a target session.
   1.269 +	@return KErrNone.
   1.270 +	*/
   1.271 +	IMPORT_C TInt SendCancel(TRemConMessageType aMsgType);
   1.272 +
   1.273 +	/**
   1.274 +	Only called internally, by the Active Object which sucks messages out of 
   1.275 +	RemCon. Note that the message type is not given- it is interpolated from 
   1.276 +	the type of the session doing the receiving.
   1.277 +	@param aInterfaceUid Interface UID of the new message.
   1.278 +	@param aOperationId Operation ID of the new message.
   1.279 +	@param aData Data associated with the new message.
   1.280 +	@param aType The type of session which received the message (from which 
   1.281 +	the type of the message can be interpolated).
   1.282 +	*/
   1.283 +	void ReceiveComplete(TUid aInterfaceUid, 
   1.284 +		TUint aOperationId, 
   1.285 +		TRemConMessageSubType aMsgSubType,
   1.286 +		const TDesC8& aData,
   1.287 +		TRemConClientType aType);
   1.288 +
   1.289 +	/**
   1.290 +	Only called internally, by the Active Object which sucks messages out of 
   1.291 +	RemCon.  This is called in the case of a session error.
   1.292 +	
   1.293 +	@param The error that has occurred.  If this is KErrServerTerminated, the
   1.294 +		   error is fatal and the session must be restarted before any new 
   1.295 +		   messages can be received.
   1.296 +	*/
   1.297 +	void Error(TInt aError);
   1.298 +
   1.299 +	/**
   1.300 +	Getter for the current set of connections in the system (not just those 
   1.301 +	associated with this session). The client is responsible for cleaning up 
   1.302 +	aConnections- the addresses will be on the heap.
   1.303 +	@param aConnections A collection of remote addresses, representing all the 
   1.304 +	currently extant connections.
   1.305 +	@return Error.
   1.306 +	*/
   1.307 +	IMPORT_C TInt GetConnections(TSglQue<TRemConAddress>& aConnections);
   1.308 +
   1.309 +	/**
   1.310 +	Notification for changes in the set of connections.
   1.311 +	@param aStatus TRequestStatus for asynchronous completion.
   1.312 +	*/
   1.313 +	IMPORT_C void NotifyConnectionsChange(TRequestStatus& aStatus);
   1.314 +
   1.315 +	/**
   1.316 +	Cancels interest in the completion of an outstanding 
   1.317 +	NotifyConnectionsChange operation.
   1.318 +	@return KErrNone.
   1.319 +	*/
   1.320 +	IMPORT_C TInt NotifyConnectionsChangeCancel();
   1.321 +	
   1.322 +	/**
   1.323 +	To determine if a target session has been opened.
   1.324 +	@return EFalse if no session has been opened, ETrue otherwise.
   1.325 +	*/
   1.326 +	IMPORT_C TBool TargetOpened() const;
   1.327 +
   1.328 +	/**
   1.329 +	To determine if a controller session has been opened.
   1.330 +	@return EFalse if no session has been opened, ETrue otherwise.
   1.331 +	*/	
   1.332 +	IMPORT_C TBool ControllerOpened() const;
   1.333 +
   1.334 +private:
   1.335 +	CRemConInterfaceSelector();
   1.336 +
   1.337 +private: // utility
   1.338 +	void AssertSession(RRemCon* aSess, TInt aPanicCode) const;
   1.339 +	TInt TryToReconnect();
   1.340 +
   1.341 +private: // owned
   1.342 +	RPointerArray<CRemConInterfaceBase> iInterfaces;
   1.343 +
   1.344 +	RRemConController iControllerSession;
   1.345 +	RRemConTarget iTargetSession;
   1.346 +
   1.347 +	CReceiver* iTargetReceiver;
   1.348 +	CReceiver* iControllerReceiver;
   1.349 +
   1.350 +	/** For all registered interfaces, this is the size of the biggest 
   1.351 +	operation-associated data lump. */
   1.352 +	TUint iMaxDataLength;
   1.353 +
   1.354 +	// The session to use for NotifyConnectionsChange and 
   1.355 +	// NotifyConnectionsChangeCancel. It doesn't matter which we use- just one 
   1.356 +	// that's connected will do. The only interesting bit is that the session 
   1.357 +	// we called NotifyConnectionsChange on should be the one we call 
   1.358 +	// NotifyConnectionsChangeCancel on, but as sessions are only closed when 
   1.359 +	// 'this' comes down that's not a complication.
   1.360 +	RRemCon* iNotificationSession;
   1.361 +	
   1.362 +	TRemConAddress iAddress;
   1.363 +
   1.364 +private: // unowned	
   1.365 +	MRemConErrorObserver* iErrorObserver;
   1.366 +	};
   1.367 +
   1.368 +#endif // REMCONINTERFACESELECTOR_H