1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/remcon/remconclient.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,314 @@
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