/*
* Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Presence search transactions.
*
*/

#ifndef __CPENGSEARCHTRANSACTION2_H
#define __CPENGSEARCHTRANSACTION2_H


//  INCLUDES
#include <E32Base.h>



// FORWARD DECLARATIONS
class CPEngNWSessionSlotID2;
class CPEngSearchCriteria2;
class CPEngSearchTransaction2Imp;
class MPEngSearchTransactionObserver2;



/**
 * Transaction API for performing network search.
 *
 * With this API clients search user ids from network
 * server. Supports using either single or multiple search
 * criterias. Also supports continuing the search
 * after getting partial results.
 *
 * Search operations are asynchronous network operations,
 * and their end results are signalled to given operation
 * observer.
 *
 * @lib PEngManager2.lib
 * @since 3.0
 */
class CPEngSearchTransaction2 : public CBase
    {

        //-----------------------------------------------------------------------
    public: /* Construction */

        /**
         * Instantiates CPEngSearchTransaction2 object.
         *
         * Instantiates CPEngSearchTransaction2 object and connects
         * it to identified Presence Engine NWSessionSlot. NWSessionSlot
         * must be a valid, existing slot.
         *
         * Errors:
         *  - Requested NWSessionSlot not found: KErrNotFound
         *  - Given NWSessionSlotID malformed: KErrArgument
         *
         * @param aNWSessionSlotID The session slot ID to identify the
         * session slot.
         * @param aPriority The priority for CPEngSearchTransaction2
         * client side active objects. These active objects are used when
         * asynchronously delivering events to observers.
         *
         * @return New CPEngSearchTransaction2 instance.
         */
        IMPORT_C static CPEngSearchTransaction2* NewL(
            const CPEngNWSessionSlotID2& aNWSessionSlotID,
            TInt aPriority = CActive::EPriorityStandard );

        IMPORT_C static CPEngSearchTransaction2* NewLC(
            const CPEngNWSessionSlotID2& aNWSessionSlotID,
            TInt aPriority = CActive::EPriorityStandard );


        /**
         * Destructor.
         * Virtual by CBase.
         */
        ~CPEngSearchTransaction2();



    private:

        CPEngSearchTransaction2();



        //-----------------------------------------------------------------------
    public: /* Network search transaction */



        /**
         * Tests is the search already active.
         *
         * @since 3.0
         * @return ETrue if operation is active. Else EFalse.
         */
        IMPORT_C TBool IsSearchFromNetworkActive() const;


        /**
         * Performs the network search.
         *
         * There can be just one active search operation at a time
         * per one CPEngSearchTransaction2 instance. However,
         * there can be simultaneously several search operations
         * going on within one NWSessionSlot with distinct
         * CPEngSearchTransaction2 objects.
         *
         * Takes ownership to passed search criteria(s). If method
         * returns error, the search criteria(s) ownership remains
         * on the client. In success sets the given model pointer to
         * NULL or resets the parameter criteria array.
         *
         * @since 3.0
         *
         * @param aCriteria The search criterias. If there are multiple
         * search criterias, logical AND operation is assumed between
         * the different criterias.
         * @param aSearchLimit Maximum number of search results that
         * can be received at a time.
         * @param aObserver The observer to notify from search events.
         *
         * @return Result from initiating search:
         *  - KErrNone if search succesfully initiated.
         *  - KErrInUse if search already on going from object.
         *  - KErrArgument if empty search criterias provided.
         *  - Else one of system wide error codes.
         */
        IMPORT_C TInt SearchFromNetwork(
            CPEngSearchCriteria2*& aCriteria,
            TInt aSearchLimit,
            MPEngSearchTransactionObserver2& aObserver );


        IMPORT_C TInt SearchFromNetwork(
            RPointerArray< CPEngSearchCriteria2 >& aCriterias,
            TInt aSearchLimit,
            MPEngSearchTransactionObserver2& aObserver );

        /**
         * Continues the current search from given continuation index.
         *
         * Search can be continued only after starting one
         * with SearchFromNetwork() and that has returned
         * some results to clients by notifying the given observer.
         *
         * When continuing, further events are raported back to
         * original observer given in SearchFromNetwork().
         *
         * @since 3.0
         * @return Result from continuing the search:
         *  - KErrNone if search succesfully continued.
         *  - KErrInUse if search already on going.
         *  - KErrNotFound if no current search to continue.
         *  - Else one of system wide error codes.
         */
        IMPORT_C TInt ContinueSearchFromNetwork( TInt aContinueIndex );


        /**
         * Stops the search.
         *
         * @since 3.0
         * @return Result from stopping the search.
         *  - KErrNone if search succesfully stopped.
         *  - KErrNotFound if no current search to stop.
         *  - Else one of system wide error codes.
         */
        IMPORT_C TInt StopSearchFromNetwork();




        //-----------------------------------------------------------------------
    private: /* Data */


        //OWN: Implementation
        CPEngSearchTransaction2Imp*     iImp;


    };

#endif  //__CPENGSEARCHTRANSACTION2_H


//End of file