14 Package XPointer APIs for C

Package XPointer contains APIs for three interfaces.

This chapter contains these sections:

XPointer Interface
XPtrLoc Interface
XPtrLocSet Interface

XPointer Interface

Table 14-1 summarizes the methods available through the XPointer interface.

Table 14-1 Summary of XPointer Methods; Package XPointer

Function	Summary
XmlXPointerEval()	Evaluates xpointer string.

XmlXPointerEval()

Parses and evaluates xpointer string and calculates locations in the document.

Syntax

xmlxptrlocset* XmlXPointerEval(
   xmldocnode* doc,
   oratext* xptrstr);

Parameter	In/Out	Description
doc	IN	document node of the corresponding DOM tree
xptrstr	IN	xpointer string

Returns

(xmlxptrlocset *) calculated ___location set

XPtrLoc Interface

Table 14-2 summarizes the methods available through the XPtrLoc interface.

Table 14-2 Summary of XPtrLoc Methods; Package XPointer

Function	Summary
XmlXPtrLocGetNode()	Returns Xml node from `XPtrLoc`.
XmlXPtrLocGetPoint()	Returns Xml point from `XPtrLoc`.
XmlXPtrLocGetRange()	Returns Xml range from `XPtrLoc`.
XmlXPtrLocGetType()	Returns type of `XPtrLoc`.
XmlXPtrLocToString()	Returns string for a ___location.

XmlXPtrLocGetNode()

Returns node from ___location

Syntax

xmlnode* XmlXPtrLocGetNode(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	___location

Returns

(xmlnode *) Node from ___location

XmlXPtrLocGetPoint()

Returns point from ___location

Syntax

xmlpoint* XmlXPtrLocGetPoint(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	___location

Returns

(xmlpoint *) Point from ___location

XmlXPtrLocGetRange()

Returns range from ___location.

Syntax

xmlrange* XmlXPtrLocGetRange(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	___location

Returns

(xmlrange *) Range from ___location

XmlXPtrLocGetType()

Returns type of ___location

Syntax

xmlxptrloctype XmlXPtrLocGetType(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	___location

Returns

(xmlxptrloctype) Type of ___location

XmlXPtrLocToString()

Returns string for a ___location:

- node name: name of the container node

- names of container nodes: "not a ___location" otherwise

Syntax

oratext* XmlXPtrLocToString(
   xmlxptrloc* loc);

Parameter	In/Out	Description
loc	IN	___location

Returns

(oratext *) string

XPtrLocSet Interface

Table 14-3 summarizes the methods available through the XPtrLocSet interface.

Table 14-3 Summary of XPtrLocSet Methods; Package XPointer

Function	Summary
XmlXPtrLocSetFree()	Free a ___location set
XmlXPtrLocSetGetItem()	Returns ___location with `idx` position in `XPtrLocSet`
XmlXPtrLocSetGetLength()	Returns length of `XPtrLocSet`.

XmlXPtrLocSetFree()

It is user's responsibility to call this function on every ___location set returned by XPointer or XPtrLocSet interfaces

Syntax

void XmlXPtrLocSetFree(
   xmlxptrlocset* locset);

Parameter	In/Out	Description
locset	IN	___location set

XmlXPtrLocSetGetItem()

Returns ___location with idx position in the ___location set. First position is 1.

Syntax

xmlxptrloc* XmlXPtrLocSetGetItem(
   xmlxptrlocset* locset, 
   ub4 idx);

Parameter	In/Out	Description
locset	IN	___location set
idx	IN	___location index

Returns

(xmlxptrloc *) ___location with the position idx

XmlXPtrLocSetGetLength()

Returns the number of locations in the ___location set

Syntax

ub4 XmlXPtrLocSetGetLength(
   xmlxptrlocset* locset);

Parameter	In/Out	Description
locset	IN	___location set

Returns

(ub4) number of nodes in locset