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:  Virtual Phonebook contact store interface.

    15 *

    16 */

    17 

    18 

    19 #ifndef MVPBKCONTACTSTORE_H

    20 #define MVPBKCONTACTSTORE_H

    21 

    22 // INCLUDES

    23 #include <e32def.h>

    24 #include <mvpbkobjecthierarchy.h>

    25 #include <mvpbkcontactoperationfactory.h>

    26 

    27 // FORWARD DECLARATIONS

    28 class CVPbkContactViewDefinition;

    29 class MVPbkContactStoreObserver;

    30 class MVPbkContactStoreProperties;

    31 class MVPbkStoreContact;

    32 class MVPbkContactGroup;

    33 class MVPbkContactView;

    34 class MVPbkContactLink;

    35 class MVPbkFieldTypeList;

    36 class MVPbkContactViewObserver;

    37 class MVPbkContactStoreInfo;

    38 class MVPbkSingleContactLinkOperationObserver;

    39 class MVPbkContactOperationBase;

    40 

    41 //Use this UID to access contact store extension 2. Used as a parameter to ContactStoreExtension() method.

    42 const TUid KMVPbkContactStoreExtension2Uid = { 2 };

    43 

    44 // CLASS DECLARATIONS

    45 

    46 /**

    47  * A contact store interface that is implemented by all contact stores.

    48  *

    49  * Using this interface clients can access a single contact store. Usually

    50  * it's more suitable to use CVPbkContactManager and MVPbkContactStoreList

    51  * for accessing stores because multiple stores can be handled at a same

    52  * time.

    53  *

    54  * The store is opened asynchronously and it must not be used before

    55  * notification has arrived. If client opens the store it must also

    56  * close the store after usage.

    57  *

    58  * The interface can be used for retriveing properties and information

    59  * of the store and also for creating a view, a new contact or a

    60  * new group (if supported).

    61  *

    62  */

    63 class MVPbkContactStore :

    64         public MVPbkObjectHierarchy,

    65         public MVPbkContactOperationFactory

    66     {

    67     public:  // Destructor

    68 

    69         /**

    70          * Clients don't destroy the stores directly because they don't

    71          * own them. The ownerships are managed by CVPbkContactManager.

    72          */

    73         virtual ~MVPbkContactStore() { }

    74 

    75     public:  // New functions

    76         /**

    77          * Returns fixed properties of this contact store.

    78          *

    79          * Fixed properties do not change when the store is open.

    80          * The store must be opened before retrieving the properties.

    81          *

    82          * @return Store properties.

    83          */

    84         virtual const MVPbkContactStoreProperties& StoreProperties() const = 0;

    85 

    86         /**

    87          * Opens this contact store asynchronously.

    88          *

    89          * Calls back the observer when the opening completes. Notice

    90          * that the same store instance can be opened by several observers.

    91          *

    92          * @param aObserver An observer for the store.

    93          * @exception KErrInUse If another asynchronous operation

    94          *            is already in progress.

    95          */

    96         virtual void OpenL(

    97                 MVPbkContactStoreObserver& aObserver ) = 0;

    98 

    99         /**

   100          * Replaces an existing store and opens it asynchronously.

   101          *

   102          * E.g. If the database is a file then this replaces the database if

   103          * it's not locked by other clients. If the store

   104          * implementation can not implment replacing then this behaves

   105          * like OpenL.

   106          *

   107          * If the store does not exist, it is created if possible.

   108          * Calls back the observer when the opening completes.

   109          *

   110          * @param aObserver An observer for the store.

   111          */

   112         virtual void ReplaceL(

   113                 MVPbkContactStoreObserver& aObserver ) = 0;

   114 

   115         /**

   116          * Closes this contact store from a single observer.

   117          *

   118          * This can be always called safely even if OpenL or ReplaceL

   119          * hasn't been called.

   120          * If the client calls OpenL it must also call this after usage,

   121          * The observer will no longer receive events from this store.

   122          * If there are other observers for the store then the store

   123          * will remain open for them.

   124          *

   125          * @param aObserver An observer that was given in OpenL or ReplaceL.

   126          */

   127         virtual void Close(

   128                 MVPbkContactStoreObserver& aObserver ) = 0;

   129 

   130         /**

   131          * Creates a new contact associated to this store.

   132          *

   133          * The contact can be edited and then it must be committed by

   134          * calling MVPbkStoreContact::CommitL for actually saving

   135          * it to the store.

   136          *

   137          * @return A new contact associated to this store. Caller takes

   138          *         ownership of the returned contact.

   139          * @see MVPbkStoreContact

   140          * @see MVPbkStoreContact::CommitL

   141          */

   142         virtual MVPbkStoreContact* CreateNewContactLC() = 0;

   143 

   144         /**

   145          * Creates a new contact group associated to this store.

   146          *

   147          * MVPbkContactStoreProperties::SupportsContactGroups must be

   148          * true if this is used.

   149          * The contact group might be saved to the store immeadiately

   150          * depending on the store implementation.

   151          * It is left open for editing. Use CommitL to commit

   152          * the creation of the group and its content.

   153          *

   154          * @return A new contact group associated to this store. Caller takes

   155          *         the ownership of the returned contact group.

   156          * @exception KErrNotSupported if the store doesn't support groups.

   157          *              Client should check store properties before

   158          *              calling this.

   159          * @see MVPbkContactStoreProperties

   160          * @see MVPbkContactGroup

   161          * @see MVPbkStoreContact

   162          * @see MVPbkStoreContact::CommitL

   163          */

   164         virtual MVPbkContactGroup* CreateNewContactGroupLC() = 0;

   165 

   166         /**

   167          * Creates a new contact view from the store asynchronously.

   168          *

   169          * Client gets the ownership of the view. The content of

   170          * the view depends on the CVPbkContactViewDefinition. The

   171          * client must wait the observer event before using the view.

   172          *

   173          * @param aViewDefinition Defines the properties of the new view.

   174          * @param aObserver An observer for the view events.

   175          * @param aSortOrder Field types that are used in the view contact

   176          *                   in the same order as in this list. Notice that

   177          *                   stores may not support all possible field types

   178          *                   in a view contact. The implementation

   179          *                   of the view contact must have as many fields as

   180          *                   the sort order. If the store doesn't support the

   181          *                   field type in a view contact then it sets empty

   182          *                   data to the field.

   183          * @return  A new contact view object. Caller takes ownership of the

   184          *          returned contact.

   185          * @see MVPbkContactView

   186          * @see CVPbkContactViewDefinition

   187          */

   188         virtual MVPbkContactView* CreateViewLC(

   189                 const CVPbkContactViewDefinition& aViewDefinition,

   190                 MVPbkContactViewObserver& aObserver,

   191                 const MVPbkFieldTypeList& aSortOrder ) = 0;

   192 

   193         /**

   194          * Returns contact groups contained in this store.

   195          *

   196          * MVPbkContactStoreProperties::SupportsContactGroups must be

   197          * true if this is used. Implementation should return an empty

   198          * link array and not NULL.

   199          *

   200          * @return Contact group identifiers contained in this store.

   201          */

   202         virtual MVPbkContactLinkArray* ContactGroupsLC() const = 0;

   203 

   204         /**

   205          * Returns a contact store information. Information can vary

   206          * runtime.

   207          *

   208          * @return Contact store information.

   209          */

   210         virtual const MVPbkContactStoreInfo& StoreInfo() const = 0;

   211 

   212         /**

   213          * This is part of Virtual Phonebook internal framefork and not

   214          * usable for clients. Clients use CVPbkContactManager

   215          * for creating links from a stream.

   216          *

   217          * Creates a link array from a stream. Stream contains the internals

   218          * of the contact link. Internals are the contact store implementation

   219          * specific part of the package format.

   220          *

   221          * NOTE: this must work wheter the OpenL has been called or not. This

   222          *       means that a link can not contain any data that would need

   223          *       an open store before internalizing.

   224          *

   225          * @param aStream A stream containing the link internals.

   226          * @return A new contact link.

   227          * @internal

   228          */

   229         virtual MVPbkContactLink* CreateLinkFromInternalsLC(

   230                 RReadStream& aStream ) const = 0;

   231 

   232         /**

   233          * Returns an extension point for this interface or NULL.

   234          *

   235          * @param aExtensionUid no extensions defined currently.

   236          * @return an extension point for this interface or NULL.

   237          */

   238         virtual TAny* ContactStoreExtension(TUid /*aExtensionUid*/)

   239                 { return NULL; }

   240 

   241     public: // From MVPbkObjectHierarchy

   242 

   243         MVPbkObjectHierarchy& ParentObject() const

   244             {

   245             return const_cast<MVPbkObjectHierarchy&>

   246                 ( static_cast<const MVPbkObjectHierarchy&>( *this ) );

   247             }

   248         MVPbkContactStore& ContactStore() const

   249             {

   250             return const_cast<MVPbkContactStore&>( *this );

   251             }

   252 

   253     };

   254 

   255 #endif // MVPBKCONTACTSTORE_H

   256 

   257 // End of File