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