63
|
1 |
/*
|
|
2 |
* Copyright (c) 2004-2007 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: An interface for contact views.
|
|
15 |
*
|
|
16 |
*/
|
|
17 |
|
|
18 |
|
|
19 |
#ifndef MVPBKCONTACTVIEWBASE_H
|
|
20 |
#define MVPBKCONTACTVIEWBASE_H
|
|
21 |
|
|
22 |
// INCLUDES
|
|
23 |
#include <e32cmn.h>
|
|
24 |
#include <VPbkContactView.hrh>
|
|
25 |
#include <bamdesca.h>
|
|
26 |
|
|
27 |
// FORWARD DECLARATIONS
|
|
28 |
class MVPbkContactViewObserver;
|
|
29 |
class MVPbkViewContact;
|
|
30 |
class MVPbkContactLink;
|
|
31 |
class MVPbkFieldTypeList;
|
|
32 |
class MVPbkContactBookmark;
|
|
33 |
class MVPbkContactViewFiltering;
|
|
34 |
|
|
35 |
// CLASS DECLARATIONS
|
|
36 |
|
|
37 |
/**
|
|
38 |
* An common interface for different contact views.
|
|
39 |
*
|
|
40 |
* The contact view interface has many implementations. It can be a view from
|
|
41 |
* a single contact store or it can be a composite of contact/group views from
|
|
42 |
* different stores. It's also possible that it contains folding items that
|
|
43 |
* are not from any store. The client defines the view structure.
|
|
44 |
*
|
|
45 |
* The most common usage is that client uses CVPbkContactManager
|
|
46 |
* for creating a contact view and defines the structure of the view.
|
|
47 |
* @see CVPbkContactManager::CreateContactViewLC
|
|
48 |
*/
|
|
49 |
class MVPbkContactViewBase
|
|
50 |
{
|
|
51 |
public: // Destructor
|
|
52 |
|
|
53 |
/**
|
|
54 |
* Destructor.
|
|
55 |
*/
|
|
56 |
virtual ~MVPbkContactViewBase() { }
|
|
57 |
|
|
58 |
public: // New functions
|
|
59 |
|
|
60 |
/**
|
|
61 |
* Returns type of this contact view.
|
|
62 |
*
|
|
63 |
* @return A contact view type.
|
|
64 |
*/
|
|
65 |
virtual TVPbkContactViewType Type() const = 0;
|
|
66 |
|
|
67 |
/**
|
|
68 |
* Changes sort order of the view asynchronously.
|
|
69 |
*
|
|
70 |
* Clients of this view will get an event via MVPbkContactViewObserver
|
|
71 |
* interface when the order has been updated. The leaf view sends
|
|
72 |
* a pair of events. First it sends ContactViewUnavailable and then
|
|
73 |
* after the order has been changed ContactViewReady. However if
|
|
74 |
* the view is of type EVPbkCompositeView the client doesn't necessary
|
|
75 |
* receive ContactViewUnavailable at all because it might be that
|
|
76 |
* there is always some subview ready in the composite.
|
|
77 |
*
|
|
78 |
* @param aSortOrder A new sort order for this view.
|
|
79 |
* @exception KErrArgument Possible reasons: a client tries to change
|
|
80 |
* a sort order of platform defined shared
|
|
81 |
* view against the platform setting.
|
|
82 |
* @see CVPbkSortOrder
|
|
83 |
*/
|
|
84 |
virtual void ChangeSortOrderL(
|
|
85 |
const MVPbkFieldTypeList& aSortOrder ) = 0;
|
|
86 |
|
|
87 |
/**
|
|
88 |
* Returns the current sort order of the view.
|
|
89 |
*
|
|
90 |
* The sort order is a sub set of master field types from
|
|
91 |
* CVPbkContactManager.
|
|
92 |
*
|
|
93 |
* @return The sort order of the view.
|
|
94 |
*/
|
|
95 |
virtual const MVPbkFieldTypeList& SortOrder() const = 0;
|
|
96 |
|
|
97 |
/**
|
|
98 |
* Refreshes the view contents asynchronously.
|
|
99 |
*
|
|
100 |
* All handles to this view's contacts are invalidated.
|
|
101 |
* Clients of this view will get an event via MVPbkContactViewObserver
|
|
102 |
* interface when the view has been refreshed.
|
|
103 |
*/
|
|
104 |
virtual void RefreshL() = 0;
|
|
105 |
|
|
106 |
/**
|
|
107 |
* Returns the number of contacts in this view.
|
|
108 |
*
|
|
109 |
* @return The number of contacts.
|
|
110 |
*/
|
|
111 |
virtual TInt ContactCountL() const = 0;
|
|
112 |
|
|
113 |
/**
|
|
114 |
* Returns a contact in this view.
|
|
115 |
*
|
|
116 |
* The returned reference may be invalidated when this
|
|
117 |
* function is called again. For that reason clients should prefer
|
|
118 |
* not to save references to the contacts retrieved from this function.
|
|
119 |
*
|
|
120 |
* @param aIndex An index of the contact in this view.
|
|
121 |
* @return A reference to a contact in this view at aIndex.
|
|
122 |
* @precond aIndex >= 0
|
|
123 |
* VPbkError::Panic(VPbkError::EInvalidContactIndex)
|
|
124 |
* is raised if the precondition does not hold.
|
|
125 |
* @exception KErrArgument if aIndex >= ContactCountL()
|
|
126 |
*/
|
|
127 |
virtual const MVPbkViewContact& ContactAtL(
|
|
128 |
TInt aIndex ) const = 0;
|
|
129 |
|
|
130 |
/**
|
|
131 |
* Creates and returns a link that points to contact at aIndex.
|
|
132 |
*
|
|
133 |
* NOTE: If the view contact is not from any store it can return
|
|
134 |
* also NULL. E.g. if the view contact is a folding
|
|
135 |
* contact view that it's not saved to any store.
|
|
136 |
* The NULL is not pushed onto the cleanup stack.
|
|
137 |
*
|
|
138 |
* @param aIndex An index of the contact for which the link
|
|
139 |
* is created.
|
|
140 |
* @return A new link object pointing to contact at aIndex or NULL if
|
|
141 |
* the link can't be created (e.g. a folder).
|
|
142 |
* @precond aIndex >= 0
|
|
143 |
* VPbkError::Panic(VPbkError::EInvalidContactIndex)
|
|
144 |
* is raised if the precondition does not hold.
|
|
145 |
* @exception KErrArgument if aIndex >= ContactCountL()
|
|
146 |
*/
|
|
147 |
virtual MVPbkContactLink* CreateLinkLC(
|
|
148 |
TInt aIndex ) const = 0;
|
|
149 |
|
|
150 |
/**
|
|
151 |
* Returns The index of the aContactLink in this view.
|
|
152 |
*
|
|
153 |
* If the identifier is not found from the view then
|
|
154 |
* KErrNotFound is returned. If the view is not from
|
|
155 |
* any store (e.g. a folding view) then it will also
|
|
156 |
* return KErrNotFound.
|
|
157 |
*
|
|
158 |
* NOTE: the implementation of this function probably
|
|
159 |
* must loop the view which means that calling
|
|
160 |
* this function frequently or in a loop can
|
|
161 |
* be slow when there are lots of contacts.
|
|
162 |
*
|
|
163 |
* @param aContactLink A link whose index is searched for.
|
|
164 |
* @return The index of the link or KErrNotFound.
|
|
165 |
*/
|
|
166 |
virtual TInt IndexOfLinkL(
|
|
167 |
const MVPbkContactLink& aContactLink ) const = 0;
|
|
168 |
|
|
169 |
/**
|
|
170 |
* Adds an observer to this contact view asynchronously.
|
|
171 |
*
|
|
172 |
* The observer will be notified after it has been added
|
|
173 |
* to the view.
|
|
174 |
*
|
|
175 |
* @param aObserver A new observer for the view.
|
|
176 |
*/
|
|
177 |
virtual void AddObserverL(
|
|
178 |
MVPbkContactViewObserver& aObserver ) = 0;
|
|
179 |
|
|
180 |
/**
|
|
181 |
* Removes an observer from this contact view.
|
|
182 |
*
|
|
183 |
* This method can be called even if aObserver has not been
|
|
184 |
* previously added. In that case, no observers are removed.
|
|
185 |
*
|
|
186 |
* @param aObserver The observer to be removed.
|
|
187 |
*/
|
|
188 |
virtual void RemoveObserver(
|
|
189 |
MVPbkContactViewObserver& aObserver ) = 0;
|
|
190 |
|
|
191 |
/**
|
|
192 |
* Returns ETrue if this view is from a store identified
|
|
193 |
* by aContactStoreUri.
|
|
194 |
*
|
|
195 |
* @param aContactStoreUri The whole URI of the contact store.
|
|
196 |
* @return ETrue if the view was from the given store.
|
|
197 |
*
|
|
198 |
* @see TVPbkContactStoreUriPtr::UriDes
|
|
199 |
*/
|
|
200 |
virtual TBool MatchContactStore(
|
|
201 |
const TDesC& aContactStoreUri ) const = 0;
|
|
202 |
|
|
203 |
/**
|
|
204 |
* Returns ETrue if this view is from a store domain identified
|
|
205 |
* by aContactStoreDomain.
|
|
206 |
*
|
|
207 |
* @param aContactStoreDomain The domain part of the contact store URI.
|
|
208 |
* The domain can be retrieved from the
|
|
209 |
* whole contact store URI using class
|
|
210 |
* TVPbkContactStoreUriPtr and
|
|
211 |
* EContactStoreUriStoreType.
|
|
212 |
* An implementation compares the
|
|
213 |
* EContactStoreUriStoreType part of
|
|
214 |
* its own URI to aContactStoreDomain.
|
|
215 |
*
|
|
216 |
* @return ETrue if the view was from the same store domain.
|
|
217 |
* @see TVPbkContactStoreUriPtr
|
|
218 |
*/
|
|
219 |
virtual TBool MatchContactStoreDomain(
|
|
220 |
const TDesC& aContactStoreDomain ) const = 0;
|
|
221 |
|
|
222 |
/**
|
|
223 |
* Creates and returns a bookmark that points to the
|
|
224 |
* view contact at aIndex.
|
|
225 |
*
|
|
226 |
* @param aIndex An index of the contact in the view.
|
|
227 |
* @return A new bookmark to the view item.
|
|
228 |
* @precond aIndex >= 0
|
|
229 |
* VPbkError::Panic(VPbkError::EInvalidContactIndex)
|
|
230 |
* is raised if the precondition does not hold.
|
|
231 |
*/
|
|
232 |
virtual MVPbkContactBookmark* CreateBookmarkLC(
|
|
233 |
TInt aIndex ) const = 0;
|
|
234 |
|
|
235 |
/**
|
|
236 |
* Returns an index of the contact in the view.
|
|
237 |
*
|
|
238 |
* If the identifier is not found from the view then
|
|
239 |
* KErrNotFound is returned.
|
|
240 |
*
|
|
241 |
* NOTE: the implementation of this function probably
|
|
242 |
* must loop the view which means that calling
|
|
243 |
* this function frequently or in a loop can
|
|
244 |
* be slow when there are lots of contacts.
|
|
245 |
*
|
|
246 |
* @param aContactBookmark A bookmark that identifies
|
|
247 |
* a contact in the view.
|
|
248 |
* @return An index of the contact in the view or KErrNotFound.
|
|
249 |
*/
|
|
250 |
virtual TInt IndexOfBookmarkL(
|
|
251 |
const MVPbkContactBookmark& aContactBookmark ) const = 0;
|
|
252 |
|
|
253 |
/**
|
|
254 |
* Returns an interface for text based contact filtering support.
|
|
255 |
*
|
|
256 |
* If the view doesn't support filtering then this returns NULL.
|
|
257 |
* Filtering must be supported in all views created from a contact
|
|
258 |
* store. However, it's possible to implement a view that doesn't
|
|
259 |
* need a filtering support and therefore clients must always check
|
|
260 |
* the returned pointer.
|
|
261 |
*
|
|
262 |
* @return A filtering interface or NULL
|
|
263 |
*/
|
|
264 |
virtual MVPbkContactViewFiltering* ViewFiltering() = 0;
|
|
265 |
|
|
266 |
/**
|
|
267 |
* Returns an extension point for this interface or NULL.
|
|
268 |
*
|
|
269 |
* @param aExtensionUid no extensions defined currently.
|
|
270 |
* @return an extension point for this interface or NULL.
|
|
271 |
*/
|
|
272 |
virtual TAny* ContactViewBaseExtension(TUid /*aExtensionUid*/)
|
|
273 |
{ return NULL; }
|
|
274 |
};
|
|
275 |
|
|
276 |
|
|
277 |
#endif // MVPBKCONTACTVIEWBASE_H
|
|
278 |
|
|
279 |
// End of File
|