--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ncdengine/inc/ncdquery.h Thu Dec 17 08:51:10 2009 +0200
@@ -0,0 +1,240 @@
+/*
+* 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