# api

## Classes
struct | axiom_xpath_expression
struct | axiom_xpath_context
struct | axiom_xpath_result
struct | axiom_xpath_result_node
## Defines
#define | AXIOM_XPATH_DEBUG
#define | AXIOM_XPATH_EVALUATION_ERROR 0
#define | AXIOM_XPATH_ERROR_STREAMING_NOT_SUPPORTED 10
## Typedefs
typedef struct axiom_xpath_expression | axiom_xpath_expression_t
typedef struct axiom_xpath_context | axiom_xpath_context_t
typedef struct axiom_xpath_result | axiom_xpath_result_t
typedef struct axiom_xpath_result_node | axiom_xpath_result_node_t
typedef int(* | axiom_xpath_function_t )(axiom_xpath_context_t *context, int np)
## Enumerations
enum | axiom_xpath_result_type_t { AXIOM_XPATH_TYPE_NODE = 0, AXIOM_XPATH_TYPE_ATTRIBUTE, AXIOM_XPATH_TYPE_NAMESPACE, AXIOM_XPATH_TYPE_TEXT, AXIOM_XPATH_TYPE_NUMBER, AXIOM_XPATH_TYPE_BOOLEAN }
## Functions
AXIS2_EXTERN axiom_xpath_expression_t * | axiom_xpath_compile_expression (const axutil_env_t *env, const axis2_char_t *xpath_expr)
AXIS2_EXTERN axiom_xpath_context_t * | axiom_xpath_context_create (const axutil_env_t *env, axiom_node_t *root_node)
AXIS2_EXTERN axiom_xpath_result_t * | axiom_xpath_evaluate (axiom_xpath_context_t *context, axiom_xpath_expression_t *xpath_expr)
AXIS2_EXTERN axis2_bool_t | axiom_xpath_cast_node_to_boolean (const axutil_env_t *env, axiom_xpath_result_node_t *node)
AXIS2_EXTERN double | axiom_xpath_cast_node_to_number (const axutil_env_t *env, axiom_xpath_result_node_t *node)
AXIS2_EXTERN axis2_char_t * | axiom_xpath_cast_node_to_string (const axutil_env_t *env, axiom_xpath_result_node_t *node)
AXIS2_EXTERN axiom_node_t * | axiom_xpath_cast_node_to_axiom_node (const axutil_env_t *env, axiom_xpath_result_node_t *node)
AXIS2_EXTERN void | axiom_xpath_free_context (const axutil_env_t *env, axiom_xpath_context_t *context)
AXIS2_EXTERN void | axiom_xpath_free_expression (const axutil_env_t *env, axiom_xpath_expression_t *xpath_expr)
AXIS2_EXTERN void | axiom_xpath_free_result (const axutil_env_t *env, axiom_xpath_result_t *result)
AXIS2_EXTERN void | axiom_xpath_register_namespace (axiom_xpath_context_t *context, axiom_namespace_t *ns)
AXIS2_EXTERN axiom_namespace_t * | axiom_xpath_get_namespace (axiom_xpath_context_t *context, axis2_char_t *prefix)
AXIS2_EXTERN void | axiom_xpath_clear_namespaces (axiom_xpath_context_t *context)
AXIS2_EXTERN axiom_xpath_result_t * | axiom_xpath_evaluate_streaming (axiom_xpath_context_t *context, axiom_xpath_expression_t *xpath_expr)
AXIS2_EXTERN axis2_bool_t | axiom_xpath_streaming_check (const axutil_env_t *env, axiom_xpath_expression_t *expr)
AXIS2_EXTERN void | axiom_xpath_register_default_functions_set (axiom_xpath_context_t *context)
AXIS2_EXTERN void | axiom_xpath_register_function (axiom_xpath_context_t *context, axis2_char_t *name, axiom_xpath_function_t func)
AXIS2_EXTERN axiom_xpath_function_t | axiom_xpath_get_function (axiom_xpath_context_t *context, axis2_char_t *name)

## Define Documentation

#define AXIOM_XPATH_DEBUG

Enable tracing

#define AXIOM_XPATH_EVALUATION_ERROR 0

An error occured while evaluating the xpath expression

## Typedef Documentation

typedef struct axiom_xpath_context axiom_xpath_context_t

The XPath context Keeps a reference to the context node or attribute, XPath expression, environment and result set.

typedef struct axiom_xpath_expression axiom_xpath_expression_t

XPath expression It includes the expression as a string and parsed data.

typedef struct axiom_xpath_result_node axiom_xpath_result_node_t

XPath result Stores type and value of the result.

typedef struct axiom_xpath_result axiom_xpath_result_t

XPath result set Contains the result set and other information such as whether the expression was evaluated successfully.

## Enumeration Type Documentation

enum axiom_xpath_result_type_t

XPath result types

## Function Documentation

AXIS2_EXTERN axiom_node_t* axiom_xpath_cast_node_to_axiom_node | ( | const axutil_env_t * | env,
|  | axiom_xpath_result_node_t * | node |
| ) |  |  |

Convert an XPath result to an axiom node. If the result is an axiom node it is returned and NULL otherwise.

Parameters:

  | env | Environment must not be null
  | node | A pointer to the XPath result

Returns:
  The axiom node.

AXIS2_EXTERN axis2_bool_t axiom_xpath_cast_node_to_boolean | ( | const axutil_env_t * | env,
|  | axiom_xpath_result_node_t * | node |
| ) |  |  |

Convert an XPath result to a boolean. If the result is a boolean the value of it is returned. If the result is a number, AXIS2_TRUE is returned if the value is not equal to 0 and AXIS2_FALSE otherwise. Otherwise AXIS2_TRUE is returned if the result is not NULL and AXIS2_FALSE otherwise.

Parameters:

  | env | Environment must not be null
  | node | A pointer to the XPath result

Returns:
  The boolean value.

AXIS2_EXTERN double axiom_xpath_cast_node_to_number | ( | const axutil_env_t * | env,
|  | axiom_xpath_result_node_t * | node |
| ) |  |  |

Convert an XPath result to a number. If the result is a boolean, 1 is returned if it's true and 0 otherwise. If the result is a number the value of it is returned. Otherwise AXIS2_TRUE is returned if the result is not NULL and AXIS2_FALSE otherwise.

Parameters:

  | env | Environment must not be null
  | node | A pointer to the XPath result

Returns:
  The numerical value.

AXIS2_EXTERN axis2_char_t* axiom_xpath_cast_node_to_string | ( | const axutil_env_t * | env,
|  | axiom_xpath_result_node_t * | node |
| ) |  |  |

Convert an XPath result to text. If the result is a boolean, "true" is returned if it's true and "false" otherwise. If the result is a number the text representation of it is returned. If the result is a text the value of it is returned. If the result is an axiom node, the text value of it is returned If the result is an axiom attribue, the text value of it is returned

Parameters:

  | env | Environment must not be null
  | node | A pointer to the XPath result

Returns:
  The text value.

AXIS2_EXTERN void axiom_xpath_clear_namespaces | ( | axiom_xpath_context_t * | context | ) |

Clears all registered XPath namespaces

Parameters:

  | context | XPath Context, must not be null

AXIS2_EXTERN axiom_xpath_expression_t* axiom_xpath_compile_expression | ( | const axutil_env_t * | env,
|  | const axis2_char_t * | xpath_expr |
| ) |  |  |

Compile an XPath expression

Parameters:

  | env | Environment must not be null
  | xpath_expr | A pointer to the XPath expression

Returns:
  The parsed XPath expression. Returns NULL if an error occured while parsing.

AXIS2_EXTERN axiom_xpath_context_t* axiom_xpath_context_create | ( | const axutil_env_t * | env,
|  | axiom_node_t * | root_node |
| ) |  |  |

Create an empty XPath context

Parameters:

  | env | Environment must not be null
  | root_node | A pointer to the root of the tree

Returns:
  The initialized XPath context.

AXIS2_EXTERN axiom_xpath_result_t* axiom_xpath_evaluate | ( | axiom_xpath_context_t * | context,
|  | axiom_xpath_expression_t * | xpath_expr |
| ) |  |  |

Evaluate an parsed XPath expression. Different expressions could be evaluated on the same context, and same expression could be evaluated on multiple trees without recompiling.

Parameters:

  | context | XPath context must not be null
  | xpath_expr | XPath expression to be evaluated

Returns:
  The set of results.

AXIS2_EXTERN axiom_xpath_result_t* axiom_xpath_evaluate_streaming | ( | axiom_xpath_context_t * | context,
|  | axiom_xpath_expression_t * | xpath_expr |
| ) |  |  |

Evaluates an XPath expression on streaming XML. Not all expressions can be evaluated on streaming XML. If the expression cannot be evaluated on streaming XML NULL will be returned.

Parameters:

  | context | XPath Context, must not be null
  | xpath_expr | XPath expression to be evaluated

AXIS2_EXTERN void axiom_xpath_free_context | ( | const axutil_env_t * | env,
|  | axiom_xpath_context_t * | context |
| ) |  |  |

Free XPath context

Parameters:

  | env | Environment must not be null
  | context | XPath context must not be null

AXIS2_EXTERN void axiom_xpath_free_expression | ( | const axutil_env_t * | env,
|  | axiom_xpath_expression_t * | xpath_expr |
| ) |  |  |

Free XPath expression

Parameters:

  | env | Environment must not be null
  | xpath_expr | XPath expression must not be null

AXIS2_EXTERN void axiom_xpath_free_result | ( | const axutil_env_t * | env,
|  | axiom_xpath_result_t * | result |
| ) |  |  |

Free XPath result set

Parameters:

  | env | Environment must not be null
  | result | XPath result set must not be null

AXIS2_EXTERN axiom_xpath_function_t axiom_xpath_get_function | ( | axiom_xpath_context_t * | context,
|  | axis2_char_t * | name |
| ) |  |  |

Retrive a pointer to a registered funciton by the function name. If there is no function registered by the given name, NULL will be returned.

Parameters:

  | context | XPath Context, must not be null
  | name | Name of the function, must not be null

Returns:
  The corresponding function.

AXIS2_EXTERN axiom_namespace_t* axiom_xpath_get_namespace | ( | axiom_xpath_context_t * | context,
|  | axis2_char_t * | prefix |
| ) |  |  |

Get a registered namespace by the prefix. If there is no namespace registered by the given prefix NULL will be returned

Parameters:

  | context | XPath Context, must not be null
  | prefix | Prefix of the namespace, must not be null

Returns:
  The namespace corresponding to the prefix.

AXIS2_EXTERN void axiom_xpath_register_default_functions_set | ( | axiom_xpath_context_t * | context | ) |

Setup the XPath core function library

Parameters:

  | context | XPath Context, must not be null

AXIS2_EXTERN void axiom_xpath_register_function | ( | axiom_xpath_context_t * | context,
|  | axis2_char_t * | name,
|  | axiom_xpath_function_t | func |
| ) |  |  |

Registers a custom XPath function http://www.w3.org/TR/xpath#corelib

Parameters:

  | context | XPath Context, must not be null
  | name | Name of the function, must not be null
  | func | Pointer to the function, must not be null

AXIS2_EXTERN void axiom_xpath_register_namespace | ( | axiom_xpath_context_t * | context,
|  | axiom_namespace_t * | ns |
| ) |  |  |

Registers a XPath namespace

Parameters:

  | context | XPath Context, must not be null
  | ns | AXIOM namespace, must not be null

AXIS2_EXTERN axis2_bool_t axiom_xpath_streaming_check | ( | const axutil_env_t * | env,
|  | axiom_xpath_expression_t * | expr |
| ) |  |  |

Checks whether the given expression can be evaluated on streaming XML. If it is possible AXIS2_TRUE will be retuned; AXIS2_FALSE otherwise.

Parameters:

  | env | Axis2 environment, must not be null
  | expr | Complied XPath expression, must not be null

Returns:
  A boolean indicating whether the expression can be evaluated on streaming XML.