XML Fragments which may be stored in a design file. More...

Classes
struct	XmlFragment
	Class used to define XML Fragments that can be stored in the design file. More...

struct	XmlFragmentList
	Class used to process list of XML Fragments. More...

Typedefs
typedef int	deleteXMLFragmentCallback (XMLFragmentListP pXMLFragmentList, CallbackArgP pUserParams)
	UserFunction is called for every XMl fragment that passes the criteria setup in the `mdlXMLFragmentList_stripFromElement`. More...

Functions
StatusInt	mdlXMLFragment_appendToXmlDom (XmlDomRef domRef, XmlNodeRef nodeRef, XMLFragmentP pThis)
	Appends the XML Fragment text to a node in an XML Dom. More...

StatusInt	mdlXMLFragment_appendToXmlDomExt (XmlDomRef domRef, XmlNodeRef nodeRef, XMLFragmentP pThis, bool bFreeThreaded)
	Appends the XML Fragment text to a node in an XML Dom. More...

StatusInt	mdlXMLFragment_createXmlDom (XmlDomRef *pDomRef, XMLFragmentP pThis)
	Creates an non FreeThreaded XML DOM from the XML Fragment. More...

StatusInt	mdlXMLFragment_createFreeThreadedXmlDom (XmlDomRef *pDomRef, XMLFragmentP pThis)
	Creates a FreeThreaded XML DOM from the XML Fragment. More...

StatusInt	mdlXMLFragment_setTextFromXMLNode (XMLFragmentP pThis, XmlNodeRef nodeRef)
	Sets the XML Text for an XML Fragment using nodeRef. More...

StatusInt	mdlXMLFragment_setTextFromXMLDom (XMLFragmentP pThis, XmlDomRef domRef)
	Sets the XML Text for an XML Fragment using the XmlDom Root Element. More...

StatusInt	mdlXMLFragment_setTextIfWellFormed (XMLFragmentP pThis, WChar const *const pText)
	Sets the XML Text for an XML Fragment only if pText is a Well-Formed XML fragment. More...

StatusInt	mdlXMLFragmentList_appendToXmlDom (XmlDomRef domRef, XmlNodeRef nodeRef, XMLFragmentListP pThis)
	Appends all the XML Fragment text from XMLFragmentList into a non-free threaded XML Dom. More...

StatusInt	mdlXMLFragmentList_appendToXmlDomExt (XmlDomRef domRef, XmlNodeRef nodeRef, XMLFragmentListP pThis, bool bFreeThreaded)
	Appends all the XML Fragment text from XMLFragmentList into a XML Dom. More...

StatusInt	mdlXMLFragmentList_createXmlDom (XmlDomRef pDomRef, XMLFragmentListP pThis, WChar const const pRootElementName)
	Creates an non FreeThreaded XML Dom from the XML FragmentList. More...

StatusInt	mdlXMLFragmentList_createFreeThreadedXmlDom (XmlDomRef pDomRef, XMLFragmentListP pThis, WChar const const pRootElementName)
	Creates a Free Threaded XML Dom from the XML FragmentList. More...

XMLFragmentListP	mdlXMLFragmentList_constructFromXmlDom (XmlDomRef domRef, WChar *pSchemaURN, UShort appID, UShort appType)
	Constructs an XML Fragment List containing a single XML Fragment from the XMLDom. More...

XMLFragmentListP	mdlXMLFragmentList_constructFromXmlNode (XmlNodeRef nodeRef, WChar *pSchemaURN, UShort appID, UShort appType)
	Constructs an XML Fragment List containing a single XML Fragment from the XMLDomNode. More...

XMLFragmentListP	mdlXMLFragmentList_construct (WChar pText, WChar pSchemaURN, UShort appID, UShort appType)
	*XML Fragment/FragmentList Functions* More...

StatusInt	mdlXMLFragmentList_free (XMLFragmentListP *ppThis)
	Frees memory of the XML Fragment List. More...

StatusInt	mdlXMLFragment_getAppID (UShort *pAppID, XMLFragmentCP pThis)
	Retrieves the app identifier from the given XML Fragment. More...

StatusInt	mdlXMLFragment_setAppID (XMLFragmentP pThis, UShort appID)
	Sets the app identifier for the given XML Fragment. More...

StatusInt	mdlXMLFragment_getAppType (UShort *pAppType, XMLFragmentCP pThis)
	Retrieves the app type from the given XML Fragment. More...

StatusInt	mdlXMLFragment_setAppType (XMLFragmentP pThis, UShort appType)
	Sets the app type for the given XML Fragment. More...

StatusInt	mdlXMLFragment_getSchemaURN (WChar **ppSchemaURN, XMLFragmentCP pThis)
	Get the Schema URN from an XML Fragment. More...

StatusInt	mdlXMLFragment_setSchemaURN (XMLFragmentP pThis, const WChar *pSchemaURN)
	Sets the Schema URN for an XML Fragment. More...

StatusInt	mdlXMLFragment_getText (WChar **ppText, XMLFragmentCP pThis)
	Get the XML Text from an XML Fragment. More...

StatusInt	mdlXMLFragment_setText (XMLFragmentP pThis, const WChar *pText)
	Sets the XML Text for an XML Fragment. More...

StatusInt	mdlXMLFragment_getIsCompressed (bool *pIsCompressed, XMLFragmentCP pThis)
	Get the "is compressed" flag value from an XML Fragment. More...

StatusInt	mdlXMLFragment_setIsCompressed (XMLFragmentP pThis, bool isCompressed)
	Sets the "is compressed" flag value for an XML Fragment. More...

StatusInt	mdlXMLFragmentList_createXMLElementDescriptor (MSElementDescrH ppDescr, XMLFragmentListP *ppThis, bool freeXMLFragmentList)
	Creates a XMLFragment element descriptor (chain) from all entries in a XMLFragmentList. More...

XMLFragmentListP	mdlXMLFragmentList_constructFromXMLFragmentElement (MSElementDescrCP pDescr)
	Constructs an XML Fragment List from an XML Element element descriptor. More...

StatusInt	mdlXMLFragmentList_attachToElement (XMLFragmentListP *ppXMLFragmentList, MSElementDescrH ppElmDscr, bool freeXMLFragmentList)
	Attaches the XMLFragmentList entries to the first element of a descriptor chain. More...

StatusInt	mdlXMLFragmentList_extractFromElement (XMLFragmentListP *ppXMLFragmentList, MSElementP pElm)
	Retrieves a list of all XMLFragments attached to the given element descriptor. More...

StatusInt	mdlXMLFragmentList_extractFromElementByAppIDAndType (XMLFragmentListP ppXMLFragmentList, MSElementP pElm, const UShort pAppID, const UShort *pAppType)
	Retrieves a list of XMLFragments attached to the given element descriptor using the search criteria of App ID and/or App Type. More...

StatusInt	mdlXMLFragmentList_stripAllFromElement (XMLFragmentListP *ppXMLFragmentList, MSElementP pElm)
	Deletes all XMLFragment attachments from the input element. More...

StatusInt	mdlXMLFragmentList_stripFromElementByAppIDAndType (XMLFragmentListP ppXMLFragmentList, MSElementP pElm, UShort pAppID, UShort *pAppType)
	Deletes XMLFragment attachments from the input element using the search criteria of App ID and/or App Type. More...

UInt32	mdlXMLFragmentList_getCount (XMLFragmentListP pThis)
	Retrieves the count of XMLFragments in an XML Fragment List. More...

StatusInt	mdlXMLFragmentList_append (XMLFragmentListP *ppThis, XMLFragmentP pAppendFragment)
	Appends an XML Fragment to an XML Fragment List. More...

StatusInt	mdlXMLFragmentList_prepend (XMLFragmentListP *ppThis, XMLFragmentP pPrependFragment)
	Prepends an XML Fragment to an XML Fragment List. More...

StatusInt	mdlXMLFragmentList_duplicate (XMLFragmentListP *ppCopy, XMLFragmentListP pThis)
	Creates a duplicate XML Fragment list from all entries in the given XML Fragment List. More...

StatusInt	mdlXMLFragmentList_duplicateSingle (XMLFragmentListP *ppCopy, XMLFragmentListP pThis)
	Creates a duplicate XML Fragment list from only the current XML Fragment List entry. More...

Public XMLFragmentP	mdlXMLFragmentList_getXMLFragmentAtIndex (XMLFragmentListP pThis, UInt32 index)
	Retrieves the XML Fragment from the input XML Fragment List Entry. More...

XMLFragmentP	mdlXMLFragmentList_getXMLFragment (XMLFragmentListP pThis)
	Retrieves the first XML Fragment from the input XML Fragment List Entry. More...

Detailed Description

XML Fragments which may be stored in a design file.

List of XML Fragments.

The XmlFragment class provides methods for storing XML-formatted data into a design file. The data may be stored in an XML Fragment element, as a linkage or XAttribute data.

An XML Fragment consists of:

AppID: A UShort identifying your application
AppType: A UShort used to further classify the use of the XML Fragment by your application
SchemaURN (optional): If your fragment conforms to an XML Schema, you may record the Schema's URN (Universal Resource Name) here.
XmlText: The actual XML fragment.

For performance, the XML Fragment API does not validate your XML fragments against an XML Schema or check them for well-formedness. You may use an XML parser for validation. The SchemaURN is provided for your reference, but may be utilized in future versions of MicroStation. Also for performance, the XML fragments are not compressed by default. If a large XML Text string must be attached to an element, use XmlFragment::SetIsCompressed to specify that it be compressed.

Typical method of attaching XML Fragment Linkage. Example:

UShort const APPID_GasCompany       = 2000;
UShort const APPTYPE_FeatureData    = 10;
UShort const  APPTYPE_StateData     = 11;
WCharCP featureDataSchema = L"www.bentley.com/piping";
WCharCP featureData = L"<FeatureData Name=\"Pipe\"></FeatureData>";
int test_fragmentLinkage (DgnModel& dgnCache)
    {
    EditElementHandle eeh;
    // Create a line
    DPoint3d        linePts[2];
    memset (linePts, 0, sizeof(linePts));
    linePts[1].y = 100;
    if (SUCCESS, LineHandler::CreateLineElement (eeh, NULL, *linePts, false, dgnCache))
        return ERROR;
    // create the XML fragment     
    XmlFragmentPtr pXMLFragment = XmlFragment::Construct (APPID_GasCompany, APPTYPE_FeatureData, false, featureData, featureDataSchema);
    if (!pXMLFragment.IsValid ())
        return ERROR;
    // attach the fragment
    if (SUCCESS != pXMLFragment->AttachToElement (eeh))
        return ERROR;
    // write the element
    return AddElementToModel (dgnCache, eeh);
    }

The XmlFragmentList class provides methods for creating, maintaining and processing a list of XML Fragments. This is useful when dealing with multiple XML Fragment linkages on a single element. They are not as useful when dealing with XML Fragment elements which can only store the data for a single XmlFragment object.

Typical method of extrach XML Fragment Linkage(s) from an element. Example:

XmlFragmentListPtr linkageFragments = XmlFragmentList::ExtractFromElement (eeh);
if (linkageFragments.IsValid ())
    {
    for each (XmlFragmentPtr fragment in (*linkageFragments))
        {
        printf ("AppID=%d, AppType=%d, SchemaURN=%S\n", fragment->GetAppID (), fragment->GetAppType (), fragment->GetSchemaURN ());
        }
    }

Typedef Documentation

typedef int deleteXMLFragmentCallback(XMLFragmentListP pXMLFragmentList,CallbackArgP pUserParams)

UserFunction is called for every XMl fragment that passes the criteria setup in the mdlXMLFragmentList_stripFromElement.

Parameters

[in]	pXMLFragmentList	The XML fragment that matches the criteria from the `mdlXMLFragmentList_stripFromElement`.
[in]	pUserParams	the user data passed to the `mdlXMLFragmentList_stripFromElement` function.

Returns: 0 to keep linkage, 1 to delete it.

See also: mdlXMLFragmentList_stripFromElement

Function Documentation

StatusInt mdlXMLFragment_appendToXmlDom	(	XmlDomRef	domRef,
		XmlNodeRef	nodeRef,
		XMLFragmentP	pThis
	)

Appends the XML Fragment text to a node in an XML Dom.

Parameters

[in]	domRef	DOM to insert XMLFragment into
[in]	nodeRef	Node in DOM to append Fragment to
[in]	pThis	XML Fragment to append

Returns: SUCCESS, ERROR or MDLERR_BADARG; domRef must be a non-threaded DOM, use mdlXMLFragment_appendToXmlDomExt for freethreaded DOMs

See also: mdlXMLFragment_appendToXmlDomExt

StatusInt mdlXMLFragment_appendToXmlDomExt	(	XmlDomRef	domRef,
		XmlNodeRef	nodeRef,
		XMLFragmentP	pThis,
		bool	bFreeThreaded
	)

Appends the XML Fragment text to a node in an XML Dom.

Parameters

[in]	domRef	DOM to insert XMLFragment into
[in]	nodeRef	Node in DOM to append Fragment to
[in]	pThis	XML Fragment to append
[in]	bFreeThreaded	is domRef a freethreaded DOM?

Returns: SUCCESS, ERROR or MDLERR_BADARG

See also: mdlXMLFragment_appendToXmlDom

StatusInt mdlXMLFragment_createFreeThreadedXmlDom	(	XmlDomRef *	pDomRef,
		XMLFragmentP	pThis
	)

Creates a FreeThreaded XML DOM from the XML Fragment.

Parameters

[in,out]	pDomRef	created Free Threaded XML DOM
[in]	pThis	XML Fragment to append

Returns: SUCCESS, ERROR or MDLERR_BADARG

See also: mdlXMLFragment_createXmlDom; mdlXMLDom_free

StatusInt mdlXMLFragment_createXmlDom	(	XmlDomRef *	pDomRef,
		XMLFragmentP	pThis
	)

Creates an non FreeThreaded XML DOM from the XML Fragment.

Parameters

[in,out]	pDomRef	created non FreeThreaded XML DOM
[in]	pThis	XML Fragment to append

Returns: SUCCESS, ERROR or MDLERR_BADARG

See also: mdlXMLFragment_createFreeThreadedXmlDom; mdlXMLDom_free

StatusInt mdlXMLFragment_getAppID	(	UShort *	pAppID,
		XMLFragmentCP	pThis
	)

Retrieves the app identifier from the given XML Fragment.

Parameters

[out]	pAppID	The ID of the "app" to which this XMLFragment belongs (typically an application's LinkageID)
[in]	pThis	XML Fragment.

Returns: normally SUCCESS; MDLERR_BADARG if App ID or XMLFragment pointer is invalid.

See also: mdlXMLFragment_setAppID

StatusInt mdlXMLFragment_getAppType	(	UShort *	pAppType,
		XMLFragmentCP	pThis
	)

Retrieves the app type from the given XML Fragment.

Remarks: The app type is an application assigned value which uniquely identifies the XML Fragment within the application's app.

Parameters

[out]	pAppType	App type of XML Fragment.
[in]	pThis	XML Fragment.

Returns: normally SUCCESS; MDLERR_BADARG if either pAppType or pThis pointers is invalid.

See also: mdlXMLFragment_setAppType

StatusInt mdlXMLFragment_getIsCompressed	(	bool *	pIsCompressed,
		XMLFragmentCP	pThis
	)

Get the "is compressed" flag value from an XML Fragment.

Remarks: By default, the XML Fragment is NOT compressed before attachment to an element or XMLFragment element creation. Using compression will not affect file size but will affect memory usage when a file is open.

Parameters

[out]	pIsCompressed	Pointer where to store is compressed flag value from XMLFragment.
[in]	pThis	XML Fragment.

Returns: normally SUCCESS; MDLERR_BADARG if either of boolean or XMLFragment pointers is invalid.

See also: mdlXMLFragment_setIsCompressed

StatusInt mdlXMLFragment_getSchemaURN	(	WChar **	ppSchemaURN,
		XMLFragmentCP	pThis
	)

Get the Schema URN from an XML Fragment.

Parameters

[out]	ppSchemaURN	Pointer to Schema URN string from XMLFragment. (Do not attempt to free)
[in]	pThis	XML Fragment.

Returns: normally SUCCESS; MDLERR_BADARG if either of Schema URN or XMLFragment pointers is invalid.

See also: mdlXMLFragment_setSchemaURN

StatusInt mdlXMLFragment_getText	(	WChar **	ppText,
		XMLFragmentCP	pThis
	)

Get the XML Text from an XML Fragment.

Parameters

[out]	ppText	Pointer to XML Text string from XMLFragment. (Do not attempt to free)
[in]	pThis	XML Fragment.

Returns: normally SUCCESS; MDLERR_BADARG if either of XML Text or XMLFragment pointers is invalid.

See also: mdlXMLFragment_setText

StatusInt mdlXMLFragment_setAppID	(	XMLFragmentP	pThis,
		UShort	appID
	)

Sets the app identifier for the given XML Fragment.

Remarks: The app identifier is a Bentley assigned application identifier (typically an application's LinkageID).

Parameters

[in]	pThis	XML Fragment.
[in]	appID	The ID of the "app" to which this XMLFragment belongs

Returns: normally SUCCESS; MDLERR_BADARG if XMLFragment pointer is invalid.

See also: mdlXMLFragment_getAppID

StatusInt mdlXMLFragment_setAppType	(	XMLFragmentP	pThis,
		UShort	appType
	)

Sets the app type for the given XML Fragment.

Remarks: The app type is an application assigned value which uniquely identifies the XML Fragment Type within the application's app.

Parameters

[in]	pThis	XML Fragment.
[in]	appType	The type of this XMLFragment within the "app" to which it belongs

Returns: normally SUCCESS; MDLERR_BADARG if XMLFragment pointer is invalid.

See also: mdlXMLFragment_getAppType

StatusInt mdlXMLFragment_setIsCompressed	(	XMLFragmentP	pThis,
		bool	isCompressed
	)

Sets the "is compressed" flag value for an XML Fragment.

Remarks: By default, the XML Fragment is NOT compressed before attachment to an element or XMLFragment element creation. Using compression will not affect file size but will affect memory usage when a file is open.

Parameters

[in]	pThis	XML Fragment.
[in]	isCompressed	Is compressed flag value to set

Returns: normally SUCCESS; MDLERR_BADARG if XMLFragment pointer is invalid.

See also: mdlXMLFragment_getIsCompressed

StatusInt mdlXMLFragment_setSchemaURN	(	XMLFragmentP	pThis,
		const WChar *	pSchemaURN
	)

Sets the Schema URN for an XML Fragment.

Parameters

[in]	pThis	XML Fragment.
[in]	pSchemaURN	Schema URN to set (or NULL to delete Schema URN).

Returns: normally SUCCESS; MDLERR_BADARG if XMLFragment pointer is invalid. MDLERR_INSFMEMORY if failed allocation of memory to store pSchemaURN.

See also: mdlXMLFragment_getSchemaURN

StatusInt mdlXMLFragment_setText	(	XMLFragmentP	pThis,
		const WChar *	pText
	)

Sets the XML Text for an XML Fragment.

Remarks: The text is assumed to be well formed XML. This function does not validate the XML text.

Parameters

[in]	pThis	XML Fragment.
[in]	pText	XML text to set (or NULL to delete XML text).

Returns: normally SUCCESS; MDLERR_BADARG if XMLFragment pointer is invalid. MDLERR_INSFMEMORY if failed allocation of memory to store pText.

See also: mdlXMLFragment_getText

StatusInt mdlXMLFragment_setTextFromXMLDom	(	XMLFragmentP	pThis,
		XmlDomRef	domRef
	)

Sets the XML Text for an XML Fragment using the XmlDom Root Element.

Parameters

[in]	pThis	XML Fragment to set text
[in]	domRef	XML Dom to set text from

Returns: SUCCESS, ERROR or MDLERR_BADARG

StatusInt mdlXMLFragment_setTextFromXMLNode	(	XMLFragmentP	pThis,
		XmlNodeRef	nodeRef
	)

Sets the XML Text for an XML Fragment using nodeRef.

Parameters

[in]	pThis	XML Fragment to append
[in]	nodeRef	Node to set text from

Returns: SUCCESS, ERROR or MDLERR_BADARG

StatusInt mdlXMLFragment_setTextIfWellFormed	(	XMLFragmentP	pThis,
		WChar const *const	pText
	)

Sets the XML Text for an XML Fragment only if pText is a Well-Formed XML fragment.

Parameters

[in]	pThis	XML Fragment to set text
[in]	pText	Text to validate and set

Returns: SUCCESS, ERROR or MDLERR_BADARG

Remarks: similiar to mdlXMLFragment_setText except test for Well-Formedness first

See also: mdlXMLFragment_setText

StatusInt mdlXMLFragmentList_append	(	XMLFragmentListP *	ppThis,
		XMLFragmentP	pAppendFragment
	)

Appends an XML Fragment to an XML Fragment List.

Parameters

[in,out]	ppThis	Combined list of XML Fragments.
[in]	pAppendFragment	XML Fragment to append. (Pointer should not be freed since it is incorporated into ppThis)

Returns: normally SUCCESS; MDLERR_BADARG if either ppThis or pAppendList pointers is invalid

StatusInt mdlXMLFragmentList_appendToXmlDom	(	XmlDomRef	domRef,
		XmlNodeRef	nodeRef,
		XMLFragmentListP	pThis
	)

Appends all the XML Fragment text from XMLFragmentList into a non-free threaded XML Dom.

Parameters

[in]	domRef	Non Free Threaded DOM to append XMLFragments from XMLFragments into
[in]	nodeRef	Node in DOM to append Fragment to
[in]	pThis	XML Fragment List to append

See also: mdlXMLFragmentList_appendToXmlDomExt

Returns: SUCCESS, ERROR or MDLERR_BADARG

StatusInt mdlXMLFragmentList_appendToXmlDomExt	(	XmlDomRef	domRef,
		XmlNodeRef	nodeRef,
		XMLFragmentListP	pThis,
		bool	bFreeThreaded
	)

Appends all the XML Fragment text from XMLFragmentList into a XML Dom.

Parameters

[in]	domRef	DOM to append XMLFragments from XMLFragments into
[in]	nodeRef	Node in DOM to append Fragment to
[in]	pThis	XML Fragment List to append
[in]	bFreeThreaded	is domRef a freethreaded DOM?

Returns: SUCCESS, ERROR or MDLERR_BADARG

See also: mdlXMLFragmentList_appendToXmlDom

StatusInt mdlXMLFragmentList_attachToElement	(	XMLFragmentListP *	ppXMLFragmentList,
		MSElementDescrH	ppElmDscr,
		bool	freeXMLFragmentList
	)

Attaches the XMLFragmentList entries to the first element of a descriptor chain.

Remarks: If the XMLFragmentList data size is larger than the available space on the given element, a status of MDLERR_TOOLARGE is returned.

The XML Fragment list is freed upon successful completion, if requested.

Parameters

[in,out]	ppXMLFragmentList	List of XMLFragments to attach to the element. (After attaching, freed and set to NULL if freeXMLFragmentList=true)
[in,out]	ppElmDscr	Element descriptor holding the element to which to attach the XML Fragment(s).
[in]	freeXMLFragmentList	Non-zero=Free XML Fragment list after operation. Only freed if function is successful.

Returns: normally SUCCESS; MDLERR_BADARG if either ppXMLFragmentList or ppElmDscr pointers is invalid. MDLERR_TOOLARGE if XMLFragmentList data size too large.

XMLFragmentListP mdlXMLFragmentList_construct	(	WChar *	pText,
		WChar *	pSchemaURN,
		UShort	appID,
		UShort	appType
	)

XML Fragment/FragmentList Functions

Set of functionality to allow creation/manipulation of XML Fragment data.

API Overview

The XML Fragments API enables you to create elements or element linkages containing XML-formatted text. Functions are also provided for setting Scan Criteria for finding your particular XML Fragment element (or elements with a particular XML Fragment linkage.) By storing data in XML Fragment elements and linkages, you let MicroStation and other applications know that they contain XML-formatted data... thus making the data accessible to other applications without requiring source code from your application to interpret your binary linkages.

An mdl XML Fragment consists of:

AppID: A UShort identifying your application
AppType: A UShort used to further classify the use of the XML Fragment by your application
SchemaURN (optional): If your fragment conforms to an XML Schema, you may record the schema's URN (Universal Resource Name) here.
Text: The actual XML fragment.

For performance, the XML Fragment API does not validate your XML fragments against an XML Schema or check them for well-formedness. You may use an XML parser for validation. The SchemaURN is provided for your reference, but may be utilized in future versions of MicroStation. Also for performance, the XML fragments are not compressed by default. If a large XML Text string must be attached to an element, use mdlXMLFragment_setIsCompressed to specify that it be compressed.

The following functions support getting and setting data from an XML Fragment:

When working with several types of XML Fragment linkages, it can be useful to work with linked lists of them. Most of the XML Fragment manipulation functions accept list of fragments as arguments, though in many cases there will be only one entry in the lists. The following functions allow you to create and iterate over XML Fragment lists:

Any XML Fragment can be written to the file as an element or attached to an element as a linkage.

The following functions allow you to read and write XML Fragments as elements:

The following functions allow you to read and write XML Fragements as linkages:

mdlXMLFragmentList_attachToElement
mdlXMLFragmentList_extractFromElement
mdlXMLFragmentList_extractFromElementByAppIDAndType
mdlXMLFragmentList_stripFromElement
mdlXMLFragmentList_stripAllFromElement
mdlXMLFragmentList_stripFromElementByAppIDAndType

The following functions allow you to convert XML Fragments to an XML Dom or XML Dom Node

Constructs an XML Fragment List containing a single XML Fragment.

Parameters

[in]	pText	XML text to set (or NULL).
[in]	pSchemaURN	Schema URN to set (or NULL).
[in]	appID	The ID of the "app" to which this XMLFragment belongs. The app identifier is a Bentley assigned application identifier. (typically an application's LinkageID).
[in]	appType	The type of this XMLFragment within the "app" to which it belongs. The app type is an application assigned value which uniquely identifies the XML Fragment within the application's app.

Returns: normally pointer to XMLFragmentList; NULL otherwise.

XMLFragmentListP mdlXMLFragmentList_constructFromXmlDom	(	XmlDomRef	domRef,
		WChar *	pSchemaURN,
		UShort	appID,
		UShort	appType
	)

Constructs an XML Fragment List containing a single XML Fragment from the XMLDom.

Parameters

[in]	domRef	XML Dom to create XML Fragment list from
[in]	pSchemaURN	Schema URN to set (or NULL).
[in]	appID	The ID of the "app" to which this XMLFragment belongs. The app identifier is a Bentley assigned application identifier. (typically an application's LinkageID).
[in]	appType	The type of this XMLFragment within the "app" to which it belongs. The app type is an application assigned value which uniquely identifies the XML Fragment within the application's app.

Returns: normally pointer to XMLFragmentList; NULL otherwise.

Remarks: similiar to mdlXMLFragmentList_contruct, except the input is a XML Dom, rather then text string

XMLFragmentListP mdlXMLFragmentList_constructFromXMLFragmentElement ( MSElementDescrCP pDescr )

Constructs an XML Fragment List from an XML Element element descriptor.

Remarks: The element descriptor should contain a single type XML Element with XML data. (cannot handle a chain of type XML elements)

Parameters

[in] pDescr Element descriptor

Returns: normally pointer to XMLFragmentList built from element descriptor; NULL otherwise.

XMLFragmentListP mdlXMLFragmentList_constructFromXmlNode	(	XmlNodeRef	nodeRef,
		WChar *	pSchemaURN,
		UShort	appID,
		UShort	appType
	)

Constructs an XML Fragment List containing a single XML Fragment from the XMLDomNode.

Parameters

[in]	nodeRef	XML Node to create XML Fragment list from
[in]	pSchemaURN	Schema URN to set (or NULL).
[in]	appID	The ID of the "app" to which this XMLFragment belongs. The app identifier is a Bentley assigned application identifier. (typically an application's LinkageID).
[in]	appType	The type of this XMLFragment within the "app" to which it belongs. The app type is an application assigned value which uniquely identifies the XML Fragment within the application's app.

Returns: normally pointer to XMLFragmentList; NULL otherwise.

Remarks: similiar to mdlXMLFragmentList_contruct, except the input is a XML Node, rather then text string

StatusInt mdlXMLFragmentList_createFreeThreadedXmlDom	(	XmlDomRef *	pDomRef,
		XMLFragmentListP	pThis,
		WChar const *const	pRootElementName
	)

Creates a Free Threaded XML Dom from the XML FragmentList.

Parameters

[in,out]	pDomRef	Created XML DOM
[in]	pThis	XML Fragment List to create XML DOM from
[in]	pRootElementName	Name for Root Element of XML DOM

Returns: SUCCESS, ERROR or MDLERR_BADARG

See also: mdlXMLFragmentList_createXmlDom; mdlXMLDom_free

Remarks: pDomRef must be freed by calling mdlXMLDom_free; All fragments will be appended to the rootElement, as follows: &lt:RootElementName&gt: [XMLFragmentText 1 here] [XMLFragmentText 2 here] ... [XMLFragmentText n here] &lt:/RootElementName&gt:; If any of the XMLFragment Text are ill-formed XML Fragments, this function will fail.

StatusInt mdlXMLFragmentList_createXmlDom	(	XmlDomRef *	pDomRef,
		XMLFragmentListP	pThis,
		WChar const *const	pRootElementName
	)

Creates an non FreeThreaded XML Dom from the XML FragmentList.

Parameters

[in,out]	pDomRef	Created non FreeThreaded XML DOM
[in]	pThis	XML Fragment List to create XML DOM from
[in]	pRootElementName	Name for Root Element of XML DOM

Returns: SUCCESS, ERROR or MDLERR_BADARG

See also: mdlXMLFragmentList_createFreeThreadedXmlDom; mdlXMLDom_free

Remarks: pDomRef must be freed by calling mdlXMLDom_free; All fragments will be appended to the rootElement, as follows: &lt:RootElementName&gt: [XMLFragmentText 1 here] [XMLFragmentText 2 here] ... [XMLFragmentText n here] &lt:/RootElementName&gt:; If any of the XMLFragment Text are ill-formed XML Fragments, this function will fail.

StatusInt mdlXMLFragmentList_createXMLElementDescriptor	(	MSElementDescrH	ppDescr,
		XMLFragmentListP *	ppThis,
		bool	freeXMLFragmentList
	)

Creates a XMLFragment element descriptor (chain) from all entries in a XMLFragmentList.

Remarks: An element descriptor chain is created if the XMLFragmentList contains more than one list entry.

Frees the XMLFragment list entry upon successful completion, if requested.

Parameters

[out]	ppDescr	Element descriptor built from XML Fragment List. (Must be freed by caller) It is the callers responsiblity to add the element(s) to the file.
[in,out]	ppThis	XML Fragment list.
[in]	freeXMLFragmentList	Non-zero=Free XML Fragment list after operation. Only freed if function is successful.

Returns: normally SUCCESS; MDLERR_BADARG if either ppDescr or pThis pointer is invalid.

StatusInt mdlXMLFragmentList_duplicate	(	XMLFragmentListP *	ppCopy,
		XMLFragmentListP	pThis
	)

Creates a duplicate XML Fragment list from all entries in the given XML Fragment List.

Parameters

[out]	ppCopy	Duplicated XML Fragment list.
[in]	pThis	XML Fragment list to duplicate.

Returns: normally SUCCESS. MDLERR_BADARG if either ppCopy or pThis pointers is invalid. MDLERR_INSFMEMORY if failed creation of duplicate list memory.

See also: mdlXMLFragmentList_duplicateSingle

StatusInt mdlXMLFragmentList_duplicateSingle	(	XMLFragmentListP *	ppCopy,
		XMLFragmentListP	pThis
	)

Creates a duplicate XML Fragment list from only the current XML Fragment List entry.

Parameters

[out]	ppCopy	Duplicated XML Fragment list.
[in]	pThis	XML Fragment list to duplicate.

Returns: normally SUCCESS. MDLERR_BADARG if either ppCopy or pThis pointers is invalid. MDLERR_INSFMEMORY if failed creation of duplicate list memory.

See also: mdlXMLFragmentList_duplicate

StatusInt mdlXMLFragmentList_extractFromElement	(	XMLFragmentListP *	ppXMLFragmentList,
		MSElementP	pElm
	)

Retrieves a list of all XMLFragments attached to the given element descriptor.

Remarks: mdlXMLFragmentList_extractFromElement differs from mdlXMLFragmentList_constructFromXMLFragmentElement in that the former reads XML data stored as user data linkages on any dgn element and the latter constructs an XMLFragmentList from a single XMLFragment Element.

Parameters

[out]	ppXMLFragmentList	List of XML Fragments which were extracted from the element.
[in]	pElm	Element to query for XML Fragment list.

Returns: normally SUCCESS; MDLERR_BADARG if ppXMLFragmentList or pElm pointers are invalid. MDLERR_LINKAGENOTFOUND if element contains no XMLFragment attachments.

See also: mdlXMLFragmentList_extractFromElementByAppIDAndType

StatusInt mdlXMLFragmentList_extractFromElementByAppIDAndType	(	XMLFragmentListP *	ppXMLFragmentList,
		MSElementP	pElm,
		const UShort *	pAppID,
		const UShort *	pAppType
	)

Retrieves a list of XMLFragments attached to the given element descriptor using the search criteria of App ID and/or App Type.

Parameters

[out]	ppXMLFragmentList	List of XML Fragments which were extracted from the element.
[in]	pElm	Element to query for XML Fragment list.
[in]	pAppID	App ID of XML Fragments to retrieve. (or NULL if criteria not applied)
[in]	pAppType	App Type of XML Fragments to retrieve (or NULL if criteria not applied).

Returns: normally SUCCESS; MDLERR_BADARG if ppXMLFragmentList or pElm pointers are invalid. MDLERR_LINKAGENOTFOUND if element contains no attachments of the app type and/or ID.

See also: mdlXMLFragmentList_extractFromElement

StatusInt mdlXMLFragmentList_free ( XMLFragmentListP * ppThis )

Frees memory of the XML Fragment List.

Parameters

[in,out] ppThis XML Fragment list.

Returns: normally SUCCESS; MDLERR_BADARG if ppThis pointer is invalid.

UInt32 mdlXMLFragmentList_getCount ( XMLFragmentListP pThis )

Retrieves the count of XMLFragments in an XML Fragment List.

Parameters

[in] pThis List of XML Fragments.

Returns: Count of XMLFragments in the list

XMLFragmentP mdlXMLFragmentList_getXMLFragment ( XMLFragmentListP pThis )

Retrieves the first XML Fragment from the input XML Fragment List Entry.

Parameters

[in] pThis List of XML Fragments.

Returns: Pointer to the XMLFragment in the XML Fragment List entry. Note: Pointer should not be freed since it is a pointer stored within the XMLFragmentList.

Public XMLFragmentP mdlXMLFragmentList_getXMLFragmentAtIndex	(	XMLFragmentListP	pThis,
		UInt32	index
	)

Retrieves the XML Fragment from the input XML Fragment List Entry.

Remarks

Example use of mdlXMLFragmentList_getXMLFragmentAtIndex:
UInt32                     i;
UInt32                     nXMLFragmentListEntries;
StatusInt                  status;
XMLFragmentP               pXMLFragment;
XMLFragmentListP           pXMLFragmentList; // Assume list previously constructed/extracted.
nXMLFragmentListEntries = mdlXMLFragmentList_getCount (pXMLFragmentList);
for (i=0; i < nXMLFragmentListEntries; i++)
     {
     pXMLFragment = mdlXMLFragmentList_getXMLFragment (pCurrent, i);
     }

Parameters

[in]	pThis	List of XML Fragments.
[in]	index	index of XML Fragment to retrieve.

Returns: Pointer to the XMLFragment in the XML Fragment List entry. Note: Pointer should not be freed since it is a pointer stored within the XMLFragmentList.

StatusInt mdlXMLFragmentList_prepend	(	XMLFragmentListP *	ppThis,
		XMLFragmentP	pPrependFragment
	)

Prepends an XML Fragment to an XML Fragment List.

Parameters

[in,out]	ppThis	Combined list of XML Fragments.
[in]	pPrependFragment	XML Fragment to prepend. (Pointer should not be freed since it is incorporated into ppThis)

Returns: normally SUCCESS; MDLERR_BADARG if either ppThis or pPrependList pointers is invalid

StatusInt mdlXMLFragmentList_stripAllFromElement	(	XMLFragmentListP *	ppXMLFragmentList,
		MSElementP	pElm
	)

Deletes all XMLFragment attachments from the input element.

Remarks: A list of the deleted XML Fragments is returned, if requested.

Parameters

[out]	ppXMLFragmentList	List of XML Fragments which were deleted from the element. (or NULL if XMLFragmentList not required)
[in,out]	pElm	Element to delete Fragments from.

Returns: normally SUCCESS; MDLERR_BADARG if pElm is invalid

See also: mdlXMLFragmentList_stripFromElementByAppIDAndType

StatusInt mdlXMLFragmentList_stripFromElementByAppIDAndType	(	XMLFragmentListP *	ppXMLFragmentList,
		MSElementP	pElm,
		UShort *	pAppID,
		UShort *	pAppType
	)

Deletes XMLFragment attachments from the input element using the search criteria of App ID and/or App Type.

Remarks: A list of the deleted XML Fragments is returned, if requested. If both App ID and App Type are NULL, then all XML attachments are deleted from the element.

Parameters

[out]	ppXMLFragmentList	List of XML Fragments which were deleted from the element. (or NULL if XMLFragmentList not required)
[in]	pElm	Element to delete Fragment list from.
[in]	pAppID	App ID of XML Fragments to retrieve. (or NULL if criteria not applied)
[in]	pAppType	App Type of XML Fragments to retrieve (or NULL if criteria not applied).

Returns: normally SUCCESS; MDLERR_BADARG if pElm is invalid

See also: mdlXMLFragmentList_stripAllFromElement

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

API Overview