//-----------------------------------------------------------------------------
// positionTo
//-----------------------------------------------------------------------------
/// <summary>
/// Position to the <see cref="DOMNode"/> in the result that is at
/// the position specified by the searchKey parameter.
/// </summary>
/// <param name="nodeToReuse">
/// An existing <see cref="DOMNode"/> object can optionally be
/// passed in, and it will be reused instead of a new object being allocated.
/// </param>
/// <param name="uiTimeLimit">
/// Time limit (in milliseconds) for operation to complete. A value of zero
/// indicates that the operation should not time out.
/// </param>
/// <param name="searchKey">
/// This is a key that corresponds to the sort key that was specified using
/// the addSortKey method. This method looks up the node in the result set
/// that has this search key and returns it.
/// </param>
/// <param name="retrieveFlags">
/// The search flags that direct how the key is to be used to do positioning.
/// This should be values from <see cref="RetrieveFlags"/> that are ORed together.
/// </param>
/// <returns>
/// Returns a <see cref="DOMNode"/> object.
/// </returns>
public DOMNode positionTo(
DOMNode nodeToReuse,
uint uiTimeLimit,
DataVector searchKey,
RetrieveFlags retrieveFlags)
{
RCODE rc;
DOMNode newNode;
IntPtr pNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if ((rc = xflaim_Query_positionToByKey( m_pQuery, m_db.getDb(),
uiTimeLimit, searchKey.getDataVector(),
retrieveFlags, ref pNode)) != 0)
{
throw new XFlaimException( rc);
}
if (nodeToReuse == null)
{
newNode = new DOMNode( pNode, m_db);
}
else
{
newNode = nodeToReuse;
newNode.setNodePtr( pNode, m_db);
}
return( newNode);
}
//-----------------------------------------------------------------------------
// getPrev
//-----------------------------------------------------------------------------
/// <summary>
/// Gets the previous <see cref="DOMNode"/> that satisfies the query criteria.
/// This may be a document root node, or any node within the document. What
/// is returned depends on how the XPATH expression was constructed.
/// </summary>
/// <param name="nodeToReuse">
/// An existing <see cref="DOMNode"/> object can optionally be passed in, and
/// it will be reused instead of a new object being allocated.
/// </param>
/// <param name="uiTimeLimit">
/// Time limit (in milliseconds) for operation to complete.
/// A value of zero indicates that the operation should not time out.
/// </param>
/// <returns>
/// Returns a <see cref="DOMNode"/> object.
/// </returns>
public DOMNode getPrev(
DOMNode nodeToReuse,
uint uiTimeLimit)
{
RCODE rc = 0;
DOMNode newNode;
IntPtr pNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if ((rc = xflaim_Query_getPrev( m_pQuery, m_db.getDb(),
uiTimeLimit, ref pNode)) != 0)
{
throw new XFlaimException( rc);
}
if (nodeToReuse == null)
{
newNode = new DOMNode( pNode, m_db);
}
else
{
newNode = nodeToReuse;
newNode.setNodePtr( pNode, m_db);
}
return( newNode);
}
//-----------------------------------------------------------------------------
// getDescendantElement
//-----------------------------------------------------------------------------
/// <summary>
/// Retrieves the first instance of the specified element node from this
/// node's descendant nodes.
/// </summary>
/// <param name="uiElementNameId">
/// The element name ID for the node to be retrieved.
/// </param>
/// <param name="nodeToReuse">
/// An existing <see cref="DOMNode"/> object can optionally be passed in, and
/// it will be reused instead of a new object being allocated.
/// </param>
/// <returns>
/// Returns a <see cref="DOMNode"/> object.
/// </returns>
public DOMNode getDescendantElement(
uint uiElementNameId,
DOMNode nodeToReuse)
{
RCODE rc;
IntPtr pNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if ((rc = xflaim_DOMNode_getDescendantElement( m_pNode, m_db.getDb(),
uiElementNameId, ref pNode)) != 0)
{
throw new XFlaimException( rc);
}
return( makeNode( nodeToReuse, pNode));
}
//-----------------------------------------------------------------------------
// getDocumentNode
//-----------------------------------------------------------------------------
/// <summary>
/// Retrieves the document node of the document this node belongs to.
/// </summary>
/// <param name="nodeToReuse">
/// An existing <see cref="DOMNode"/> object can optionally be passed in, and
/// it will be reused instead of a new object being allocated.
/// </param>
/// <returns>
/// Returns a <see cref="DOMNode"/> object.
/// </returns>
public DOMNode getDocumentNode(
DOMNode nodeToReuse)
{
RCODE rc;
IntPtr pNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if ((rc = xflaim_DOMNode_getDocumentNode( m_pNode, m_db.getDb(),
ref pNode)) != 0)
{
throw new XFlaimException( rc);
}
return( makeNode( nodeToReuse, pNode));
}
//-----------------------------------------------------------------------------
// createNode
//-----------------------------------------------------------------------------
/// <summary>
/// Creates a new DOM node and inserts it into the database in the
/// specified position relative to the current node. An existing
/// DOMNode object can optionally be passed in, and it will be reused
/// instead of a new object being allocated.
/// </summary>
/// <param name="eNodeType">
/// Type of node to create.
/// </param>
/// <param name="uiNameId">
/// The dictionary tag number that represents the node name. This name ID
/// must exist in the dictionary before it can be used here. The value
/// may be one of the predefined ones, or it may be created by calling
/// <see cref="Db.createElementDef"/>.
/// </param>
/// <param name="eInsertLoc">
/// The relative position to insert the new node with respect to this node.
/// </param>
/// <param name="nodeToReuse">
/// An existing <see cref="DOMNode"/> object can optionally be passed in, and
/// it will be reused instead of a new object being allocated.
/// </param>
/// <returns>
/// Returns a <see cref="DOMNode"/> object.
/// </returns>
public DOMNode createNode(
eDomNodeType eNodeType,
uint uiNameId,
eNodeInsertLoc eInsertLoc,
DOMNode nodeToReuse)
{
RCODE rc;
IntPtr pNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if ((rc = xflaim_DOMNode_createNode( m_pNode, m_db.getDb(),
eNodeType, uiNameId, eInsertLoc, ref pNode)) != 0)
{
throw new XFlaimException( rc);
}
return( makeNode( nodeToReuse, pNode));
}
private DOMNode makeNode(
DOMNode nodeToReuse,
IntPtr pNode)
{
if (nodeToReuse == null)
{
return( new DOMNode( pNode, m_db));
}
else
{
nodeToReuse.setNodePtr( pNode, m_db);
return( nodeToReuse);
}
}
//-----------------------------------------------------------------------------
// createAttribute
//-----------------------------------------------------------------------------
/// <summary>
/// Creates a new attribute node for this node. Note that only element
/// nodes are allowed to have attributes.
/// </summary>
/// <param name="uiAttrNameId">
/// The dictionary tag number that represents the attribute name. This name ID
/// must exist in the dictionary before it can be used here. The value
/// may be one of the predefined ones, or it may be created by calling
/// <see cref="Db.createAttributeDef"/>.
/// </param>
/// <param name="nodeToReuse">
/// An existing <see cref="DOMNode"/> object can optionally be passed in, and
/// it will be reused instead of a new object being allocated.
/// </param>
/// <returns>
/// Returns a <see cref="DOMNode"/> object.
/// </returns>
public DOMNode createAttribute(
uint uiAttrNameId,
DOMNode nodeToReuse)
{
RCODE rc;
IntPtr pNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if ((rc = xflaim_DOMNode_createAttribute( m_pNode, m_db.getDb(),
uiAttrNameId, ref pNode)) != 0)
{
throw new XFlaimException( rc);
}
return( makeNode( nodeToReuse, pNode));
}
//-----------------------------------------------------------------------------
// createChildElement
//-----------------------------------------------------------------------------
/// <summary>
/// Creates a new element node and inserts it into the database in the
/// as either the first or last child of the current node. An existing
/// <see cref="DOMNode"/> object can optionally be passed in, and it will be reused
/// instead of a new object being allocated.
/// </summary>
/// <param name="uiChildElementNameId">
/// The dictionary tag number that represents the node name. This name ID
/// must exist in the dictionary before it can be used here. The value
/// may be one of the predefined ones, or it may be created by calling
/// <see cref="Db.createElementDef"/>.
/// </param>
/// <param name="bFirstChild">
/// Specifies whether the new element is to be created as a first or last child.
/// </param>
/// <param name="nodeToReuse">
/// An existing <see cref="DOMNode"/> object can optionally be passed in, and
/// it will be reused instead of a new object being allocated.
/// </param>
/// <returns>
/// Returns a <see cref="DOMNode"/> object.
/// </returns>
public DOMNode createChildElement(
uint uiChildElementNameId,
bool bFirstChild,
DOMNode nodeToReuse)
{
RCODE rc;
IntPtr pNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if ((rc = xflaim_DOMNode_createChildElement( m_pNode, m_db.getDb(),
uiChildElementNameId, (int)(bFirstChild ? 1 : 0), ref pNode)) != 0)
{
throw new XFlaimException( rc);
}
return( makeNode( nodeToReuse, pNode));
}
//-----------------------------------------------------------------------------
// importDocument
//-----------------------------------------------------------------------------
/// <summary>
/// Imports an XML document into the XFlaim database. The import requires
/// an update transaction.
/// </summary>
/// <param name="istream">
/// Input stream containing the document(s) to be imported
/// </param>
/// <param name="uiCollection">
/// Destination collection for imported document(s).
/// </param>
/// <param name="nodeToReuse">
/// An existing DOM node object can optionally be passed in. It will
/// be reused rather than allocating a new object.
/// </param>
/// <param name="importStats">
/// Import statistics is returned here if a non-null value is passed in.
/// </param>
/// <returns>
/// Returns a <see cref="DOMNode"/> that is the root of the imported document.
/// </returns>
public DOMNode importDocument(
IStream istream,
uint uiCollection,
DOMNode nodeToReuse,
CS_XFLM_IMPORT_STATS importStats)
{
RCODE rc;
IntPtr pDocumentNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if (importStats == null)
{
importStats = new CS_XFLM_IMPORT_STATS();
}
if ((rc = xflaim_Db_importDocument( m_pDb, istream.getIStream(),
uiCollection, ref pDocumentNode, importStats)) != 0)
{
throw new XFlaimException(rc);
}
if( nodeToReuse != null)
{
nodeToReuse.setNodePtr( pDocumentNode, this);
return( nodeToReuse);
}
return( new DOMNode( pDocumentNode, this));
}
//-----------------------------------------------------------------------------
// importIntoDocument
//-----------------------------------------------------------------------------
/// <summary>
/// Imports an XML fragment into a document. The import requires
/// an update transaction.
/// </summary>
/// <param name="istream">
/// Input stream containing the nodes to be imported.
/// </param>
/// <param name="nodeToLinkTo">
/// Existing node that imported nodes will link to.
/// </param>
/// <param name="insertLocation">
/// Where imported XML fragment is to be linked with respect
/// to nodeToLinkTo.
/// </param>
/// <returns>
/// Returns import statistics <see cref="CS_XFLM_IMPORT_STATS"/>.
/// </returns>
public CS_XFLM_IMPORT_STATS importIntoDocument(
IStream istream,
DOMNode nodeToLinkTo,
eNodeInsertLoc insertLocation)
{
RCODE rc;
CS_XFLM_IMPORT_STATS importStats = new CS_XFLM_IMPORT_STATS();
if ((rc = xflaim_Db_importIntoDocument( m_pDb,
istream.getIStream(), nodeToLinkTo.getNode(), insertLocation,
importStats)) != 0)
{
throw new XFlaimException(rc);
}
return( importStats);
}
//-----------------------------------------------------------------------------
// getNode
//-----------------------------------------------------------------------------
/// <summary>
/// Retrieves the specified node from the specified collection.
/// </summary>
/// <param name="uiCollection">
/// The collection where the node is stored.
/// </param>
/// <param name="ulNodeId">
/// The ID number of the node to be retrieved.
/// </param>
/// <param name="nodeToReuse">
/// </param>
/// <returns></returns>
public DOMNode getNode(
uint uiCollection,
ulong ulNodeId,
DOMNode nodeToReuse)
{
RCODE rc;
IntPtr pNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if ((rc = xflaim_Db_getNode( m_pDb, uiCollection, ulNodeId,
ref pNode)) != 0)
{
throw new XFlaimException(rc);
}
if (nodeToReuse != null)
{
nodeToReuse.setNodePtr(pNode, this);
return( nodeToReuse);
}
return( new DOMNode(pNode, this));
}
//-----------------------------------------------------------------------------
// getDictionaryDef
//-----------------------------------------------------------------------------
/// <summary>
/// Retrieve a dictionary definition document.
/// </summary>
/// <param name="dictType">
/// The type of dictionary definition being retrieved.
/// </param>
/// <param name="uiDictNumber">
/// The number the dictionary definition being retrieved.
/// </param>
/// <param name="nodeToReuse">
/// An existing DOM node object can optionally be passed in. It will
/// be reused rather than allocating a new object.
/// </param>
/// <returns>
/// Returns the root <see cref="DOMNode"/> of the document.
/// </returns>
public DOMNode getDictionaryDef(
ReservedElmTag dictType,
uint uiDictNumber,
DOMNode nodeToReuse)
{
RCODE rc;
IntPtr pNode = (nodeToReuse != null) ? nodeToReuse.getNode() : IntPtr.Zero;
if ((rc = xflaim_Db_getDictionaryDef( m_pDb, dictType,
uiDictNumber, ref pNode)) != 0)
{
throw new XFlaimException(rc);
}
if (nodeToReuse != null)
{
nodeToReuse.setNodePtr(pNode, this);
return( nodeToReuse);
}
return( new DOMNode(pNode, this));
}
//-----------------------------------------------------------------------------
// exportXMLToString
//-----------------------------------------------------------------------------
/// <summary>
/// Export XML to a string.
/// </summary>
/// <param name="startNode">
/// The node in the XML document to export. All of its sub-tree will be exported.
/// </param>
/// <param name="eFormat">
/// Formatting to use when exporting.
/// </param>
/// <returns>
/// Returns a string containing the exported XML.
/// </returns>
public string exportXMLToString(
DOMNode startNode,
eExportFormatType eFormat)
{
RCODE rc;
IntPtr pszStr;
string sXML;
IntPtr pStartNode = (startNode != null) ? startNode.getNode() : IntPtr.Zero;
if ((rc = xflaim_Db_exportXMLToString( m_pDb, pStartNode,
eFormat, out pszStr)) != 0)
{
throw new XFlaimException( rc);
}
sXML = Marshal.PtrToStringAnsi( pszStr);
m_dbSystem.freeUnmanagedMem( pszStr);
return( sXML);
}
//-----------------------------------------------------------------------------
// exportXML
//-----------------------------------------------------------------------------
/// <summary>
/// Export XML to a text file.
/// </summary>
/// <param name="startNode">
/// The node in the XML document to export. All of its sub-tree will be exported.
/// </param>
/// <param name="sFileName">
/// File the XML is to be exported to. File will be overwritten.
/// </param>
/// <param name="eFormat">
/// Formatting to use when exporting.
/// </param>
public void exportXML(
DOMNode startNode,
string sFileName,
eExportFormatType eFormat)
{
RCODE rc;
IntPtr pStartNode = (startNode != null) ? startNode.getNode() : IntPtr.Zero;
if ((rc = xflaim_Db_exportXML( m_pDb, pStartNode, sFileName, eFormat)) != 0)
{
throw new XFlaimException( rc);
}
}
//-----------------------------------------------------------------------------
// documentDone
//-----------------------------------------------------------------------------
/// <summary>
/// Indicate that modifications to a document are "done". This allows
/// XFLAIM to process the document as needed.
/// </summary>
/// <param name="domNode">
/// Root node of the document that the application has finished
/// modifying
/// </param>
public void documentDone(
DOMNode domNode)
{
RCODE rc;
if ((rc = xflaim_Db_documentDone2( m_pDb, domNode.getNode())) != 0)
{
throw new XFlaimException(rc);
}
}
