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 search transactions.

    15 *

    16 */

    17 

    18 #ifndef __CPENGSEARCHTRANSACTION2_H

    19 #define __CPENGSEARCHTRANSACTION2_H

    20 

    21 

    22 //  INCLUDES

    23 #include <E32Base.h>

    24 

    25 

    26 

    27 // FORWARD DECLARATIONS

    28 class CPEngNWSessionSlotID2;

    29 class CPEngSearchCriteria2;

    30 class CPEngSearchTransaction2Imp;

    31 class MPEngSearchTransactionObserver2;

    32 

    33 

    34 

    35 /**

    36  * Transaction API for performing network search.

    37  *

    38  * With this API clients search user ids from network

    39  * server. Supports using either single or multiple search

    40  * criterias. Also supports continuing the search

    41  * after getting partial results.

    42  *

    43  * Search operations are asynchronous network operations,

    44  * and their end results are signalled to given operation

    45  * observer.

    46  *

    47  * @lib PEngManager2.lib

    48  * @since 3.0

    49  */

    50 class CPEngSearchTransaction2 : public CBase

    51     {

    52 

    53         //-----------------------------------------------------------------------

    54     public: /* Construction */

    55 

    56         /**

    57          * Instantiates CPEngSearchTransaction2 object.

    58          *

    59          * Instantiates CPEngSearchTransaction2 object and connects

    60          * it to identified Presence Engine NWSessionSlot. NWSessionSlot

    61          * must be a valid, existing slot.

    62          *

    63          * Errors:

    64          *  - Requested NWSessionSlot not found: KErrNotFound

    65          *  - Given NWSessionSlotID malformed: KErrArgument

    66          *

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

    68          * session slot.

    69          * @param aPriority The priority for CPEngSearchTransaction2

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

    71          * asynchronously delivering events to observers.

    72          *

    73          * @return New CPEngSearchTransaction2 instance.

    74          */

    75         IMPORT_C static CPEngSearchTransaction2* NewL(

    76             const CPEngNWSessionSlotID2& aNWSessionSlotID,

    77             TInt aPriority = CActive::EPriorityStandard );

    78 

    79         IMPORT_C static CPEngSearchTransaction2* NewLC(

    80             const CPEngNWSessionSlotID2& aNWSessionSlotID,

    81             TInt aPriority = CActive::EPriorityStandard );

    82 

    83 

    84         /**

    85          * Destructor.

    86          * Virtual by CBase.

    87          */

    88         ~CPEngSearchTransaction2();

    89 

    90 

    91 

    92     private:

    93 

    94         CPEngSearchTransaction2();

    95 

    96 

    97 

    98         //-----------------------------------------------------------------------

    99     public: /* Network search transaction */

   100 

   101 

   102 

   103         /**

   104          * Tests is the search already active.

   105          *

   106          * @since 3.0

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

   108          */

   109         IMPORT_C TBool IsSearchFromNetworkActive() const;

   110 

   111 

   112         /**

   113          * Performs the network search.

   114          *

   115          * There can be just one active search operation at a time

   116          * per one CPEngSearchTransaction2 instance. However,

   117          * there can be simultaneously several search operations

   118          * going on within one NWSessionSlot with distinct

   119          * CPEngSearchTransaction2 objects.

   120          *

   121          * Takes ownership to passed search criteria(s). If method

   122          * returns error, the search criteria(s) ownership remains

   123          * on the client. In success sets the given model pointer to

   124          * NULL or resets the parameter criteria array.

   125          *

   126          * @since 3.0

   127          *

   128          * @param aCriteria The search criterias. If there are multiple

   129          * search criterias, logical AND operation is assumed between

   130          * the different criterias.

   131          * @param aSearchLimit Maximum number of search results that

   132          * can be received at a time.

   133          * @param aObserver The observer to notify from search events.

   134          *

   135          * @return Result from initiating search:

   136          *  - KErrNone if search succesfully initiated.

   137          *  - KErrInUse if search already on going from object.

   138          *  - KErrArgument if empty search criterias provided.

   139          *  - Else one of system wide error codes.

   140          */

   141         IMPORT_C TInt SearchFromNetwork(

   142             CPEngSearchCriteria2*& aCriteria,

   143             TInt aSearchLimit,

   144             MPEngSearchTransactionObserver2& aObserver );

   145 

   146 

   147         IMPORT_C TInt SearchFromNetwork(

   148             RPointerArray< CPEngSearchCriteria2 >& aCriterias,

   149             TInt aSearchLimit,

   150             MPEngSearchTransactionObserver2& aObserver );

   151 

   152         /**

   153          * Continues the current search from given continuation index.

   154          *

   155          * Search can be continued only after starting one

   156          * with SearchFromNetwork() and that has returned

   157          * some results to clients by notifying the given observer.

   158          *

   159          * When continuing, further events are raported back to

   160          * original observer given in SearchFromNetwork().

   161          *

   162          * @since 3.0

   163          * @return Result from continuing the search:

   164          *  - KErrNone if search succesfully continued.

   165          *  - KErrInUse if search already on going.

   166          *  - KErrNotFound if no current search to continue.

   167          *  - Else one of system wide error codes.

   168          */

   169         IMPORT_C TInt ContinueSearchFromNetwork( TInt aContinueIndex );

   170 

   171 

   172         /**

   173          * Stops the search.

   174          *

   175          * @since 3.0

   176          * @return Result from stopping the search.

   177          *  - KErrNone if search succesfully stopped.

   178          *  - KErrNotFound if no current search to stop.

   179          *  - Else one of system wide error codes.

   180          */

   181         IMPORT_C TInt StopSearchFromNetwork();

   182 

   183 

   184 

   185 

   186         //-----------------------------------------------------------------------

   187     private: /* Data */

   188 

   189 

   190         //OWN: Implementation

   191         CPEngSearchTransaction2Imp*     iImp;

   192 

   193 

   194     };

   195 

   196 #endif  //__CPENGSEARCHTRANSACTION2_H

   197 

   198 

   199 //End of file

   200 

   201 

   202 

   203