/*

* Copyright (c) 2006 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:  

*

*/

#ifndef M_NCD_QUERY_H

#define M_NCD_QUERY_H

#include <e32cmn.h>

#include "catalogsbase.h"

#include "ncdinterfaceids.h"

#include "catalogsarray.h"

class MNcdQueryItem;

/**

 *  Describes a query.

 *

 *  The Catalogs Engine may send queries to the client as part of specific

 *  operations, or as general callbacks. 

 *

 *  Querys consist of a message and query items. A query can have just a

 *  message or just a range of query items or both.

 *

 *  The query message can be for example a disclaimer or a plain iformation

 *  message. The query message is intented to be shown separate from the query

 *  items.

 *

 *  If the query demands some input from the user it will contain query items.

 *  A query item defines one element of a whole query e.g. credit card number in a purchase 

 *  information query.

 *

 *  Query objects can be used to query a wide variety of things from the

 *  client: disclaimers, user acceptance for web-connection usage,

 *  credit card information etc.

 *

 *  Example: 

 *

 *  message: "Please enter creditcard information to complete the purchase"

 *  queryitem: "Creditcard owner:"

 *  queryitem: "Creditcard expiration date:"

 *  queryitem: "Creditcard number:"

 *  

 *

 *  Querys can be sent from a server at any time so the client needs to

 *  be prepared to handle them.

 *  

 *  Most operations use querys when user interaction is needed.

 *

 *  @note Query objects don't do any validity checks for input data.

 *

 *  @note: Querys are simple objects that have no connection to Catalogs Engine

 *         of their own. The object that sent the query may need to be notified of

 *         the completion of the query (e.g. MNcdOperation::QueryCompleted).

 *

 *  @see MNcdQueryItem

 *  @see MNcdOperation

 *  @see MNcdProviderObserver

 */

class MNcdQuery : public virtual MCatalogsBase

    {

public:

    /**

     * Unique identifier for the interface, required for all MCatalogsBase interfaces.

     *

     * 

     */

    enum { KInterfaceUid = ENcdQueryUid };

    /**

     * Query response states.

     *

     * 

     */

    enum TResponse

        {

        /** No response has been set. */

        ENoResponse,

        /** Query has been accepted. */

        EAccepted,

        /** Query has been rejected. */

        ERejected

        };

    /**

     * Query semantics

     */

    enum TSemantics

        {

        /** No specific semantics specified */

        ESemanticsNone,

        /** Unknown/unsupported semantics specified */

        ESemanticsUnknown,

        /** Information (just show) */

        ESemanticsInfoMessage,

        /** Error (just show) */

        ESemanticsErrorMessage,

        /** Disclaimer (show, request user acceptance) */

        ESemanticsDisclaimer,

        /** Operator selection */

        ESemanticsOperatorQuery,

        /** Language selection */

        ESemanticsLanguageQuery,

        /** User registration */        

        ESemanticsRegistrationQuery,

        /** User authentication */

        ESemanticsAuthenticationQuery,

        /** Review query (e.g. a review score for an item) */

        ESemanticsReviewQuery,

        /** Payment method selection */

        ESemanticsPaymentMethodSelectionQuery,

        /** Confirmation query (yes/no) */

        ESemanticsConfirmationQuery,

        /** Advertisement (just show) */

        ESemanticsAdvertisementMessage,

        /** Payment input fields */

        ESemanticsPaymentQuery

        };

    /**

     * Checks whether this query is optional.

     *

     * @return ETrue if the query is optional, EFalse if it is mandatory.

     */

    virtual TBool IsOptional() const = 0;

    /**

     * Semantics of the query.

     *

     * This can be used to act differently for semantically

     * different querys (disclaimer, information message etc).

     *

     * 

     * @return Semantics for the item.

     */

    virtual TSemantics Semantics() const = 0;

    /**

     * Getter for query message title. Intented be shown with the message body

     * if available.

     *

     * 

     * @return Message text. KNullDesC() if no message title available.

     */

    virtual const TDesC& MessageTitle() const = 0;

    /**

     * Getter for query message body. If available, should always be shown

     * to the user e.g. as a separate dialog.

     *

     * 

     * @return Message text. KNullDesC() if no message body available.

     */

    virtual const TDesC& MessageBody() const = 0;

    /**

     * Returns the query items.

     *

     * 

     * @return Array of query item pointers. Counted, Release() must be called

     *         for each after use e.g. with a call to RCatalogsArray::ResetAndDestroy().

     * @exception Leave System wide error code.

     */

    virtual RCatalogsArray< MNcdQueryItem > QueryItemsL() = 0;

    /**

     * Sets the query response.

     *

     * Query response accepts or rejects the query as a whole (including all query

     * items). Query response must be set before the query is completed.

     *

     * 

     * @note All non-optional query items need to be set before the query can be

     *       accepted (response set to EAccepted).

     * @param aResponse Either MNcdQuery::EAccepted or MNcdQuery::ERejected

     * @exception KErrNotReady Query cannot be accepted, there are

     *            non-optional query items whose value has not been set.

     */

    virtual void SetResponseL( TResponse aResponse ) = 0;

    /**

     * Gets the query response.

     *

     * @return Query response, as set with SetResponseL() (or MNcdQuery::ENoResponse

     *         if not set).

     */

    virtual TResponse Response() = 0;

    /**

     * Checks whether the query response will be sent over a secure connection.

     *

     * @return ETrue if connection is secure, EFalse if not.

     */

    virtual TBool IsSecureConnection() const = 0;

protected:

    /**

    * Destructor.

    *

    * @see MCatalogsBase::~MCatalogsBase

    */

    virtual ~MNcdQuery() {}

    };

#endif //  M_NCD_QUERY_H