|
1 /* |
|
2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Store API to retrieve presence attribute models. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef __CPENGATTRIBUTESTORE2_H__ |
|
20 #define __CPENGATTRIBUTESTORE2_H__ |
|
21 |
|
22 // INCLUDES |
|
23 #include <E32Base.h> |
|
24 |
|
25 |
|
26 //FORWARD DECLARATIONS |
|
27 class CPEngAttributeStore2Imp; |
|
28 class CPEngNWSessionSlotID2; |
|
29 class MPEngPresenceAttrModel2; |
|
30 |
|
31 |
|
32 |
|
33 |
|
34 /** |
|
35 * Store API to retrieve presence attribute models. |
|
36 * |
|
37 * With this API clients can access presence attributes |
|
38 * from two different category: |
|
39 * |
|
40 * 1. Cached presence attributes |
|
41 * Cached presence attributes are subscribed or fetched |
|
42 * presence attributes stored to presence cache. |
|
43 * Clients can only read values from these attributes. |
|
44 * Cached attribute objects are available to clients |
|
45 * only when attribute data is in the storage. |
|
46 * (Attribute is either subscribed or fetched from network.) |
|
47 * Cached data is available only during active network session. |
|
48 * |
|
49 * |
|
50 * 2. User own presence attributes |
|
51 * Own presence attributes present the user own presence status. |
|
52 * Presence Engine has always user own attributes defined. |
|
53 * On terminal hold user own attributes are initially in their |
|
54 * default state. Each concrete attribute type defines |
|
55 * its own default state. |
|
56 * |
|
57 * To user own presence attributes clients can perform: |
|
58 * - edit user own presence attributes |
|
59 * - store edited user own attributes back to presence storage |
|
60 * - publish user own presence attributes to network |
|
61 * |
|
62 * User own attributes are stored to permanent presence storage. |
|
63 * User own attribuets have empty Presence ID. See |
|
64 * KPEngUserOwnPresenceId from PEngPresenceEngineConsts2.h |
|
65 * |
|
66 * |
|
67 * When loading attribute objects, ownership of created |
|
68 * attribute objects is returned to caller. |
|
69 * |
|
70 * NOTE!! Attribute objects can't be pushed directly with |
|
71 * CleanupStack::PushL() to CleanupStack. CleanupStack consideres |
|
72 * MPEngPresenceAttrModel2 objects as TAny pointers and frees their |
|
73 * memory directly without deleting properly such objects. Thus clients |
|
74 * need to use CleanupClosePushL( *presenceAttrModel2 ) to push |
|
75 * retrieved objects to CleanupStack. |
|
76 * |
|
77 * @lib PEngManager2.lib |
|
78 * @since 3.0 |
|
79 */ |
|
80 class CPEngAttributeStore2 : public CBase |
|
81 { |
|
82 //----------------------------------------------------------------------- |
|
83 public: /* Construction */ |
|
84 |
|
85 |
|
86 /** |
|
87 * Instantiates CPEngAttributeStore2 object. |
|
88 * |
|
89 * Instantiates CPEngAttributeStore2 object and connects it to |
|
90 * identified Presence Engine side NWSessionSlot. NWSessionSlot |
|
91 * must be a valid, existing slot. |
|
92 * |
|
93 * Errors: |
|
94 * - Requested NWSessionSlot not found: KErrNotFound |
|
95 * - Given NWSessionSlotID malformed: KErrArgument |
|
96 * |
|
97 * @param aNWSessionSlotID The session slot ID to identify the |
|
98 * session slot. |
|
99 * @param aPriority The priority for Presence Engine client side active |
|
100 * objects. These active objects are used when asynchronously delivering |
|
101 * events to observers or maintaining Presence Cache state. |
|
102 * |
|
103 * @return New CPEngAttributeStore2 instance. |
|
104 */ |
|
105 IMPORT_C static CPEngAttributeStore2* NewL( |
|
106 const CPEngNWSessionSlotID2& aNWSessionSlotID, |
|
107 TInt aPriority = CActive::EPriorityStandard ); |
|
108 |
|
109 IMPORT_C static CPEngAttributeStore2* NewLC( |
|
110 const CPEngNWSessionSlotID2& aNWSessionSlotID, |
|
111 TInt aPriority = CActive::EPriorityStandard ); |
|
112 |
|
113 |
|
114 /** |
|
115 * Destructor. |
|
116 * Virtual by CBase. |
|
117 */ |
|
118 ~CPEngAttributeStore2(); |
|
119 |
|
120 |
|
121 |
|
122 private: |
|
123 |
|
124 CPEngAttributeStore2(); |
|
125 |
|
126 |
|
127 |
|
128 |
|
129 //----------------------------------------------------------------------- |
|
130 public: /* Cached presence attributes */ |
|
131 |
|
132 /** |
|
133 * Gets a cached presence attribute. |
|
134 * Ownership of created model is transferred to caller. |
|
135 * |
|
136 * @since 3.0 |
|
137 * @param aPresenceID The user's presence id |
|
138 * @param aType The attribute type. Presence Engine known |
|
139 * attribute types are listed in PEngWVPresenceAttributes2.h. |
|
140 * @param aModel Returns retrieved attribute model. If retrieve |
|
141 * fails with error, NULL pointer is returned. |
|
142 * Ownership of created model is transferred to caller. |
|
143 * Object can be destroyed either with normal delete operator |
|
144 * or MPEngPresenceAttrModel2::Close() method. If CleanupStack |
|
145 * is used, object must be pushed with CleanupClosePushL(). |
|
146 * |
|
147 * @return Status code from attribute loading: |
|
148 * - KErrNone if loading succeeds. |
|
149 * - KErrNotSupported if attribute type isn't supported. |
|
150 * - KErrNotFound if attribute isn't found from presence cache. |
|
151 * - Else one of system wide error codes. |
|
152 */ |
|
153 IMPORT_C TInt GetCachedAttribute( |
|
154 const TDesC& aPresenceID, |
|
155 TUint32 aType, |
|
156 MPEngPresenceAttrModel2*& aModel ) const; |
|
157 |
|
158 |
|
159 /** |
|
160 * Gets a cached presence attribute for editing. |
|
161 * Ownership of created model is transferred to caller. |
|
162 * |
|
163 * Loaded model can be read, edited and stored back to cache. |
|
164 * |
|
165 * Loading tries to gain exclusive write lock for attribute. |
|
166 * If some other client already has a exclusive write lock |
|
167 * for the attribute, the attribute model loading fails with |
|
168 * KErrLocked. Once write locked attribute stays locked until |
|
169 * the attribute model instance owning the lock is destroyed. |
|
170 * |
|
171 * @since 3.0 |
|
172 * @param aType The attribute type. Presence Engine known |
|
173 * attribute types are listed in PEngWVPresenceAttributes2.h. |
|
174 * @param aModel Returns retrieved attribute model. If retrieve |
|
175 * fails with error, NULL pointer is returned. |
|
176 * Ownership of created model is transferred to caller. |
|
177 * Object can be destroyed either with normal delete operator |
|
178 * or MPEngPresenceAttrModel2::Close() method. If CleanupStack |
|
179 * is used, object must be pushed with CleanupClosePushL(). |
|
180 * |
|
181 * @return Status code from attribute loading: |
|
182 * - KErrNone if loading succeeds. |
|
183 * - KErrNotSupported if attribute type isn't supported. |
|
184 * - KErrLocked if attribute model is already locked. |
|
185 * - Else one of system wide error codes. |
|
186 */ |
|
187 IMPORT_C TInt GetAndLockCachedAttribute( |
|
188 const TDesC& aPresenceID, |
|
189 TUint32 aType, |
|
190 MPEngPresenceAttrModel2*& aModel ); |
|
191 |
|
192 |
|
193 /** |
|
194 * Stores editable cached presence attribute to presence |
|
195 * storage. Ownership of model stays on the caller. |
|
196 * The attribute model edit lock is kept or released |
|
197 * depending the aReleaseEditLock parameter. |
|
198 * |
|
199 * @since 3.0 |
|
200 * @param aModel The attribute model to store. |
|
201 * @param aKeepLocked If ETrue, attribute model |
|
202 * edit lock is released if storing succeeds. If EFalse, |
|
203 * attribute model is kept edit locked in all cases. |
|
204 * @return Status code from attribute storing: |
|
205 * - KErrNone if storing succeeds. |
|
206 * - KErrArgument if attribute is either loaded from another |
|
207 * NWSessionSlot or it isn't locked for edit. |
|
208 * - Else one of system wide error codes. |
|
209 */ |
|
210 IMPORT_C TInt StoreCachedAttribute( |
|
211 MPEngPresenceAttrModel2& aModel, |
|
212 TBool aReleaseEditLock = ETrue ); |
|
213 |
|
214 |
|
215 |
|
216 //----------------------------------------------------------------------- |
|
217 public: /* User own presence attributes */ |
|
218 |
|
219 /** |
|
220 * Gets a user own presence attribute for reading. |
|
221 * Ownership of created model is transferred to caller. |
|
222 * |
|
223 * Loaded model can be only read. If attribute value is tried |
|
224 * to edit or save to storage, those operations will fail with |
|
225 * error. |
|
226 * |
|
227 * @since 3.0 |
|
228 * @param aType The attribute type. Presence Engine known |
|
229 * attribute types are listed in PEngWVPresenceAttributes2.h. |
|
230 * @param aModel Returns retrieved attribute model. If retrieve |
|
231 * fails with error, NULL pointer is returned. |
|
232 * Ownership of created model is transferred to caller. |
|
233 * Object can be destroyed either with normal delete operator |
|
234 * or MPEngPresenceAttrModel2::Close() method. If CleanupStack |
|
235 * is used, object must be pushed with CleanupClosePushL(). |
|
236 * |
|
237 * @return Status code from attribute loading: |
|
238 * - KErrNone if loading succeeds. |
|
239 * - KErrNotSupported if attribute type isn't supported. |
|
240 * - Else one of system wide error codes. |
|
241 */ |
|
242 IMPORT_C TInt GetOwnAttribute( |
|
243 TUint32 aType, |
|
244 MPEngPresenceAttrModel2*& aModel ) const; |
|
245 |
|
246 |
|
247 |
|
248 /** |
|
249 * Gets a user own presence attribute for editing. |
|
250 * Ownership of created model is transferred to caller. |
|
251 * |
|
252 * Loaded model can be read or edited or published to network. |
|
253 * |
|
254 * Loading tries to gain exclusive write lock for attribute. |
|
255 * If some other client already has a exclusive write lock |
|
256 * for the attribute, the attribute model loading fails with |
|
257 * KErrLocked. Once write locked attribute stays locked until |
|
258 * - the attribute model instance owning the lock is destroyed |
|
259 * - the lock is freed with CPEngAttributeStore2::UnLockOwnAttribute() |
|
260 * - the attribute model is published to network with |
|
261 * CPEngAttributeTransaction2::PublishAndUnLockOwnAttribute() |
|
262 * |
|
263 * @since 3.0 |
|
264 * @param aType The attribute type. Presence Engine known |
|
265 * attribute types are listed in PEngWVPresenceAttributes2.h. |
|
266 * @param aModel Returns retrieved attribute model. If retrieve |
|
267 * fails with error, NULL pointer is returned. |
|
268 * Ownership of created model is transferred to caller. |
|
269 * Object can be destroyed either with normal delete operator |
|
270 * or MPEngPresenceAttrModel2::Close() method. If CleanupStack |
|
271 * is used, object must be pushed with CleanupClosePushL(). |
|
272 * |
|
273 * @return Status code from attribute loading: |
|
274 * - KErrNone if loading succeeds. |
|
275 * - KErrNotSupported if attribute type isn't supported. |
|
276 * - KErrLocked if attribute model is already locked. |
|
277 * - Else one of system wide error codes. |
|
278 */ |
|
279 IMPORT_C TInt GetAndLockOwnAttribute( |
|
280 TUint32 aType, |
|
281 MPEngPresenceAttrModel2*& aModel ); |
|
282 |
|
283 |
|
284 /** |
|
285 * Stores editable user own presence attribute to presence |
|
286 * storage. Ownership of model stays on the caller. |
|
287 * The attribute model edit lock is kept or released |
|
288 * depending the aReleaseEditLock parameter. |
|
289 * |
|
290 * @since 3.0 |
|
291 * @param aModel The attribute model to store. |
|
292 * @param aKeepLocked If ETrue, attribute model |
|
293 * edit lock is released if storing succeeds. If EFalse, |
|
294 * attribute model is kept edit locked in all cases. |
|
295 * @return Status code from attribute storing: |
|
296 * - KErrNone if storing succeeds. |
|
297 * - KErrArgument if attribute is either loaded from another |
|
298 * NWSessionSlot or it isn't locked for edit. |
|
299 * - Else one of system wide error codes. |
|
300 */ |
|
301 IMPORT_C TInt StoreOwnAttribute( |
|
302 MPEngPresenceAttrModel2& aModel, |
|
303 TBool aReleaseEditLock = ETrue ); |
|
304 |
|
305 |
|
306 /** |
|
307 * Frees the write lock owned by the model. |
|
308 * Ownership of model stays on the caller. |
|
309 * |
|
310 * @since 3.0 |
|
311 * @param aModel The attribute model which write lock to free. |
|
312 * @return Status code from attribute storing: |
|
313 * - KErrNone if unlocking succeeds. |
|
314 * - KErrArgument if attribute is either loaded from another |
|
315 * NWSessionSlot or it isn't locked for edit. (In this case |
|
316 * the lock isn't freed.) |
|
317 */ |
|
318 IMPORT_C TInt UnLockOwnAttribute( |
|
319 MPEngPresenceAttrModel2& aModel ); |
|
320 |
|
321 |
|
322 |
|
323 |
|
324 /** |
|
325 * Checks is the given user owned attribute |
|
326 * write locked or not. |
|
327 * |
|
328 * @since 3.0 |
|
329 * @param aType The attribute type. Presence Engine known attribute |
|
330 * types are listed in PEngWVPresenceAttributes2.h. |
|
331 * @return Status code from lock checking: |
|
332 * - KErrNone if not locked. |
|
333 * - KErrNotSupported if attribute type isn't supported. |
|
334 * - KErrLocked if attribute model is locked. |
|
335 * - Else one of system wide error codes. |
|
336 */ |
|
337 IMPORT_C TInt OwnAttributeAvailable( |
|
338 TUint32 aType ) const; |
|
339 |
|
340 |
|
341 |
|
342 |
|
343 //----------------------------------------------------------------------- |
|
344 public: /* Common utilities */ |
|
345 |
|
346 /** |
|
347 * Checks is the given attribute type supported or not. |
|
348 * |
|
349 * Attribute types that Presence Engine knows are listed |
|
350 * in PEngWVPresenceAttributes2.h. Support for some of |
|
351 * attribute types is variated with CenRep local variation |
|
352 * keys or depends from currently used WV CSP protocol version. |
|
353 * |
|
354 * This method can be used to check is certain attribute type |
|
355 * supported currently or not. |
|
356 * |
|
357 * @since 3.0 |
|
358 * @param aType The attribute type. Presence Engine known attribute |
|
359 * types are listed in PEngWVPresenceAttributes2.h. |
|
360 * @return Status code from lock checking: |
|
361 * - KErrNone if attribute type is supported. |
|
362 * - KErrNotSupported if attribute type isn't supported. |
|
363 */ |
|
364 IMPORT_C TInt AttributeTypeSupported( TUint32 aType ) const; |
|
365 |
|
366 |
|
367 |
|
368 //----------------------------------------------------------------------- |
|
369 private: /* Data */ |
|
370 |
|
371 |
|
372 //OWN: Implementation |
|
373 CPEngAttributeStore2Imp* iImp; |
|
374 |
|
375 }; |
|
376 |
|
377 |
|
378 |
|
379 #endif // __CPENGATTRIBUTESTORE2_H__ |
|
380 |