|
1 // Copyright (c) 2006-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 "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // RConnectionServ: client access to the comms framework management plane |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @file |
|
20 @publishedPartner |
|
21 @released |
|
22 */ |
|
23 |
|
24 |
|
25 #ifndef ES_CONNECTION_SERV_H |
|
26 #define ES_CONNECTION_SERV_H |
|
27 |
|
28 #include <e32std.h> |
|
29 #include <es_sock.h> |
|
30 #include <comms-infras/cs_connservparams.h> |
|
31 #include <comms-infras/cs_connservparams_internal.h> |
|
32 #include <comms-infras/es_connectionservparameterbundle.h> |
|
33 |
|
34 namespace ConnectionServ |
|
35 { |
|
36 |
|
37 class TAvailability; |
|
38 class CConnectionServParameterBundle; |
|
39 |
|
40 |
|
41 |
|
42 |
|
43 class MAccessPointNotificationObserver |
|
44 /** |
|
45 Interface to react to access point notifications |
|
46 */ |
|
47 { |
|
48 public: |
|
49 // Called when a notification occurs. Ownership of aResult is handed to the implementer of this method |
|
50 // .. so if you want to keep aResult after this method returns, just store the pointer. |
|
51 // When you've finished looking at aResult, you must delete it. |
|
52 // |
|
53 virtual void AccessPointNotification(CConnectionServParameterBundle* aResult) = 0; |
|
54 |
|
55 // Called when there is an error. No further notifications will occur after this |
|
56 // function is called. |
|
57 // |
|
58 virtual void AccessPointNotificationError(TInt aErrCode) = 0; |
|
59 }; |
|
60 |
|
61 |
|
62 |
|
63 class CConnectionServImpl; |
|
64 |
|
65 class RConnectionServ : public RCommsSession |
|
66 /** |
|
67 Provides access to the comms management plane. |
|
68 */ |
|
69 { |
|
70 public: |
|
71 |
|
72 friend class CConnectionServImpl; |
|
73 |
|
74 |
|
75 // HOUSEKEEPING |
|
76 |
|
77 IMPORT_C RConnectionServ(); |
|
78 |
|
79 /** |
|
80 Opens a new RConnServer session. |
|
81 |
|
82 @param aTierId Id of the Tier to connect to. |
|
83 To use the instance the client connects to a Tier, depending on the technology they need to address. |
|
84 All actions are then performed in the context of that Tier until Close is called. |
|
85 The Tier Id may be Null which indicates all tiers. At the moment no functionality supports the Null value. |
|
86 @return KErrNone if successful, otherwise another of the system wide error codes. |
|
87 */ |
|
88 IMPORT_C TInt Connect(TUint aTierId); |
|
89 |
|
90 |
|
91 /** |
|
92 Ends the session and ends the association with the Tier that was specified in Connect. |
|
93 */ |
|
94 IMPORT_C void Close(); |
|
95 |
|
96 |
|
97 // ACCESS POINT QUERY |
|
98 |
|
99 /** |
|
100 Retrieve information from the Tier(s) specified in the Connect function about the availability of one or more services. |
|
101 |
|
102 aQuery is an in parameter. It must be created and deleted (after the request has completed!) by the caller of this method. |
|
103 The Parameter Bundle contains 1 Parameter Set Container (at present). |
|
104 The Parameter Set Container contains 1 or more query Parameter Sets to specify the Access Point or group of Access Points it wishes |
|
105 to retrieve information about. |
|
106 |
|
107 aResult is an out parameter. It must be created and deleted (after the request has completed!) by the caller of this method. |
|
108 The Connection Server populates this bundle with information about the access points that matched the query. |
|
109 |
|
110 The time taken to perform this action depends on the implementation in the Tier Manager stack plug-in that serves the tier this session is attached to. |
|
111 Hence it's an asynchronous request. |
|
112 |
|
113 It delegates to active objects to do its work, and hence the passed-in TRequestStatus is completed by the thread that calls this function. |
|
114 Therefore it is not possible to make this call act "synchronously" by just using WaitForRequest on the following line |
|
115 to the call to this function. Instead you'd have to kick off a worker thread to perform this call, |
|
116 then use your main thread to do the waiting for the completion. |
|
117 This should only be a problem for test code, as all "real-world" apps are event based anyway so would supply an active object for |
|
118 this request, therefore would return control to the active scheduler which can then do what it needs to complete the request. |
|
119 */ |
|
120 IMPORT_C void AccessPointStatusQuery(const CConnectionServParameterBundle& aQuery, CConnectionServParameterBundle& aResult, TRequestStatus& aStatus); |
|
121 |
|
122 |
|
123 /** |
|
124 Tell the Connection Server we are cancelling our status query request. If no query is active, does nothing. |
|
125 |
|
126 This function is synchronous, in that it ensures the cancel has gone all the way through to the server before |
|
127 it returns. |
|
128 */ |
|
129 IMPORT_C void CancelAccessPointStatusQuery(); |
|
130 |
|
131 |
|
132 |
|
133 // ACCESS POINT NOTIFICATION |
|
134 |
|
135 /** |
|
136 As for AccessPointStatusQuery, but will notify of changes to availability of requested Access Point(s). |
|
137 |
|
138 aQuery is an in parameter. It must be created and deleted (after the request has completed!) by the caller of this method. |
|
139 The Parameter Bundle contains 1 Parameter Set Container (at present). |
|
140 The Parameter Set Container contains 1 or more query Parameter Sets to specify the Access Point or group of Access Points it wishes |
|
141 to retrieve information about. |
|
142 |
|
143 The aQuery defines a set of access points. |
|
144 As soon as this "view" is established on the server, an empty bundle gets reported to the observer |
|
145 (see second argument, aObserver) to denote that all the notifications are all registered on the server side. |
|
146 After that, Access Points entering or leaving the set get reported to the observer. |
|
147 This is at least the case for the generic tier parameters. |
|
148 Tiers with advanced parameters (e.g. signal strength) may define their own criteria as to when to notify |
|
149 (e.g. signal strength crossing some threshold by some amount) |
|
150 Queueing of multiple events happens automatically on the server side. |
|
151 |
|
152 aObserver refers to a client-defined implementation of the MAccessPointNotificationObserver interface - |
|
153 this defines an AccessPointNotification(CConnectionServParameterBundle* aResult) method (which is called on each |
|
154 result back from the connection server), and an AccessPointNotificationError() method which is called in case of |
|
155 an error. |
|
156 |
|
157 Notifications are performed by a worker active object. Therefore you must have an active scheduler to use this API, |
|
158 and a return of control to the active scheduler is required before any notification or error will be received via your observer. |
|
159 */ |
|
160 IMPORT_C void AccessPointNotification(const CConnectionServParameterBundle& aQuery, MAccessPointNotificationObserver& aObserver); |
|
161 |
|
162 /** |
|
163 Tell the Connection Server we are cancelling our notification session. If no notification session is active, does nothing. |
|
164 |
|
165 This function is synchronous, in that it ensures the cancel has gone all the way through to the server before |
|
166 it returns. |
|
167 */ |
|
168 IMPORT_C void CancelAccessPointNotification(); |
|
169 |
|
170 |
|
171 |
|
172 private: |
|
173 |
|
174 CConnectionServImpl* iConnectionServImpl; |
|
175 }; |
|
176 |
|
177 |
|
178 } // namespace ConnectionServ |
|
179 |
|
180 |
|
181 |
|
182 #endif // ES_CONNECTION_SERV_H |
|
183 |