1 remconinterfaceselector.h

     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 

    17 

    18 /**

    19  @file

    20  @publishedAll

    21  @released

    22 */

    23 

    24 #ifndef REMCONINTERFACESELECTOR_H

    25 #define REMCONINTERFACESELECTOR_H

    26 

    27 #include <e32base.h>

    28 #include <remcon/messagetype.h>

    29 #include <remcon/clienttype.h>

    30 #include <remcon/remconclient.h>

    31 #include <remcon/remconinterfaceif.h>

    32 #include <remconaddress.h>

    33 

    34 class CRemConInterfaceBase;

    35 class CReceiver;

    36 class MRemConErrorObserver;

    37 

    38 // Panic information

    39 _LIT(KRemConIfSelPanicCat, "RemConIfSel");

    40 enum 

    41 	{

    42 	/** The client has given a bad message type. */

    43 	ERemConIfSelBadMessageType = 0,

    44 

    45 	/** The client has already called OpenTargetL successfully.

    46 		

    47 	This is no longer an illegal condition and so the panic will never

    48 	be raised.

    49 	*/

    50 	ERemConIfSelTargetSessionAlreadyExists = 1,

    51 

    52 	/** The client has already called OpenControllerL successfully.

    53 		

    54 	This is no longer an illegal condition and so the panic will never

    55 	be raised.

    56 	*/

    57 	ERemConIfSelControllerSessionAlreadyExists = 2,

    58 

    59 	/** The client has created (and registered) an outer layer interface of a 

    60 	type which is already registered. */

    61 	ERemConIfSelInterfaceOfThatTypeAlreadyRegistered = 3,

    62 	

    63 	/** The client has not offended- there is a defect in some layer of the 

    64 	Remote Control system. */

    65 	ERemConIfSelInternalError = 4,

    66 

    67 	/** An outer-layer interface has been instantiated (and registered with 

    68 	the intermediate layer) after OpenControllerL or OpenTargetL has been 

    69 	successfully called. */

    70 	ERemConIfSelTardyInterfaceRegistration = 5,

    71 

    72 	/** OpenControllerL has not successfully been called before using an API 

    73 	which expects a controller session to have been created. */

    74 	ERemConIfSelNoControllerSession = 6,

    75 

    76 	/** OpenTargetL has not successfully been called before using an API which 

    77 	expects a target session to have been created. */

    78 	ERemConIfSelNoTargetSession = 7,

    79 

    80 	/** Neither OpenControllerL not OpenTargetL has been successfully called 

    81 	before using an API which expects either a controller or a target session 

    82 	to have been created. */

    83 	ERemConIfSelNoSession = 8,

    84 

    85 	/** An outer layer DLL has instantiated CRemConInterfaceBase with an 

    86 	illegal client type. */

    87 	ERemConIfSelUndefinedClientType = 9,

    88 

    89 	/** An implementation of CRemConInterfaceBase::GetInterface does not 

    90 	provide an implementation of MRemConInterfaceIf. */

    91 	ERemConIfSelNoInterfaceImplementation = 10,

    92 	};

    93 

    94 /**

    95 CRemConInterfaceSelector is only instantiable via its NewL function. It is not 

    96 derivable.

    97 */

    98 NONSHARABLE_CLASS(CRemConInterfaceSelector) : public CBase

    99 	{

   100 public: 

   101 	/**

   102 	Factory method.

   103 	@return Ownership of a new CRemConInterfaceSelector.

   104 	*/

   105 	IMPORT_C static CRemConInterfaceSelector* NewL();

   106 

   107 	/** Destructor. */

   108 	IMPORT_C ~CRemConInterfaceSelector();

   109 

   110 public:

   111 	/**

   112 	Register the interface with the selector. This is called by the 

   113 	interface's BaseConstructL. Takes ownership of aInterface.

   114 	 This function is not to be called outside of remconinterfacebase.dll. It is available for compatibility with previous

   115 	 versions, but it is intended to be called only by CRemConInterfaceBase::BaseConstructL.

   116 	 CRemConInterfaceBase-derived classes should indirectly perform a RegisterInterfaceL, by calling

   117 	 CRemConInterfaceBase::BaseConstructL from their construction functions.

   118 	@param aInterface The interface.

   119 	*/

   120 	IMPORT_C void RegisterInterfaceL(CRemConInterfaceBase& aInterface);

   121 	

   122 	/** 

   123 	Register an error observer.  This is provided to allow the client to

   124 	discover when an error has occurred passively.

   125 	

   126 	@param aObserver An error observer to be notified on a passive error.

   127 					 NULL to stop receiving notifications.

   128 	*/

   129 	IMPORT_C void RegisterErrorObserver(MRemConErrorObserver* aObserver);

   130 

   131 	/**

   132 	Opens a controller session to RemCon. The session is connectionless until 

   133 	such time as GoConnectionOriented may be called.

   134 	@leave KErrInUse If a controller session is already open.

   135 	*/

   136 	IMPORT_C void OpenControllerL();

   137 

   138 	/**

   139 	Makes the controller session (which must already exist- use 

   140 	OpenControllerL) connection-oriented.

   141 	@param aConnection The remote to talk to. 

   142 	*/

   143 	IMPORT_C void GoConnectionOrientedL(const TRemConAddress& aConnection);

   144 

   145 	/**

   146 	Makes the controller session (which must already exist- use 

   147 	OpenControllerL) connectionless.

   148 	*/

   149 	IMPORT_C void GoConnectionlessL();

   150 

   151 	/**

   152 	Brings up a bearer-level connection.

   153 	The controller session must already exist (use OpenControllerL) and 

   154 	be connection-oriented.

   155 	@param aStatus TRequestStatus for asynchronous completion.

   156 	*/

   157 	IMPORT_C void ConnectBearer(TRequestStatus& aStatus);

   158 

   159 	/**

   160 	Cancels interest in the completion of a ConnectBearer request.

   161 	@return KErrNone.

   162 	*/

   163 	IMPORT_C TInt ConnectBearerCancel();

   164 

   165 	/**

   166 	Destroys a bearer-level connection. 

   167 	The controller session must already exist (use OpenControllerL) and be 

   168 	connection-oriented.

   169 	@param aStatus TRequestStatus for asynchronous completion.

   170 	*/

   171 	IMPORT_C void DisconnectBearer(TRequestStatus& aStat);

   172 

   173 	/**

   174 	Cancels interest in the completion of a DisconnectBearer request.

   175 	@return KErrNone.

   176 	*/

   177 	IMPORT_C TInt DisconnectBearerCancel();

   178 

   179 	/**

   180 	Opens a target session to RemCon.

   181 	@leave KErrInUse If a target session is already open.

   182 	*/

   183 	IMPORT_C void OpenTargetL();

   184 

   185 	/**

   186 	Sends a message to the remote device(s).

   187 	There should be only one command and response outstanding at any one time.

   188 	Send cannot be called again until aStatus is completed.

   189 	@panic RemConClient 4 If a send is already outstanding

   190 	@param aStatus TRequestStatus for asynchronous completion.

   191 	@param aInterfaceUid The UID of the concrete (outer-layer) interface 

   192 	sending the message.

   193 	@param aOperationId The interface-specific operation identifier.

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

   195 	successfully sent to.

   196 	@param aMsgType Whether the message is a command or a response.

   197 	@param aData Any associated message data in interface-specific format.

   198 	*/

   199 	IMPORT_C void Send(TRequestStatus& aStatus, 

   200 		TUid aInterfaceUid,

   201 		TUint aOperationId, 

   202 		TUint& aNumRemotes,

   203 		TRemConMessageType aMsgType,

   204 		const TDesC8& aData = KNullDesC8());

   205 

   206 	/**

   207 	Sends a message to the remote device(s).

   208 	@param aStatus TRequestStatus for asynchronous completion.

   209 	@param aInterfaceUid The UID of the concrete (outer-layer) interface 

   210 	sending the message.

   211 	@param aOperationId The interface-specific operation identifier.

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

   213 	successfully sent to.

   214 	@param aMsgType Whether the message is a command or a response.

   215 	@param aMsgSubType The subtype of the command of response

   216 	@param aData Any associated message data in interface-specific format.

   217 	*/

   218 	IMPORT_C void Send(TRequestStatus& aStatus, 

   219 		TUid aInterfaceUid,

   220 		TUint aOperationId, 

   221 		TUint& aNumRemotes,

   222 		TRemConMessageType aMsgType,

   223 		TRemConMessageSubType aMsgSubType,

   224 		const TDesC8& aData = KNullDesC8());

   225 

   226 	

   227 	/**

   228 	@internalTechnology

   229 	Sends a message to the remote device(s), without waiting for the send to complete

   230 	@param aInterfaceUid The UID of the concrete (outer-layer) interface 

   231 	sending the message.

   232 	@param aOperationId The interface-specific operation identifier.

   233 	@param aMsgType Whether the message is a command or a response.

   234 	@param aData Any associated message data in interface-specific format.

   235 	*/

   236 	IMPORT_C TInt SendUnreliable(

   237 		TUid aInterfaceUid,

   238 		TUint aOperationId, 

   239 		TRemConMessageType aMsgType,

   240 		const TDesC8& aData = KNullDesC8());

   241 	

   242 	/**

   243 	@internalTechnology

   244 	Sends a message to the remote device(s), without waiting for the send to complete

   245 	@param aInterfaceUid The UID of the concrete (outer-layer) interface 

   246 	sending the message.

   247 	@param aOperationId The interface-specific operation identifier.

   248 	@param aMsgType Whether the message is a command or a response.

   249 	@param aMsgSubType The subtype of the command of response

   250 	@param aData Any associated message data in interface-specific format.

   251 	*/

   252 	IMPORT_C TInt SendUnreliable(

   253 		TUid aInterfaceUid,

   254 		TUint aOperationId, 

   255 		TRemConMessageType aMsgType,

   256 		TRemConMessageSubType aMsgSubType,

   257 		const TDesC8& aData = KNullDesC8());

   258 	

   259 	/**

   260 	Cancels interest in the completion of a Send request.

   261 	@param aMsgType The type of the message, the completion of the send of 

   262 	which we are not interested in. This is needed because a single 

   263 	CRemConInterfaceSelector may have two sends outstanding at once, one on 

   264 	a controller session and another on a target session.

   265 	@return KErrNone.

   266 	*/

   267 	IMPORT_C TInt SendCancel(TRemConMessageType aMsgType);

   268 

   269 	/**

   270 	Only called internally, by the Active Object which sucks messages out of 

   271 	RemCon. Note that the message type is not given- it is interpolated from 

   272 	the type of the session doing the receiving.

   273 	@param aInterfaceUid Interface UID of the new message.

   274 	@param aOperationId Operation ID of the new message.

   275 	@param aData Data associated with the new message.

   276 	@param aType The type of session which received the message (from which 

   277 	the type of the message can be interpolated).

   278 	*/

   279 	void ReceiveComplete(TUid aInterfaceUid, 

   280 		TUint aOperationId, 

   281 		TRemConMessageSubType aMsgSubType,

   282 		const TDesC8& aData,

   283 		TRemConClientType aType);

   284 

   285 	/**

   286 	Only called internally, by the Active Object which sucks messages out of 

   287 	RemCon.  This is called in the case of a session error.

   288 	

   289 	@param The error that has occurred.  If this is KErrServerTerminated, the

   290 		   error is fatal and the session must be restarted before any new 

   291 		   messages can be received.

   292 	*/

   293 	void Error(TInt aError);

   294 

   295 	/**

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

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

   298 	aConnections- the addresses will be on the heap.

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

   300 	currently extant connections.

   301 	@return Error.

   302 	*/

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

   304 

   305 	/**

   306 	Notification for changes in the set of connections.

   307 	@param aStatus TRequestStatus for asynchronous completion.

   308 	*/

   309 	IMPORT_C void NotifyConnectionsChange(TRequestStatus& aStatus);

   310 

   311 	/**

   312 	Cancels interest in the completion of an outstanding 

   313 	NotifyConnectionsChange operation.

   314 	@return KErrNone.

   315 	*/

   316 	IMPORT_C TInt NotifyConnectionsChangeCancel();

   317 	

   318 	/**

   319 	To determine if a target session has been opened.

   320 	@return EFalse if no session has been opened, ETrue otherwise.

   321 	*/

   322 	IMPORT_C TBool TargetOpened() const;

   323 

   324 	/**

   325 	To determine if a controller session has been opened.

   326 	@return EFalse if no session has been opened, ETrue otherwise.

   327 	*/	

   328 	IMPORT_C TBool ControllerOpened() const;

   329 

   330 private:

   331 	CRemConInterfaceSelector();

   332 

   333 private: // utility

   334 	void AssertSession(RRemCon* aSess, TInt aPanicCode) const;

   335 	TInt TryToReconnect();

   336 

   337 private: // owned

   338 	RPointerArray<CRemConInterfaceBase> iInterfaces;

   339 

   340 	RRemConController iControllerSession;

   341 	RRemConTarget iTargetSession;

   342 

   343 	CReceiver* iTargetReceiver;

   344 	CReceiver* iControllerReceiver;

   345 

   346 	/** For all registered interfaces, this is the size of the biggest 

   347 	operation-associated data lump. */

   348 	TUint iMaxDataLength;

   349 

   350 	// The session to use for NotifyConnectionsChange and 

   351 	// NotifyConnectionsChangeCancel. It doesn't matter which we use- just one 

   352 	// that's connected will do. The only interesting bit is that the session 

   353 	// we called NotifyConnectionsChange on should be the one we call 

   354 	// NotifyConnectionsChangeCancel on, but as sessions are only closed when 

   355 	// 'this' comes down that's not a complication.

   356 	RRemCon* iNotificationSession;

   357 	

   358 	TRemConAddress iAddress;

   359 

   360 private: // unowned	

   361 	MRemConErrorObserver* iErrorObserver;

   362 	};

   363 

   364 #endif // REMCONINTERFACESELECTOR_H