The C/C++ interface to diXmlsq.dll which performs simple and full XPath 1.0 queries on an XML document. More...

Macros
#define	XMLSQ_ASCIIFY 0x1000
	Asciify the output as XML character references [default=UTF-8-encoded].

#define	XMLSQ_RAW 0x2000
	Output nodeset in raw format [default=prettify with tabs and newlines].

#define	XMLSQ_TRIM 0x4000
	Trim leading and trailing whitespace (and collapse whitespace for an attribute value)

#define	XMLSQ__ERR_NOBUFS -1
	Error: Insufficient buffer space.

#define	XMLSQ__ERR_BAD_FILEORXML -2
	Error: File cannot be opened or is invalid XML.

#define	XMLSQ__ERR_BAD_QUERY -3
	Error: Invalid XPath query.

Functions
long	XMLSQ_GetText (char szOut, long nOutChars, const char xmlFile, const char *query, long nOptions)
	Extract text from the first matching XML node. More...

long	XMLSQ_FullQuery (char szOut, long nOutChars, const char xmlFile, const char *query, long nOptions)
	Perform a full XPath query on the XML input outputting the result as a string. More...

long	XMLSQ_Count (const char xmlFile, const char query, long nOptions)
	Compute the count for the XPath query. More...

long	XMLSQ_Gen_Version (void)
	Get version number of the core DLL. More...

long	XMLSQ_Gen_CompileTime (char *szOut, long nOutChars)
	Get date and time the core DLL module was last compiled. More...

long	XMLSQ_Gen_ModuleName (char *szOut, long nOutChars, long nOptions)
	Get full path name of the current process's core library DLL. More...

long	XMLSQ_Gen_Platform (char *szOut, long nOutChars)
	Get platform for which the core DLL was compiled ("Win32" or "Win64"). More...

Detailed Description

The C/C++ interface to diXmlsq.dll which performs simple and full XPath 1.0 queries on an XML document.

Output to szOut buffer: Functions that provide output in szOut require the buffer to be pre-dimensioned (i.e. allocated) to at least the specified length nOutChars PLUS one extra for the null-terminating byte. These functions always return the total length in bytes of the string they tried to create (perhaps a negative value if an error). To find the required length, pass a NULL szOut or zero nOutChars argument, then add one to the result for the required buffer size.

Note that the number returned may be negative if an error occurs. See Error messages.

For example:

char *xmlfile = "test.xml";
char *query = "/";
long nchars;
char *lpszOut;
// Find out how many bytes we need
nchars = XMLSQ_GetText(NULL, 0, xmlfile, query, 0);
if (nchars < 0) error();
// Pre-dimension, i.e allocate memory for string buffer
lpszOut = malloc(nchars+1);  // NB +1
if (!lpszOut) error();
nchars = XMLSQ_GetText(lpszOut, nchars, xmlfile, query, 0);
// ...
// do something with lpszOut...
// ...
free(lpszOut);

Differences between XMLSQ_GetText() and XMLSQ_FullQuery(): The function XMLSQ_GetText() extracts the text value of the first node found selected by the query. XMLSQ_FullQuery() outputs the result of the full XPath 1.0 query as a string.

For example, for the file hello-lang.xml

<?xml version="1.0" encoding="UTF-8"?>
<a>
  <b lang="en">Hello world</b>
  <b lang="es">Olá mundo</b>
  <b lang="cs">Ahoj světe</b>
</a>

XMLSQ_GetText(buf, nchars, "hello-lang.xml", "//b", 0); // outputs

Hello world

XMLSQ_FullQuery(buf, nchars, "hello-lang.xml", "//b", 0); // outputs
<b lang="en">Hello world</b>
<b lang="es">Olá mundo</b>
<b lang="cs">Ahoj světe</b>

XMLSQ_GetText(buf, nchars, "hello-lang.xml", "//b/@lang", 0); // outputs

en

XMLSQ_FullQuery(buf, nchars, "hello-lang.xml", "//b/@lang", 0); // outputs
lang="en"
lang="es"
lang="cs"

Error messages

If an error occurs, a negative number -N is returned.

For XMLSQ_GetText() and XMLSQ_FullQuery() N is the length of the error message that will be output in the szOut buffer. You should act on the sign of the return value and allocate the buffer size accordingly. For example.

int r, nchars;
char *buf;
r = XMLSQ_GetText(NULL, 0, xmlfile, query, 0);
nchars = (r > 0 ? r : -r);
buf = calloc(1, nchars + 1);
r = XMLSQ_GetText(buf, nchars, xmlfile, query, 0);

An error message will begin with **ERROR:. If the output buffer is too short, XMLSQ__ERR_NOBUFS (-1) will be returned.

For XMLSQ_Count() the error code -N is either XMLSQ__ERR_BAD_FILEORXML (-2) or XMLSQ__ERR_BAD_QUERY (-3).

Function Documentation

◆ XMLSQ_GetText()

long XMLSQ_GetText	(	char *	szOut,
		long	nOutChars,
		const char *	xmlFile,
		const char *	query,
		long	nOptions
	)

Extract text from the first matching XML node.

Parameters

szOut	Buffer to receive output.
nOutChars	Maximum number of character bytes to be received (excluding the null terminating byte).
xmlFile	Name of XML file or string containing XML data.
query	XPath 1.0 expression to select a node. This must evaluate to a node or node set.
nOptions	Option flags. Add with the '\|' operator. Add XMLSQ_ASCIIFY to replace any non-ASCII characters in the output with XML character references. Add XMLSQ_RAW to display a nodeset without prettify-ing with tabs and newlines. Add XMLSQ_TRIM to trim leading and trailing whitespace (and collapse whitespace for an attribute value).

Returns: Number of bytes in or required for the output string. In case of an error, the return value will be a negative number -N, where N is the length of the error message, that will be output in szOut. If the output buffer szOut is too short, XMLSQ__ERR_NOBUFS (-1) will be returned.

Remarks

To find the required length, pass a NULL argument for szOut or zero for nOutChars.

XPath 1.0 only.

If query evaluates to a single element with content, then the text content will be output.
If query evaluates to an attribute, then the attribute value will be output.
If query evaluates to a node set, then the content of the first matching node will be returned as a string, including any markup.
If no matching text node is found, an empty string is returned (return value = 0). No distinction is made between a match on an empty element and no match at all. Use XMLSQ_Count() to differentiate between a match on an empty element (returns > 0) and no match at all (returns 0).

◆ XMLSQ_FullQuery()

long XMLSQ_FullQuery	(	char *	szOut,
		long	nOutChars,
		const char *	xmlFile,
		const char *	query,
		long	nOptions
	)

Perform a full XPath query on the XML input outputting the result as a string.

Parameters

szOut	Buffer to receive output.
nOutChars	Maximum number of character bytes to be received (excluding the null terminating byte).
xmlFile	Name of XML file or string containing XML data.
query	XPath 1.0 expression.
nOptions	Option flags. Add with the '\|' operator. Add XMLSQ_ASCIIFY to replace any non-ASCII characters in the output with XML character references. Add XMLSQ_RAW to display a nodeset without prettify-ing with tabs and newlines. Add XMLSQ_TRIM to trim leading and trailing whitespace (and collapse whitespace for an attribute value).

Returns: Number of bytes in or required for the output string. In case of an error, the return value will be a negative number -N, where N is the length of the error message, that will be output in szOut. If the output buffer szOut is too short, XMLSQ__ERR_NOBUFS (-1) will be returned.

Remarks: query may be any valid XPath 1.0 expression. The result is always output as a string. So, for example, the number 1.5 will be output as the string "1.500000" and the boolean value true will be output as "true".

◆ XMLSQ_Count()

long XMLSQ_Count	(	const char *	xmlFile,
		const char *	query,
		long	nOptions
	)

Compute the count for the XPath query.

Parameters

xmlFile	Name of XML file or string containing XML data.
query	XPath 1.0 expression. This must evaluate to a node or node set.
nOptions	For future use. Specify zero (0).

Returns: The integer value of count(query) or a negative error code.

Remarks: Use XMLSQ_Count() to differentiate between a match on an empty element (returns > 0) and no match at all (returns 0).; The error code XMLSQ__ERR_BAD_FILEORXML (-2) indicates a missing file or invalid XML document structure. The code XMLSQ__ERR_BAD_QUERY (-3) indicates an invalid query.; For a more detailed error message, use XMLSQ_FullQuery().

◆ XMLSQ_Gen_Version()

long XMLSQ_Gen_Version ( void )

Get version number of the core DLL.

Returns: Version number as an integer in the form major*10000+minor*100+revision e.g. DLL file version 1.2.x.3 will return 10203

◆ XMLSQ_Gen_CompileTime()

long XMLSQ_Gen_CompileTime	(	char *	szOut,
		long	nOutChars
	)

Get date and time the core DLL module was last compiled.

Parameters

[out]	szOut	Buffer to receive output string.
[in]	nOutChars	Maximum number of character bytes to be received (excluding the null terminating byte).

Returns: Number of characters in or required for output string.

◆ XMLSQ_Gen_ModuleName()

long XMLSQ_Gen_ModuleName	(	char *	szOut,
		long	nOutChars,
		long	nOptions
	)

Get full path name of the current process's core library DLL.

Parameters

[out]	szOut	Buffer to receive output string.
[in]	nOutChars	Maximum number of character bytes to be received (excluding the null terminating byte).
[in]	nOptions	Not used. Specify zero.

Returns: Number of characters in or required for output string.

◆ XMLSQ_Gen_Platform()

long XMLSQ_Gen_Platform	(	char *	szOut,
		long	nOutChars
	)

Get platform for which the core DLL was compiled ("Win32" or "Win64").

Parameters

[out]	szOut	Buffer to receive output string.
[in]	nOutChars	Maximum number of character bytes to be received (excluding the null terminating byte).

Returns: Number of characters in or required for output string.

Macros

Functions

Detailed Description

Error messages

Function Documentation

◆ XMLSQ_GetText()

◆ XMLSQ_FullQuery()

◆ XMLSQ_Count()

◆ XMLSQ_Gen_Version()

◆ XMLSQ_Gen_CompileTime()

◆ XMLSQ_Gen_ModuleName()

◆ XMLSQ_Gen_Platform()