1.1 --- a/epoc32/include/remcon/remconclient.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,314 +0,0 @@
1.4 -// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 -// All rights reserved.
1.6 -// This component and the accompanying materials are made available
1.7 -// 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.8 -// which accompanies this distribution, and is available
1.9 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 -//
1.11 -// Initial Contributors:
1.12 -// Nokia Corporation - initial contribution.
1.13 -//
1.14 -// Contributors:
1.15 -//
1.16 -// Description:
1.17 -// Remote Control client side.
1.18 -//
1.19 -//
1.20 -
1.21 -
1.22 -
1.23 -/**
1.24 - @file
1.25 - @internalComponent
1.26 -*/
1.27 -
1.28 -#ifndef REMCONCLIENT_H
1.29 -#define REMCONCLIENT_H
1.30 -
1.31 -#include <remcon/clienttype.h>
1.32 -#include <remcon/messagetype.h>
1.33 -#include <remcon/operationinformation.h>
1.34 -
1.35 -class TRemConAddress;
1.36 -
1.37 -/**
1.38 -The abstract base class for RemCon session handles.
1.39 -*/
1.40 -class RRemCon : public RSessionBase
1.41 - {
1.42 -public:
1.43 - /**
1.44 - Connect the handle to the server.
1.45 - Must be called before all other methods (except Version and Close).
1.46 - @return Error.
1.47 - */
1.48 - IMPORT_C TInt Connect();
1.49 -
1.50 - /**
1.51 - Getter for the version of the server.
1.52 - @return Version of the server.
1.53 - */
1.54 - IMPORT_C TVersion Version() const;
1.55 -
1.56 - /**
1.57 - Sends a message (command or response) to the remote device.
1.58 - @param aStatus TRequestStatus for asynchronous completion.
1.59 - @param aInterfaceUid The UID of the interface to which the message
1.60 - belongs.
1.61 - @param aOperationId The ID of the message. RemCon needs to know this,
1.62 - separately from the arbitrary data, so it can (a) match up any incoming
1.63 - response to this client (if the message is a command), and (b) match this
1.64 - message up to the target (if this message is a response).
1.65 - @param aNumRemotes On success only, the number of remotes the message was
1.66 - successfully sent to (at the bearer level). If the message is a command
1.67 - from a connection-oriented controller, then on success aNumRemotes will be
1.68 - 1. [For consistency, this pattern holds if the message is a response, even
1.69 - though the information is redundant.] If the message is a command from a
1.70 - connectionless controller, then aNumRemotes will be zero or more,
1.71 - depending on what the TSP said should be done with the message and how
1.72 - many of the TSP-nominated bearers successfully sent the message.
1.73 - @param aData Data associated with the message.
1.74 - */
1.75 - IMPORT_C void Send(TRequestStatus& aStatus,
1.76 - TUid aInterfaceUid,
1.77 - TUint aOperationId,
1.78 - TUint& aNumRemotes,
1.79 - TRemConMessageSubType aSubType,
1.80 - const TDesC8& aData = KNullDesC8());
1.81 -
1.82 - IMPORT_C TInt SendUnreliable( TUid aInterfaceUid,
1.83 - TUint aOperationId,
1.84 - TRemConMessageSubType aSubType,
1.85 - const TDesC8& aData = KNullDesC8());
1.86 -
1.87 - /**
1.88 - Cancels interest in the completion of an outstanding Send operation.
1.89 - @return KErrNone.
1.90 - */
1.91 - IMPORT_C TInt SendCancel();
1.92 -
1.93 - /**
1.94 - Receive a message (command or response) from the remote device. Note that
1.95 - RemCon server queues both commands and responses so that none are ever
1.96 - thrown away just because the client didn't have a Receive outstanding when
1.97 - they arrived.
1.98 - @param aStatus TRequestStatus for asynchronous completion.
1.99 - @param aInterfaceUid The UID of the interface to which the message
1.100 - belongs.
1.101 - @param aOperationId The ID of the message.
1.102 - @param aData Data associated with the message.
1.103 - */
1.104 - IMPORT_C void Receive(TRequestStatus& aStatus,
1.105 - TUid& aInterfaceUid,
1.106 - TUint& aOperationId,
1.107 - TRemConMessageSubType& aSubType,
1.108 - TDes8& aData);
1.109 -
1.110 - /**
1.111 - Cancels interest in the completion of an outstanding Receive operation.
1.112 - @return KErrNone.
1.113 - */
1.114 - IMPORT_C TInt ReceiveCancel();
1.115 -
1.116 - /**
1.117 - Getter for the current set of connections in the system (not just those
1.118 - associated with this session). The client is responsible for cleaning up
1.119 - the collection- the addresses are on the client's heap.
1.120 - @param aConnections A collection of remote addresses, representing all the
1.121 - currently extant connections. Must be empty when this function is called.
1.122 - @return Error.
1.123 - */
1.124 - IMPORT_C TInt GetConnections(TSglQue<TRemConAddress>& aConnections);
1.125 -
1.126 - /**
1.127 - Notification for changes in the set of connections.
1.128 - This completes whenever the set of connections changes in some way.
1.129 - If they wish to know what specifically changed, the client must call
1.130 - GetConnections and do their own analysis of the results from that.
1.131 - Changes to the connection history of the system are logged internally so
1.132 - that the client will not 'miss' any changes by not reposting the
1.133 - notification quickly enough. However, if more than one bearer-level
1.134 - connection change occurs in the server before the notification is reposted
1.135 - by the client, then the following notification completion may 'cover' more
1.136 - than one actual state change.
1.137 - @param aStatus TRequestStatus for asynchronous completion.
1.138 - */
1.139 - IMPORT_C void NotifyConnectionsChange(TRequestStatus& aStatus);
1.140 -
1.141 - /**
1.142 - Cancels interest in the completion of an outstanding
1.143 - NotifyConnectionsChange operation.
1.144 - @return KErrNone.
1.145 - */
1.146 - IMPORT_C TInt NotifyConnectionsChangeCancel();
1.147 -
1.148 - /**
1.149 - Marks the start of heap cell checking in the server's heap. In release
1.150 - builds, just returns KErrNone.
1.151 - @return Error.
1.152 - */
1.153 - IMPORT_C TInt __DbgMarkHeap();
1.154 -
1.155 - /**
1.156 - Checks that the number of allocated cells on the server's heap is correct.
1.157 - The server is panicked if not. In release builds, just returns KErrNone.
1.158 - @param aCount The expected number of allocated heap cells.
1.159 - @return Error.
1.160 - */
1.161 - IMPORT_C TInt __DbgCheckHeap(TInt aCount);
1.162 -
1.163 - /**
1.164 - Marks the end of heap cell checking. Checks that the number of heap cells
1.165 - allocated since the last __DbgMarkHeap() is aCount; the most common value
1.166 - to pass here is zero. In release builds, just returns KErrNone.
1.167 - @param aCount The expected number of allocated heap cells.
1.168 - @return Error.
1.169 - */
1.170 - IMPORT_C TInt __DbgMarkEnd(TInt aCount);
1.171 -
1.172 - /**
1.173 - Simulates memory allocation failure in the server. In release builds, just
1.174 - returns KErrNone.
1.175 - @param aCount The number of allocations after which memory allocation
1.176 - should fail.
1.177 - @return Error.
1.178 - */
1.179 - IMPORT_C TInt __DbgFailNext(TInt aCount);
1.180 -
1.181 -protected:
1.182 - /**
1.183 - Constructor.
1.184 - @param aType The type of the session.
1.185 - */
1.186 - RRemCon(TRemConClientType aType);
1.187 -
1.188 - /** Destructor. */
1.189 - ~RRemCon();
1.190 -
1.191 -private: // utility
1.192 - TInt DoConnect();
1.193 - TInt SetClientType();
1.194 -
1.195 -private: // owned
1.196 - const TRemConClientType iClientType;
1.197 -
1.198 - /**
1.199 - Used by Send.
1.200 - */
1.201 - TPckg<TUint> iNumRemotesPckg;
1.202 - TPckgBuf<TOperationInformation> iOpInfoPckg;
1.203 -
1.204 - /**
1.205 - Used by Receive.
1.206 - */
1.207 - TPckg<TUint> iUidPckg;
1.208 - TPckg<TUint> iOpIdPckg;
1.209 - TPckg<TRemConMessageSubType> iMsgSubTypePckg;
1.210 - };
1.211 -
1.212 -/**
1.213 -The concrete session class for RemCon controllers.
1.214 -Controller sessions are connectionless when opened. This means that addressing
1.215 -of commands is done by the Target Selector Plugin (TSP). A controller may
1.216 -alternatively be connection-oriented, which means that addressing of commands
1.217 -is done using a member of the server-side session which specifies a connection
1.218 -to a remote device. [NB Just because a session 'points to' a connection in
1.219 -this way does not means that the connection necessarily exists at the bearer
1.220 -level or at any other level.]
1.221 -To make a controller session connection-oriented, call GoConnectionOriented.
1.222 -On success, the session's remote address member will have been set to the
1.223 -requested remote address.
1.224 -To make a session connectionless again, use GoConnectionless. On success, the
1.225 -remote address member will be null, indicating that the TSP will be used to
1.226 -address our commands.
1.227 -To control bearer-level connections, use ConnectBearer and DisconnectBearer.
1.228 -Note that real connections may, depending on the bearer, be torn down by the
1.229 -remote end outside of our control. Use GetConnections (and the associated
1.230 -notification) to get information about the current state of the real
1.231 -connections. Note however that the client is not _required_ to be interested
1.232 -in this level of control as RemCon is responsible for making sure the required
1.233 -connection exists at the bearer level before sending the message. The level of
1.234 -control mentioned is provided to the client so that it can, for instance,
1.235 -ensure adequate responsiveness of the first command sent.
1.236 -ConnectBearerCancel and DisconnectBearerCancel merely cancel interest in the
1.237 -corresponding request. They do not change the state of the system, bearers,
1.238 -connections, or member data in any other way. They operate as pure Symbian OS
1.239 -asynchronous cancel methods.
1.240 -*/
1.241 -class RRemConController : public RRemCon
1.242 - {
1.243 -public:
1.244 - /** Constructor */
1.245 - IMPORT_C RRemConController();
1.246 -
1.247 - /** Destructor */
1.248 - IMPORT_C ~RRemConController();
1.249 -
1.250 - /**
1.251 - Makes the session connection-oriented. On success, the given connection
1.252 - data will be used for sending commands.
1.253 - @param aBearerUid The UID of the bearer to use.
1.254 - @param aData Optional bearer-specific connection data.
1.255 - @return Error.
1.256 - */
1.257 - IMPORT_C TInt GoConnectionOriented(const TRemConAddress& aConnection);
1.258 -
1.259 - /**
1.260 - Makes the session connectionless. On success, the TSP will be used for
1.261 - sending commands.
1.262 - @return Error.
1.263 - */
1.264 - IMPORT_C TInt GoConnectionless();
1.265 -
1.266 - /**
1.267 - Establish a bearer-level connection using the information supplied in
1.268 - GoConnectionOriented.
1.269 - @param aStatus Used by the server to indicate completion of the request.
1.270 - */
1.271 - IMPORT_C void ConnectBearer(TRequestStatus& aStatus);
1.272 -
1.273 - /**
1.274 - Cancels interest in the completion of an outstanding ConnectBearer
1.275 - request. Does not affect the state of the bearer-level connection.
1.276 - @return KErrNone.
1.277 - */
1.278 - IMPORT_C TInt ConnectBearerCancel();
1.279 -
1.280 - /**
1.281 - Triggers bearer-level disconnection of the connection specified in
1.282 - GoConnectionOriented.
1.283 - @param aStatus Used by the server to indicate completion of the request.
1.284 - */
1.285 - IMPORT_C void DisconnectBearer(TRequestStatus& aStatus);
1.286 -
1.287 - /**
1.288 - Cancels interest in the completion of an outstanding DisconnectBearer
1.289 - request. Does not affect the state of the bearer-level connection.
1.290 - @return KErrNone.
1.291 - */
1.292 - IMPORT_C TInt DisconnectBearerCancel();
1.293 - };
1.294 -
1.295 -/**
1.296 -The concrete session class for RemCon targets.
1.297 -*/
1.298 -class RRemConTarget : public RRemCon
1.299 - {
1.300 -public:
1.301 - /** Constructor */
1.302 - IMPORT_C RRemConTarget();
1.303 -
1.304 - /** Destructor */
1.305 - IMPORT_C ~RRemConTarget();
1.306 -
1.307 - /**
1.308 - Tells the server in which APIs the client is interested. The server
1.309 - will only deliver incoming commands of these APIs to the client.
1.310 - @param aNumAPIs The number of APIs to be registered
1.311 - @param aAPIs The concatenation of all the API UIDs.
1.312 - @return The error code returned from the server.
1.313 - */
1.314 - IMPORT_C TInt RegisterInterestedAPIs(TInt aNumAPIs, const TDesC8& aAPIs);
1.315 - };
1.316 -
1.317 -#endif // REMCONCLIENT_H