XML Module

Robert-Vladut Patrascu

Table of Contents

1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.4. Exported Variables
1.4.1. Variable lifetime
1.4.2. Accessing the $xml(path) variable
1.5. Exported Functions

List of Examples

1.1. Creating a document
1.2. Inserting nodes with indentation
1.3. Using script variables in path

Chapter 1. Admin Guide

1.1. Overview

This module exposes a script variable that provides basic parsing and manipulation of XML documents or blocks of XML data. The variable provides ways to access entire XML elements, their text content or their attributes. You can modify the content and attributes as well as adding or removing nodes in the XML tree.

The processing does not take into account any DTDs or schemas in terms of validation.

1.2. Dependencies

1.2.1. OpenSIPS Modules

This module does not depend on other modules.

1.2.2. External Libraries or Applications

  • libxml2 Most Linux and BSD distributions include libxml but the library can also be downloaded from: xmlsoft.org

1.3. Exported Parameters

The module does not export any parameters.

1.4. Exported Variables

This module exports the $xml(path) variable.

1.4.1. Variable lifetime

The xml variables will be available to the process that created them from the moment they were initialized. They will not reset per message or per transaction. If you want to use them on a per message basis you should initialize them each time.

1.4.2. Accessing the $xml(path) variable

Accessing elements and attributes is based on the tree representation of the XML document thus a complete path from the root node is required. The in-memory equivalent of an XML document is an "XML object" which must be initilized with a well-formed block of XML data before use. In consequence, the path must start with the object name, followed by any number of nodes leading to the desired element.

The grammar that describes the path is:

path = name | name(identifier)+(acces)?

identifier = element(index)?

element = /string | /$var

index = [integer] | [$var]

access = .val | .attr/string | .attr/$var

In order to select between nodes with identical names on a certain level in the tree, an index can be provided, starting from 0.

The sequence of nodes in the path can be followed by .val in order to access the last node's text content or by .attr/attr_name in order to access it's attribute named attr_name. Otherwise the entire element (start-tag, end-tag, children elements and content) is accessed.

Assiging NULL to the variable removes the entire element or it's text content or attribute acording to the access mode.

If you want to insert an element, you must assign a string value (containg a well-formed block of XML data that has a root node) to the parent node. Note that assigning a value directly to a node does not replace it with that value.

IMPORTANT: In XML all characters in the content of the document are significant including blanks and formatting line breaks. An element and it's content will be returned WITH all the whitespaces and newlines and when adding a new node under an existing one, if you want to insert it with indentation, you must include the needed characters in the assigned string.

Other script variables can be used as element names, attribute names and indexes in the path. Variables that will be used as indexes must contain integer values. Variables that will be used as element or attribute names should contain string values.

Example 1.1. Creating a document

$xml(my_doc) = "<doc></doc>";        # init object

$xml(my_doc/doc) = "<list></list>";  # add a "list" node

$xml(my_doc/doc/list) = "<item>some_value</item>";    # add an "item" node to the list

$xml(my_doc/doc/list) = "<item>another_value</item>"; # add another item to the list

$xml(my_doc/doc/list/item[1].val) = "new_val";        # set text content of previous item

$xml(my_doc/doc/list.attr/sort) = "asc";              # add attribute "sort" to list node

$xml(my_doc/doc/list.attr/sort) = NULL;               # remove previous attribute

$xml(my_doc/doc/list/item[1]) = NULL;                 # remove second item

$xml(my_doc/doc/list.val) = "end";                    # add text content to list which now has
                                                      # mixed content

$xml(my_doc/doc/list.val) = NULL;                     # remove the text content

xlog("$xml(my_doc/doc/list)\n");                      # display the entire list

xlog("$xml(my_doc)\n");                               # display the entire document

$xml(my_doc) = NULL;                                  # clear the entire document

Example 1.2. Inserting nodes with indentation

$xml(my_doc) = "<doc>\n</doc>";
$xml(my_doc/doc) = "\t<list></list>\n";
$xml(my_doc/doc/list) = "\n\t\t<item></item>\n\t";

# this creates the following document:
# <doc>
#	<list>
#		<item></item>
#	</list>
# </doc>
# without the explicit formating characters the document would be:
# <doc><list><item></item></list></doc>

Example 1.3. Using script variables in path

# accessing the attribute of second item in list
$var(my_list) = "list";
$var(my_idx) = 1;
$var(my_attr) = "sort";

1.5. Exported Functions

The module does not export any script functions.