1 /*

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

    15 *

    16 */

    17 	

    18 

    19 #ifndef M_NCD_QUERY_H

    20 #define M_NCD_QUERY_H

    21 

    22 #include <e32cmn.h>

    23 

    24 #include "catalogsbase.h"

    25 #include "ncdinterfaceids.h"

    26 #include "catalogsarray.h"

    27 

    28 class MNcdQueryItem;

    29     

    30 /**

    31  *  Describes a query.

    32  *

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

    34  *  operations, or as general callbacks. 

    35  *

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

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

    38  *

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

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

    41  *  items.

    42  *

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

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

    45  *  information query.

    46  *

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

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

    49  *  credit card information etc.

    50  *

    51  *  Example: 

    52  *

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

    54  *  queryitem: "Creditcard owner:"

    55  *  queryitem: "Creditcard expiration date:"

    56  *  queryitem: "Creditcard number:"

    57  *  

    58  *

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

    60  *  be prepared to handle them.

    61  *  

    62  *  Most operations use querys when user interaction is needed.

    63  *

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

    65  *

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

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

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

    69  *

    70  *  @see MNcdQueryItem

    71  *  @see MNcdOperation

    72  *  @see MNcdProviderObserver

    73  */

    74 class MNcdQuery : public virtual MCatalogsBase

    75     {

    76     

    77 public:

    78 

    79     /**

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

    81      *

    82      * 

    83      */

    84     enum { KInterfaceUid = ENcdQueryUid };

    85 

    86     /**

    87      * Query response states.

    88      *

    89      * 

    90      */

    91     enum TResponse

    92         {

    93         /** No response has been set. */

    94         ENoResponse,

    95 

    96         /** Query has been accepted. */

    97         EAccepted,

    98 

    99         /** Query has been rejected. */

   100         ERejected

   101         };

   102 

   103     /**

   104      * Query semantics

   105      */

   106     enum TSemantics

   107         {

   108         /** No specific semantics specified */

   109         ESemanticsNone,

   110 

   111         /** Unknown/unsupported semantics specified */

   112         ESemanticsUnknown,

   113 

   114         /** Information (just show) */

   115         ESemanticsInfoMessage,

   116         

   117         /** Error (just show) */

   118         ESemanticsErrorMessage,

   119 

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

   121         ESemanticsDisclaimer,

   122         

   123         /** Operator selection */

   124         ESemanticsOperatorQuery,

   125         

   126         /** Language selection */

   127         ESemanticsLanguageQuery,

   128         

   129         /** User registration */        

   130         ESemanticsRegistrationQuery,

   131         

   132         /** User authentication */

   133         ESemanticsAuthenticationQuery,

   134         

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

   136         ESemanticsReviewQuery,

   137 

   138         /** Payment method selection */

   139         ESemanticsPaymentMethodSelectionQuery,

   140         

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

   142         ESemanticsConfirmationQuery,

   143 

   144         /** Advertisement (just show) */

   145         ESemanticsAdvertisementMessage,

   146 

   147         /** Payment input fields */

   148         ESemanticsPaymentQuery

   149 

   150         };

   151 

   152     /**

   153      * Checks whether this query is optional.

   154      *

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

   156      */

   157     virtual TBool IsOptional() const = 0;

   158     

   159     /**

   160      * Semantics of the query.

   161      *

   162      * This can be used to act differently for semantically

   163      * different querys (disclaimer, information message etc).

   164      *

   165      * 

   166      * @return Semantics for the item.

   167      */

   168     virtual TSemantics Semantics() const = 0;

   169     

   170     /**

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

   172      * if available.

   173      *

   174      * 

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

   176      */

   177     virtual const TDesC& MessageTitle() const = 0;

   178     

   179     /**

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

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

   182      *

   183      * 

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

   185      */

   186     virtual const TDesC& MessageBody() const = 0;

   187     

   188     /**

   189      * Returns the query items.

   190      *

   191      * 

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

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

   194      * @exception Leave System wide error code.

   195      */

   196     virtual RCatalogsArray< MNcdQueryItem > QueryItemsL() = 0;

   197 

   198     /**

   199      * Sets the query response.

   200      *

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

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

   203      *

   204      * 

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

   206      *       accepted (response set to EAccepted).

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

   208      * @exception KErrNotReady Query cannot be accepted, there are

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

   210      */

   211     virtual void SetResponseL( TResponse aResponse ) = 0;

   212 

   213     /**

   214      * Gets the query response.

   215      *

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

   217      *         if not set).

   218      */

   219     virtual TResponse Response() = 0;

   220     

   221     /**

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

   223      *

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

   225      */

   226     virtual TBool IsSecureConnection() const = 0;

   227 

   228 protected:

   229 

   230     /**

   231     * Destructor.

   232     *

   233     * @see MCatalogsBase::~MCatalogsBase

   234     */

   235     virtual ~MNcdQuery() {}

   236 

   237     };

   238 	

   239 	

   240 #endif //  M_NCD_QUERY_H