1 // Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // XPath evaluator declaration

    15 //

    16 

    17 

    18 

    19 /**

    20  @file

    21  @publishedAll

    22  @released

    23 */

    24 #ifndef XMLENGXPATHEVALUATOR_H

    25 #define XMLENGXPATHEVALUATOR_H

    26 

    27 #include <xml/dom/xmlengxpathexpression.h>

    28 #include <xml/dom/xmlengxformsinstancemap.h>

    29 #include <xml/dom/xmlengnamespaceresolver.h>

    30 

    31 class MXmlEngXPathExtensionFunction;

    32 

    33 class MXmlEngNamespaceResolver;

    34 /**

    35 Evaluates XPath expressions on a DOM tree.

    36 

    37 See the XPath specfication here:

    38 http://www.w3.org/TR/2004/NOTE-DOM-Level-3-XPath-20040226/xpath.html

    39 */

    40 class TXmlEngXPathEvaluator

    41 {

    42 public:

    43     /** Default constructor */

    44     IMPORT_C TXmlEngXPathEvaluator();

    45 

    46 	// XPath 1.0 methods

    47 	

    48     /**

    49     Precompiles and stores an XPath expression, which is returned to caller.

    50 

    51 	Information on how to write XPath expressions can be found here:

    52 	@see http://en.wikipedia.org/wiki/XPath

    53 		 

    54     @param aExpression The expression to create

    55     @param aResolver Not supported in current API.  Reserved for future use.

    56     @return The compiled XPath expression.

    57 	@leave KXmlEngErrXPathSyntax Error compiling expression

    58 	@leave KErrNoMemory Memory allocation error

    59 	@leave - Otherwise, any of the system wide errors.

    60     */

    61     IMPORT_C RXmlEngXPathExpression CreateExpressionL(const TDesC8& aExpression,

    62                                    const MXmlEngNamespaceResolver* aResolver = NULL);

    63 

    64     /**

    65     Evaluates the XPath expression given as a parameter and returns the result.

    66     

    67     @param aExpression The expression to evaluate

    68     @param aContextNode The node relative to which the expression is evaluated. 

    69     @param aResolver Not supported in current API. Reserved for future use.

    70     @return The result of the evaluation.

    71     @leave KXmlEngErrXPathResult Error evaluating expression

    72 	@leave KXmlEngErrXPathSyntax Error compiling expression

    73 	@leave KErrNoMemory Memory allocation error

    74 	@leave - Otherwise, any of the system wide errors.

    75     */

    76     IMPORT_C RXmlEngXPathResult EvaluateL(const TDesC8& aExpression,

    77                                    const TXmlEngNode aContextNode,

    78                                    const MXmlEngNamespaceResolver* aResolver = NULL);

    79 

    80 

    81 	// Extensions to XPath 1.0

    82 

    83 	/**

    84 	Does the same thing as EvaluateL(), but also calculates the dependency list

    85 	of the expression.

    86     

    87     @param aExpression The expression to evaluate

    88     @param aContextNode The node relative to which the expression is evaluated. 

    89     @param aResolver Not supported in current API. Reserved for future use.

    90     @param aDependents After the method has returned, contains set of nodes that 

    91     the expression is dependent on.

    92     @return The result of evaluation

    93 

    94 	@leave KXmlEngErrXPathResult Error evaluating expression

    95 	@leave KXmlEngErrXPathSyntax Error compiling expression

    96 	@leave KErrNoMemory Memory allocation error

    97 	@leave - Otherwise, any of the system wide errors.

    98     */

    99     IMPORT_C RXmlEngXPathResult EvaluateWithDependenciesL(const TDesC8& aExpression,

   100                                    const TXmlEngNode aContextNode,

   101                                    const MXmlEngNamespaceResolver* aResolver,

   102                                    RXmlEngNodeSet& aDependents);

   103 

   104     /**

   105     Registers the instance map to be used when evaluating form expressions. The map 

   106     contains DOM Documents and their names. For example, when evaluating the expression 

   107     "instance('a')" the evaluator looks up a document that has the name "a" from the map. 

   108 

   109     @param aInstanceTrees The instance map, ownership is not transferred.

   110     */

   111     IMPORT_C void SetInstanceMap(CXmlEngXFormsInstanceMap* aInstanceTrees);

   112 

   113     /**

   114     Returns the registered instance map.  Ownership is not transferred.

   115     @return A pointer to the instance map or NULL if not registered.

   116     */

   117     IMPORT_C CXmlEngXFormsInstanceMap* InstanceMap();

   118 

   119 private:

   120     CXmlEngXFormsInstanceMap* iInstanceTrees;

   121 };

   122 

   123 

   124 

   125 #endif /* XMLENGXPATHEVALUATOR_H */

   126