Mxml Wrapper Module

The mxmlwrap module contains functions for accessing and manipulating known elements of an XML data structure through the Mini-XML library, included in IMOD as libimxml. The module can hold multiple XML data structures, accessed by their indexes in all functions. There is no "current" XML set, unlike in the autodoc module, so different structures can thus be accessed by different threads. All data are accessed via node indexes that are stored in lists. When an element is added, its index is added to the list. When nodes are looked up by name under a given node, their indexes are added to the list.

There are no Fortran wrappers yet.

Header to include: mxmlwrap.h


int ixmlReadFile(const char *filename, int withXMLdecl, char **rootElement)
int ixmlLoadString(const char *string, int withXMLdecl, char **rootElement)
int ixmlNewNodeList(const char *rootElement)
int ixmlWriteFile(int xmlInd, const char *filename)
int ixmlFindElements(int xmlInd, int nodeInd, const char *tag, int *foundInd, int *numFound)
int ixmlGetStringValue(int xmlInd, int nodeInd, char **string)
int ixmlGetIntegerValue(int xmlInd, int nodeInd, int *val)
int ixmlGetFloatValue(int xmlInd, int nodeInd, float *val)
int ixmlGetDoubleValue(int xmlInd, int nodeInd, double *val)
int ixmlGetStringAttribute(int xmlInd, int nodeInd, const char *name, char **string)
int ixmlGetIntegerAttribute(int xmlInd, int nodeInd, const char *name, int *val)
int ixmlAddElement(int xmlInd, int nodeInd, const char *tag)
int ixmlSetStringValue(int xmlInd, int nodeInd, const char *string)
int ixmlSetIntegerValue(int xmlInd, int nodeInd, int val)
int ixmlSetFloatValue(int xmlInd, int nodeInd, float val)
int ixmlSetDoubleValue(int xmlInd, int nodeInd, double val)
int ixmlAddStringAttribute(int xmlInd, int nodeInd, const char *name, const char *value)
int ixmlAddIntegerAttribute(int xmlInd, int nodeInd, const char *name, int value)
int ixmlPopListIndexes(int xmlInd, int firstInd)
void ixmlClear(int index)
void ixmlResetLastLevel()
const char *ixmlWhitespace_cb(void *nodeVoid, int where)

int ixmlReadFile(const char *filename, int withXMLdecl, char **rootElement)

Reads an XML file from filename and returns a copy of the name of its root element in rootElement, which should be freed with free.  Set withXMLdecl non-zero to process a file with the standard opening ?xml (XML declaration) node, or 0 to consider the top node to be the root. The node index list is initialized with a pointer to the top xml node at index 0 and a pointer to the root element at index 1 (if withXMLdecl is non-zero).  The return value is the index for this set of XML data, or -1 for a memory error, -2 for failure to open file, or -3 for failure to load as XML.

int ixmlLoadString(const char *string, int withXMLdecl, char **rootElement)

Like ixmlReadFile, but loads an XML structure from a string in string instead of from a file.

int ixmlNewNodeList(const char *rootElement)

Starts a new set of XML data and a new node list, with a root element named by rootElement.  The node index list is initialized with a pointer to the top xml node at index 0 and a pointer to the root element at index 1.  The return value is the index for this set of XML data, -1 for a memory error, or -2 for failure to create a node.

int ixmlWriteFile(int xmlInd, const char *filename)

Writes the XML data at index xmlInd to file with name filename.

int ixmlFindElements(int xmlInd, int nodeInd, const char *tag, int *foundInd, int *numFound)

Looks for all elements with the name tag under the node with list index nodeInd in the XML data at index xmlInd, and adds pointers to the elements to the node list. The number of elements found is returned in numFound and the list index of the first one found is returned in foundInd.  The return value is -1 for a memory error, -2 for an invalid XML index, or -3 for an invalid node index.

int ixmlGetStringValue(int xmlInd, int nodeInd, char **string)

Returns a copy of the element value for the node with list index nodeInd in the XML data at index xmlInd into string, which should be freed with free. The return value is -1 for a memory error, -2 for an invalid XML index, -3 for an invalid node index, -4 for an invalid value node, such as multiple child nodes or wrong kind of node.

int ixmlGetIntegerValue(int xmlInd, int nodeInd, int *val)

Returns an integer value for the node with list index nodeInd in the XML data at index xmlInd into val.  The return value is -1 for errors in parsing the value, -2 for an invalid XML index, -3 for an invalid node index, or -4 for an invalid value node.

int ixmlGetFloatValue(int xmlInd, int nodeInd, float *val)

Like ixmlGetIntegerValue, but returns a floating point value.

int ixmlGetDoubleValue(int xmlInd, int nodeInd, double *val)

Like ixmlGetIntegerValue, but returns a double value.

int ixmlGetStringAttribute(int xmlInd, int nodeInd, const char *name, char **string)

Returns a copy of the attribute with the name name for the node with list index nodeInd in the XML data at index xmlInd into string, which should be freed with free.  The return value is -1 for a memory error, -2 for an invalid XML index, -3 for an invalid node index, or 1 for the attribute not found.

int ixmlGetIntegerAttribute(int xmlInd, int nodeInd, const char *name, int *val)

Returns the integer value of the attribute with the name name for the node with list index nodeInd in the XML data at index xmlInd into val. The return value is -1 for errors in parsing the value, -2 for an invalid XML index, or -3 for an invalid node index.

int ixmlAddElement(int xmlInd, int nodeInd, const char *tag)

Adds an element with the name tag to the node with list index nodeInd in the XML data at index xmlInd.  The new element is added to the node index list.  Returns the list index  of the node, or -1 for a memory error, -2 for an invalid XML index, or -3 for an invalid node index.

int ixmlSetStringValue(int xmlInd, int nodeInd, const char *string)

Sets the value of the node with list index nodeInd in the XML data at index xmlInd to string.  Returns -1 for a memory error, -2 for an invalid XML index, or -3 for an invalid node index.

int ixmlSetIntegerValue(int xmlInd, int nodeInd, int val)

Like ixmlSetStringValue, but sets the integer value in val.

int ixmlSetFloatValue(int xmlInd, int nodeInd, float val)

Like ixmlSetStringValue, but sets the float value in val.

int ixmlSetDoubleValue(int xmlInd, int nodeInd, double val)

Like ixmlSetStringValue, but sets the double value in val.

int ixmlAddStringAttribute(int xmlInd, int nodeInd, const char *name, const char *value)

Adds a string attribute with the given name and value to the node with list index nodeInd in the XML data at index xmlInd. Returns -2 for an invalid XML index, or -3 for an invalid node index.

int ixmlAddIntegerAttribute(int xmlInd, int nodeInd, const char *name, int value)

Like ixmlAddStringAttribute, but sets the value string from the integer in value.

int ixmlPopListIndexes(int xmlInd, int firstInd)

Discards the end of the node list starting at index firstInd in the in the XML data at index xmlInd.

void ixmlClear(int index)

Clears out the XML structure and index list for XML item index.

void ixmlResetLastLevel()

Resets the output level counter before writing to file with ixmlWhitespace_cb

const char *ixmlWhitespace_cb(void *nodeVoid, int where)

Callback function for writing with 2 spaces of indentation, must be case to mxml_save_cb_t in the call to mxmlSaveFile. Returns a Whitespace string or NULL; nodeVoid is an Element node, where is a MXML_WS_ tag.