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