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:  

    15 :                

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef SCVPBKCONTACTVIEW_H

    22 #define SCVPBKCONTACTVIEW_H

    23 

    24 // INCLUDES

    25 #include <e32base.h>

    26 #include <MVPbkContactView.h>

    27 

    28 

    29 // CLASS DECLARATIONS

    30 

    31 /**

    32  * An interface for contact store views.

    33  *

    34  * The view contains contacts from a single contact store.

    35  * MVPbkObjectHierarchy interface can be used to navigate to the store.

    36  */

    37 class CVPbkContactViewStub : public CBase, 

    38         public MVPbkContactView

    39     {

    40     public:  // Destructor

    41         /**

    42          * Destructor.

    43          */

    44         ~CVPbkContactViewStub() { };

    45         

    46         CVPbkContactViewStub()  { };

    47    		

    48    		/**

    49          * Returns the parent object of this object. For the root of the 

    50          * hierarchy returns self.

    51          * @return The parent object.

    52          */

    53         MVPbkObjectHierarchy& ParentObject() const;

    54 

    55 

    56         /**

    57          * Returns type of this contact view.

    58          *

    59          * @return A contact view type.

    60          */

    61         TVPbkContactViewType Type() const ;

    62 

    63         /**

    64          * Changes sort order of the view asynchronously.

    65          *

    66          * Clients of this view will get an event via MVPbkContactViewObserver

    67          * interface when the order has been updated. The leaf view sends

    68          * a pair of events. First it sends ContactViewUnavailable and then

    69          * after the order has been changed ContactViewReady. However if

    70          * the view is of type EVPbkCompositeView the client doesn't necessary

    71          * receive ContactViewUnavailable at all because it might be that

    72          * there is always some subview ready in the composite.

    73          *

    74          * @param aSortOrder A new sort order for this view.

    75          * @exception KErrArgument Possible reasons: a client tries to change

    76          *                         a sort order of platform defined shared

    77          *                         view against the platform setting.

    78          * @see CVPbkSortOrder

    79          */

    80         void ChangeSortOrderL(

    81                 const MVPbkFieldTypeList& aSortOrder ) ;

    82 

    83         /**

    84          * Returns the current sort order of the view.

    85          *

    86          * The sort order is a sub set of master field types from

    87          * CVPbkContactManager.

    88          *

    89          * @return The sort order of the view.

    90          */

    91         const MVPbkFieldTypeList& SortOrder() const ;

    92 

    93         /**

    94          * Refreshes the view contents asynchronously.

    95          * 

    96          * All handles to this view's contacts are invalidated.

    97          * Clients of this view will get an event via MVPbkContactViewObserver

    98          * interface when the view has been refreshed.

    99          */

   100         void RefreshL() ;

   101         

   102         /**

   103          * Returns the number of contacts in this view.

   104          *

   105          * @return The number of contacts.

   106          */

   107         TInt ContactCountL() const ;

   108 

   109         /**

   110          * Returns a contact in this view. 

   111          *

   112          * The returned reference may be invalidated when this 

   113          * function is called again. For that reason clients should prefer

   114          * not to save references to the contacts retrieved from this function.

   115          *

   116          * @param aIndex An index of the contact in this view.

   117          * @return A reference to a contact in this view at aIndex.

   118          * @precond aIndex >

   119          *              VPbkError::Panic(VPbkError::EInvalidContactIndex)

   120          *              is raised if the precondition does not hold.

   121          * @exception KErrArgument if aIndex >= ContactCountL()

   122          */

   123         const MVPbkViewContact& ContactAtL(

   124                 TInt aIndex ) const ;

   125 

   126         /**

   127          * Creates and returns a link that points to contact at aIndex.

   128          *

   129          * NOTE: If the view contact is not from any store it can return

   130          *       also NULL. E.g. if the view contact is a folding 

   131          *       contact view that it's not saved to any store.

   132          *       The NULL is not pushed onto the cleanup stack.

   133          *

   134          * @param aIndex An index of the contact for which the link

   135          *               is created.

   136          * @return A new link object pointing to contact at aIndex or NULL if

   137          *          the link can't be created (e.g. a folder).

   138          * @precond aIndex >

   139          *          VPbkError::Panic(VPbkError::EInvalidContactIndex)

   140          *          is raised if the precondition does not hold.

   141          * @exception KErrArgument if aIndex >= ContactCountL()

   142          */

   143         MVPbkContactLink* CreateLinkLC(

   144                 TInt aIndex ) const ;

   145 

   146         /**

   147          * Returns The index of the aContactLink in this view.

   148          *

   149          * If the identifier is not found from the view then

   150          * KErrNotFound is returned. If the view is not from

   151          * any store (e.g. a folding view) then it will also

   152          * return KErrNotFound.

   153          *

   154          * NOTE: the implementation of this function probably

   155          *       must loop the view which means that calling

   156          *       this function frequently or in a loop can

   157          *       be slow when there are lots of contacts.

   158          *

   159          * @param aContactLink A link whose index is searched for.

   160          * @return The index of the link or KErrNotFound.

   161          */

   162         TInt IndexOfLinkL(

   163                 const MVPbkContactLink& aContactLink ) const ;

   164 

   165         /**

   166          * Adds an observer to this contact view asynchronously. 

   167          *

   168          * The observer will be notified after it has been added

   169          * to the view.

   170          *

   171          * @param aObserver A new observer for the view.

   172          */

   173         void AddObserverL(

   174                 MVPbkContactViewObserver& aObserver ) ;

   175 

   176         /**

   177          * Removes an observer from this contact view.

   178          *

   179          * This method can be called even if aObserver has not been

   180          * previously added. In that case, no observers are removed.

   181          *

   182          * @param aObserver The observer to be removed.

   183          */

   184         void RemoveObserver(

   185                 MVPbkContactViewObserver& aObserver ) ;

   186         

   187         /**

   188          * Returns ETrue if this view is from a store identified 

   189          * by aContactStoreUri.

   190          *

   191          * @param aContactStoreUri The whole URI of the contact store.

   192          * @return ETrue if the view was from the given store.

   193          *

   194          * @see TVPbkContactStoreUriPtr::UriDes

   195          */

   196         TBool MatchContactStore(

   197                 const TDesC& aContactStoreUri ) const ;

   198         

   199         /**

   200          * Returns ETrue if this view is from a store domain identified 

   201          * by aContactStoreDomain.

   202          *

   203          * @param aContactStoreDomain The domain part of the contact store URI.

   204          *                            The domain can be retrieved from the 

   205          *                            whole contact store URI using class 

   206          *                            TVPbkContactStoreUriPtr and 

   207          *                            EContactStoreUriStoreType.

   208          *                            An implementation compares the

   209          *                            EContactStoreUriStoreType part of 

   210          *                            its own URI to aContactStoreDomain.

   211          *                            

   212          * @return ETrue if the view was from the same store domain.

   213          * @see TVPbkContactStoreUriPtr

   214          */

   215         TBool MatchContactStoreDomain(

   216                 const TDesC& aContactStoreDomain ) const ;

   217         

   218         /**

   219          * Creates and returns a bookmark that points to the

   220          * view contact at aIndex.

   221          *

   222          * @param aIndex An index of the contact in the view.

   223          * @return A new bookmark to the view item.

   224          * @precond aIndex >

   225          *          VPbkError::Panic(VPbkError::EInvalidContactIndex)

   226          *          is raised if the precondition does not hold.

   227          */

   228         MVPbkContactBookmark* CreateBookmarkLC(

   229                 TInt aIndex ) const ;

   230 

   231         /**

   232          * Returns an index of the contact in the view.

   233          *

   234          * If the identifier is not found from the view then

   235          * KErrNotFound is returned.

   236          *

   237          * NOTE: the implementation of this function probably

   238          *       must loop the view which means that calling

   239          *       this function frequently or in a loop can

   240          *       be slow when there are lots of contacts.

   241          *

   242          * @param aContactBookmark A bookmark that identifies

   243          *                         a contact in the view.

   244          * @return An index of the contact in the view or KErrNotFound.

   245          */

   246         TInt IndexOfBookmarkL(

   247                 const MVPbkContactBookmark& aContactBookmark ) const ;

   248         

   249         /**

   250          * Returns an interface for text based contact filtering support.

   251          *

   252          * If the view doesn't support filtering then this returns NULL. 

   253          * Filtering must be supported in all views created from a contact

   254          * store. However, it's possible to implement a view that doesn't

   255          * need a filtering support and therefore clients must always check

   256          * the returned pointer.

   257          *

   258          * @return A filtering interface or NULL

   259          */

   260         MVPbkContactViewFiltering* ViewFiltering() ;

   261         

   262         

   263         

   264     };

   265 

   266 #endif // SCVPBKCONTACTVIEW_H

   267 

   268 //End of file