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:  Presence attribute transactions.

    15 *

    16 */

    17 

    18 #ifndef __CPENGATTRIBUTETRANSACTION2_H

    19 #define __CPENGATTRIBUTETRANSACTION2_H

    20 

    21 //  INCLUDES

    22 #include <E32Base.h>

    23 #include <BamDescA.h>

    24 

    25 

    26 // FORWARD DECLARATIONS

    27 class CPEngAttributeTransaction2Imp;

    28 class CPEngNWSessionSlotID2;

    29 class MPEngAttributeTransactionObserver2;

    30 class MPEngPresenceAttrModel2;

    31 

    32 

    33 

    34 // CLASS DECLARATION

    35 

    36 /**

    37  * Transaction API for presence attributes.

    38  *

    39  * With this API clients can:

    40  *

    41  *   1. Publish user own presence attributes to network.

    42  *   2. Fetch presence attributes from network.

    43  *

    44  * Attribute publish and attribute fetch are asynchronous

    45  * network operations, and their end results are signalled

    46  * to given operation observer.

    47  *

    48  * @lib PEngManager2.lib

    49  * @since 3.0

    50  */

    51 class CPEngAttributeTransaction2 : public CBase

    52     {

    53 

    54         //-----------------------------------------------------------------------

    55     public: /* Construction */

    56 

    57         /**

    58          * Instantiates CPEngAttributeTransaction2 object.

    59          *

    60          * Instantiates CPEngAttributeTransaction2 object and connects

    61          * it to identified Presence Engine NWSessionSlot. NWSessionSlot

    62          * must be a valid, existing slot.

    63          *

    64          * Errors:

    65          *  - Requested NWSessionSlot not found: KErrNotFound

    66          *  - Given NWSessionSlotID malformed: KErrArgument

    67          *

    68          * @param aNWSessionSlotID The session slot ID to identify the

    69          * session slot.

    70          * @param aPriority The priority for CPEngAttributeTransaction2

    71          * client side active objects. These active objects are used when

    72          * asynchronously delivering events to observers.

    73          *

    74          * @return New CPEngAttributeTransaction2 instance.

    75          */

    76         IMPORT_C static CPEngAttributeTransaction2* NewL(

    77             const CPEngNWSessionSlotID2& aNWSessionSlotID,

    78             TInt aPriority = CActive::EPriorityStandard );

    79 

    80         IMPORT_C static CPEngAttributeTransaction2* NewLC(

    81             const CPEngNWSessionSlotID2& aNWSessionSlotID,

    82             TInt aPriority = CActive::EPriorityStandard );

    83 

    84 

    85         /**

    86          * Destructor.

    87          * Virtual by CBase.

    88          */

    89         ~CPEngAttributeTransaction2();

    90 

    91 

    92 

    93     private:

    94 

    95         CPEngAttributeTransaction2();

    96 

    97 

    98 

    99 

   100         //-----------------------------------------------------------------------

   101     public: /* User own attribute publish */

   102 

   103 

   104         /**

   105          * Tests is the publish already active.

   106          *

   107          * @since 3.0

   108          * @return ETrue if operation is active. Else EFalse.

   109          */

   110         IMPORT_C TBool IsPublishOwnAttributesActive() const;

   111 

   112 

   113 

   114         /**

   115          * Publishes the user own attribute to the network server.

   116          *

   117          * Published attribute is kept locked untill the publish

   118          * operation completes (either succesfully or with failure).

   119          *

   120          * There can be just one active publish operation at a time

   121          * per one CPEngAttributeTransaction2 instance. However,

   122          * there can be simultaneously several publish operations

   123          * going on within one NWSessionSlot with distinct

   124          * CPEngAttributeTransaction2 objects and distinct attribute sets.

   125          *

   126          * Takes ownership to passed model(s). If method returns error,

   127          * the model(s) ownership remains on the client. In success sets

   128          * the given model pointer to NULL or resets the parameter model

   129          * array.

   130          *

   131          * Passed models must be loaded from same NWSessionSlot as

   132          * CPEngAttributeTransaction2 is connected and attribute

   133          * models must be locked for edit/publish.

   134          *

   135          * @since 3.0

   136          * @param aModel The attribute model to publish.

   137          * @param aObserver The observer to notify from attribute

   138          * publish events.

   139          *

   140          * @return Result from initiating attribute publish:

   141          *  - KErrNone if attribute publish succesfully initiated.

   142          *  - KErrInUse if attribute publish already on going from object.

   143          *  - KErrArgument if attributes either loaded from another

   144          *    NWSessionSlot or they are not locked for edit.

   145          *  - Else one of system wide error codes.

   146          */

   147         IMPORT_C TInt PublishAndUnLockOwnAttribute(

   148             MPEngPresenceAttrModel2*& aModel,

   149             MPEngAttributeTransactionObserver2& aObserver );

   150 

   151 

   152         IMPORT_C TInt PublishAndUnLockOwnAttributes(

   153             RPointerArray<MPEngPresenceAttrModel2>& aModels,

   154             MPEngAttributeTransactionObserver2& aObserver );

   155 

   156 

   157 

   158         /**

   159          * Cancels the user attribute publish.

   160          *

   161          * @since 3.0

   162          */

   163         IMPORT_C void CancelPublishOwnAttributes();

   164 

   165 

   166 

   167 

   168 

   169         //-----------------------------------------------------------------------

   170     public: /* Presence attribute fetch from network */

   171 

   172         /**

   173          * Tests is the fetch already active.

   174          *

   175          * @since 3.0

   176          * @return ETrue if operation is active. Else EFalse.

   177          */

   178         IMPORT_C TBool IsFetchAttributesActive() const;

   179 

   180 

   181         /**

   182          * Fetches presence attributes from network server.

   183          *

   184          * Fetches presence attributes from the network

   185          * and stores fetched attributes to presence cache.

   186          * (Fetched presence attributes can be retrieved e.g. with

   187          * CPEngAttributeStore2::GetCachedAttributeL().)

   188          *

   189          * There can be just one active fetch operation at a time

   190          * per one CPEngAttributePublisher instance. However, within

   191          * one NWSessionSlot there can be several active fetch

   192          * operations going on.

   193          *

   194          * @since 3.0

   195          * @param aPresenceID The user to fetch.

   196          * @param aType The attribute type. Presence Engine known

   197          *        attribute types are listed in PEngWVPresenceAttributes2.h.

   198          * @param aObserver The observer to notify from attribute fetch events.

   199          * @param aOptions Reserved for future fetch options.

   200          *

   201          * @return Result from initiating attribute fetch:

   202          *  - KErrNone if attribute fetch succesfully initiated.

   203          *  - KErrInUse if attribute fetch already on going from object.

   204          *  - KErrNotSupported if requestSed attribute type isn't supported.

   205          *  - Else one of system wide error codes.

   206          */

   207         IMPORT_C TInt FetchAttributesToCache(

   208             const TDesC& aPresenceID,

   209             const TArray<TUint32>& aTypes,

   210             MPEngAttributeTransactionObserver2& aObserver,

   211             TInt aOptions = 0 );

   212 

   213         IMPORT_C TInt FetchAttributesToCache(

   214             const MDesCArray& aPresenceIDs,

   215             const TArray<TUint32>& aTypes,

   216             MPEngAttributeTransactionObserver2& aObserver,

   217             TInt aOptions = 0 );

   218 

   219 

   220         /**

   221          * Fetches presence attributes from network server.

   222          *

   223          * Fetches presence attributes from the network

   224          * and returns them to client as local objects.

   225          * Client can ask the fetched presence attributes

   226          * after succesfull fetch from

   227          * CPEngAttributeTransaction2::GetFetchedAttributes().)

   228          *

   229          * There can be just one active fetch operation at a time

   230          * per one CPEngAttributePublisher instance. However, within

   231          * one NWSessionSlot there can be several active fetch

   232          * operations going on.

   233          *

   234          * @since 3.0

   235          * @param aPresenceID The user to fetch.

   236          * @param aType The attribute type. Presence Engine known

   237          *        attribute types are listed in PEngWVPresenceAttributes2.h.

   238          * @param aObserver The observer to notify from attribute fetch events.

   239          * @return Result from initiating attribute fetch:

   240          *  - KErrNone if attribute fetch succesfully initiated.

   241          *  - KErrInUse if attribute fetch already on going from object.

   242          *  - KErrNotSupported if requestSed attribute type isn't supported.

   243          *  - Else one of system wide error codes.

   244          */

   245         IMPORT_C TInt FetchAttributesToObjects(

   246             const TDesC& aPresenceID,

   247             const TArray<TUint32>& aTypes,

   248             MPEngAttributeTransactionObserver2& aObserver );

   249 

   250 

   251         /**

   252          * Cancels the presence attribute fetch.

   253          *

   254          * @since 3.0

   255          */

   256         IMPORT_C void CancelFetchAttributes();

   257 

   258 

   259 

   260         //-----------------------------------------------------------------------

   261     public: /* Object get for observer callbacks */

   262 

   263 

   264         /**

   265          * Gets the fetched attribute objects produced by the last

   266          * FetchAttributesToObjects(). Ownership of attribute models is

   267          * returned to caller. Returned models can be only read.

   268          *

   269          * Fetched attributes can be asked only during the observer callback:

   270          * MPEngAttributeTransactionObserver2::HandleAttributeTransactionCompleteL().

   271          * After retrieving the models, client owns the attribute objects and

   272          * can freely control their lifetime.

   273          *

   274          * @since 3.0

   275          * @param aModel Returns retrieved attribute model(s).

   276          *        Retrieved attribute models are appended to the end of array.

   277          *        If array has existing attribute objects, those are not touched.

   278          *        If get fails with resource error, so far succesfully

   279          *        moved attributes are returned.

   280          *

   281          * @return Status code from attribute getting:

   282          *        - KErrNone if get succeeds.

   283          *        - KErrNotReady if no fetch results available

   284          *        - Else one of system wide error codes.

   285          */

   286         IMPORT_C TInt GetFetchedAttributes(

   287             RPointerArray< MPEngPresenceAttrModel2 >& aModels );

   288 

   289 

   290 

   291 

   292         //-----------------------------------------------------------------------

   293     private: /* Data */

   294 

   295 

   296         //OWN: Implementation

   297         CPEngAttributeTransaction2Imp*     iImp;

   298 

   299 

   300     };

   301 

   302 #endif // __CPENGATTRIBUTETRANSACTION2_H

   303 

   304 //End of file

   305 

   306 

   307 

   308 

   309 

   310 

   311