A writeable "handle" to an MSElement. More...

#include <ElementHandle.h>

Inheritance diagram for EditElementHandle:

Public Member Functions
	EditElementHandle ()
	construct a blank, invalid, EditElementHandle More...

	EditElementHandle (MSElementDescrP descr, bool owned, bool isUnmodified, DgnModelRefP modelRef=0)
	Construct an ElementHandle from an MSElementDescr. More...

	EditElementHandle (ElementRefP elRef, DgnModelRefP modelRef=0)
	Construct an ElementHandle from an ElementRefP and a DgnModelRefP. More...

	EditElementHandle (MSElementCP el, DgnModelRefP modelRef)
	Construct an ElementHandle from an MSElement and a DgnModelRef. More...

	EditElementHandle (ElementId id, DgnModelRefP modelRef)
	Construct an ElementHandle from an ElementId and a DgnModelRefP. More...

	EditElementHandle (ElementHandleCR from, bool duplicateDescr)
	Construct an ElementHandle from another element handle. More...

void	Duplicate (ElementHandleCR)
	Duplicate the element descriptor and its scheduled XAttribute changes. More...

void	SetModelRef (DgnModelRefP modelRef)
	Change the DgnModelRef for this EditElementHandle. More...

void	SetNonPersistent ()
	Turn off the "IsUnmodified" flag for this EditElementHandle. More...

void	Invalidate ()
	Mark this EditElementHandle as invalid. If there is an MSElementDescr associated with this EditElementHandle, it is freed. More...

void	SetIElementState (IElementStateP state)

IElementStateP	GetIElementState ()

Element Data
MSElementDescrP	GetElementDescrP ()
	Get a writable MSElementDescr from this EditElementHandle. More...

MSElementP	GetElementP ()
	Get a pointer to a writeable MSElement from this EditElementHandle. More...

StatusInt	ReplaceElement (MSElementCP el)
	Replace the element associated with this EditElementHandle with a new element. More...

StatusInt	ReplaceElementDescr (MSElementDescrP elDscr)
	Replace the MSElementDescr associated with the EditElementHandle with a new MSElementDescr. More...

MSElementDescrP	ExtractElementDescr ()
	Extract and take ownership of the MSElementDescr associated with this EditElementHandle. More...

void	SetElementDescr (MSElementDescrP elDscr, bool owned, bool isUnmodified, DgnModelRefP modelRef=0)
	Assign a new MSElementDescr to this EditElementHandle. More...

void	SetElementRef (ElementRefP elRef, DgnModelRefP modelRef)
	Change the ElementRefP and DgnModelRef for this EditElementHandle. More...

XAttribute Changes
StatusInt	ScheduleWriteXAttribute (XAttributeHandlerIdCR h, UInt32 xAttrId, size_t dataSize, void const *data)
	Schedule the specified XAttribute to be written to the MSElementDescr. More...

StatusInt	CancelWriteXAttribute (XAttributeHandlerIdCR h, UInt32 xAttrId)
	Cancel out the effects of a prior call to ScheduleWriteXAttribute. More...

StatusInt	ScheduleDeleteXAttribute (XAttributeHandlerIdCR h, UInt32 xAttrId)
	Schedule removal of the specified XAttribute from the MSElementDescr. More...

StatusInt	CancelDeleteXAttribute (XAttributeHandlerIdCR h, UInt32 xAttrId)
	Cancel out the effects of a prior call to ScheduleDeleteXAttribute. More...

Read from model
StatusInt	FindByID (ElementId elemID, DgnModelP dgnCache, bool allowDeleted=false)

StatusInt	FindByID (ElementId elemID, DgnModelRefP modelRef, bool allowDeleted=false)

Write changes to a Model
StatusInt	AddToModel ()
	Add this EditElementHandle to the associated model. More...

StatusInt	DeleteFromModel ()
	Delete this EditElementHandle from its model. More...

StatusInt	ReplaceInModel (ElementRefP oldRef)
	Replace the element referred to by the supplied ElementRefP with the modified MSElementDescr held by this EditElementHandle. More...

Element Linkages
ElementLinkageIterator	BeginElementLinkages (UInt16 rl=0)
	Get an iterator over the element's user data linkages. More...

ElementLinkageIterator	EndElementLinkages ()
	Get an iterator that marks the end of the element's user data linkages. More...

StatusInt	ReplaceElementLinkage (ElementLinkageIteratorR it, LinkageHeader const &newLinkageHeader, void const *newLinkageData)
	Replace an element data linkage on this element. More...

StatusInt	RemoveElementLinkage (ElementLinkageIteratorR it)
	Remove an element data linkage from this element. More...

StatusInt	InsertElementLinkage (ElementLinkageIterator newLinkageIt, LinkageHeaderCR newLinkageHeader, void const newLinkageData, ElementLinkageIterator &wh, UInt16 rl=0)
	Add a new element data linkage to this element. More...

StatusInt	AppendElementLinkage (ElementLinkageIterator newLinkageIt, LinkageHeaderCR newLinkageHeader, void const newLinkageData)
	Appends a new element data linkage to the end of this element. More...

Public Member Functions inherited from ElementHandle
	ElementHandle ()
	construct a blank, invalid, ElementHandle More...

	~ElementHandle ()

	ElementHandle (ElementRefP elRef, DgnModelRefP modelRef=0)
	Construct an ElementHandle from an ElementRefP and a DgnModelRefP. More...

	ElementHandle (ElementId id, DgnModelRefP modelRef)
	Construct an ElementHandle from an ElementId and a DgnModelRefP. More...

	ElementHandle (MSElementDescrCP elDscr, bool owned, bool isUnmodified=false, DgnModelRefP modelRef=0)
	Construct an ElementHandle from an MSElementDescr. More...

	ElementHandle (MSElementCP el, DgnModelRefP modelRef)
	Construct an ElementHandle from an MSElement and a DgnModelRef. More...

	ElementHandle (ElementHandleCR from)
	Copy an ElementHandle. More...

ElementId	GetElementId () const
	Get the element ID of the element contained in the ElementHandle. More...

void	ResetHandler () const

Handler &	GetHandler (MissingHandlerPermissions perm=MISSING_HANDLER_PERMISSION_None) const
	Get the Handler for this ElementHandle. More...

DisplayHandlerP	GetDisplayHandler () const
	A shortcut method to get a DisplayHandler pointer for the Handler of this ElementHandle, or NULL if the element's Handler does not derive from DisplayHandler. More...

IDependencyHandlerP	GetIDependencyHandler () const
	A shortcut method to get the IDependencyHandler interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface. More...

ITransactionHandlerP	GetITransactionHandler () const
	A shortcut method to get the ITransactionHandler interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface. More...

ITextQueryCP	GetITextQuery () const
	A shortcut method to get the ITextQuery interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface. More...

ITextEditP	GetITextEdit () const
	A shortcut method to get the ITextEdit interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface. More...

ElementRefP	GetElementRef () const
	Get the ElementRefP for this ElementHandle. More...

DgnModelP	GetDgnModelP () const
	Get a DgnModelP for this ElementHandle. More...

DgnFileP	GetDgnFileP () const
	Get the DgnFile of the DgnModel for this ElementHandle. More...

DgnModelRefP	GetModelRef () const
	Get the DgnModelRef for this ElementHandle. More...

MSElementCP	GetElementCP () const
	Get a const pointer to the MSElement associated with this ElementHandle. More...

bool	IsValid () const
	Determine whether this ElementHandle is currently valid. More...

bool	IsPersistent () const
	Determine whether this ElementHandle references an unmodified element in the cache. More...

int	GetElementType () const
	Get the element type of the element referenced by this ElementHandle. More...

void	GetElementHeader (Elm_hdr &hdr) const
	Get a copy of the Elm_hdr of the element referenced by this ElementHandle. More...

MSElementDescrCP	PeekElementDescrCP () const
	Peek to see whether this ElementHandle currently has an MSElementDescr. More...

MSElementDescrCP	GetElementDescrCP () const
	Get an MSElementDescrCP from this ElementHandle. More...

ConstElementLinkageIterator	BeginElementLinkages (UInt16 rl=0) const
	Get an iterator over the element's user data linkages. More...

ConstElementLinkageIterator	EndElementLinkages () const
	Get an iterator that marks the end of the element's user data linkages. More...

Detailed Description

A writeable "handle" to an MSElement.

EditElementHandle is the ideal means of passing an element to functions, when the functions might modify the element. EditElementHandle is also useful for creating and adding new elements and for deleting existing elements.

EditElementHandle, MSElementDescrP, and ElementRefP

Like an ElementHandle, an EditElementHandle can hold either an ElementRefP or an MSElementDescrP in order to represent an element. Unlike ElementHandle, an EditElementHandle can be used to change the modified and persistent state of its element and will will change its internal representation accordingly.

EditElementHandle is often set up to take ownership of an underlying MSElementDescrP. This feature allows EditElementHandle, like ElementHandle, to serve as a smart pointer. As a read/write handle, EditElementHandle is also well suited for cases where the underlying MSElementDescrP pointer must be reallocated. Use of EditElementHandle makes for cleaner, simpler, more reliable code and is preferable to MSElementDescrH.

Common Use

Some common workflows involving an EditElementHandle are:

Create New Element

Creating a new element involves setting up an element descriptor in memory and then writing it to a cache. The handle ends up holding the new ElementRefP that represents the newly created element.

// Create the element data
MSElementDescrP elementDescriptor = ...
//  Set up handle to a new, non-persistent element descriptor
//  Note that the handle takes ownership of the descriptor.
EditElementHandle eh (elementDescriptor, true, true);
//  Append the element to a cache.
//  Note: AddToModel assigns an ElementRefP to the element.
//        It switches the handle's internal representation to use the ElementRefP and frees the original descriptor.
if (SUCCESS != eh.AddToModel ())
    error!
else
    {
    BeAssert (eh.GetElementRef () != NULL);
    BeAssert (eh.IsPersistent());
    BeAssert (eh.PeekElementDescrCP() == NULL);    // The original descriptor has been discarded and freed!
    }

Modify Existing Element

The modification scenario starts with an existing, unmodified element. The modification logic will normally work on an element descriptor. The handle then shifts to holding the modified descriptor. After writing the modified descriptor back to its cache, then handle switches back to representing an existing, unmodified element.

// Get a reference to the element
ElementRefP elementRef = ...
//  Set up handle to an existing, persistent element
EditElementHandle eh (elementRef, modelRef);
elementRef = NULL;
//  If you really want to get the ElementRefP, get it from the descriptor:
// eh.GetElementDescrCP()->h.elementRef
//  Modify the element's data in some way, e.g., by calling a Handler method
eh.GetHandler().SomeModificationMethod (eh);
...
//  Write the changes
//  Note: ReplaceInModel may possibly move the ElementRefP if the element changes in size.
//        ReplaceInModel switches the handle's internal representation to use the (updated) ElementRefP and frees the original descriptor.
if (eh.ReplaceInModel (oldRef) != SUCCESS)
    error!
else
    {
    BeAssert (eh.GetElementRef () != NULL);
    BeAssert (eh.IsPersistent());
    // NB: eh.GetElementRef() may not equal the original elementRef!
    }

Use Legacy Code to Modify an Element Descriptor

Legacy code often works with element descriptors. This shows how to use the ExtractElementDescr method in order to hand off a descriptor and manage its lifecycle.

//  Set up handle to an existing, persistent element
EditElementHandle eh (elementRef, modelRef);
//  Call legacy code, which will operate on an element descriptor.
//  In this case the legacy code may reallocate the descriptor.
eh.GetElementDescrP ();                            // Cause the handle to create and hold a descriptor.
MSElementDescrP ed = eh.ExtractElementDescr ();    // take ownership of descriptor away from eh
legacyFunction (&ed, ...);                      // legacy code modifies the naked descriptor
eh.SetElementDescr (ed, true, false);              // return ownership of descriptor to eh
ed = NULL;
//  Write the changes
if (eh.ReplaceInModel (oldRef) != SUCCESS)
    error!
else
    {
    BeAssert (eh.GetElementRef () != NULL);
    BeAssert (eh.IsPersistent());
    }

The Persistent and Unmodified State

Applications that work with legacy code may have to understand and even manage a handle's internal state. When following the common use scenarios above, an application can use an EditElementHandle without worrying too much about whether the handle contains an ElementRefP or an MSElementDescrP or whether the descriptor's elementRef field is valid or not. The EditElementHandle's state logic can manage this data in most cases. If the application follows a different workflow, however, it might have to control this information in the handle.

An EditElementHandle can represent an element in three possible states:

Persistent and unmodified. MicroStation will assume that the EditElementHandle's ElementRefP represents the correct state of the element's data. The GetElementRef method will return non-null only in this state. The IsPersistent method will return true only in this state. Most of the time, the handle will contain only an ElementRefP in this state. In rare situations involving legacy code, the handle may contain both an ElementRefP and an element descriptor.
Persistent and modified. MicroStation will assume that the EditElementHandle's ElementRefP does not reflect the element's current state. GetElementRef will return NULL and IsPersistent will return false in this state, even if the descriptor has its h.elementRef field set up. This is to remind you to look in the descriptor for the element's data.
Non-persistent. The EditElementHandle contains only an element descriptor.

Applications can control an EditElementHandle's persistent status by means of the isUnmodified argument to the element descriptor constructor and the SetElementDescr method. Normally, isUnmodified is set to false. That is, if you are setting up an EditElementHandle from a descriptor, you are probably creating a new element or have modified its data. If you want to represent a persistent, unmodified element, the preferred method is to specify an ElementRefP. When using legacy code, however, an application might possibly start by reading a persistent element into an element descriptor. If the application then wants to switch over to using an EditElementHandle, it can pass isUnmodified = true. That will cause the EditElementHandle to adopt the descriptor's ElementRefP and also to hold the descriptor pointer. The following example shows how to create a persistent and unmodified handle that also acts as a smart pointer.

    EditElementHandle eh (elementDescriptor, true, true);
    ...
    ... eh.GetElementDescrP ();    // already has a descriptor, so no need to read it
    ... eh.GetElementRef ();       // also has an ElementRefP

    // eh will free elementDescriptor

Scheduling XAttribute Changes

You can use EditElementHandle to add, replace, or delete an element's XAttributes. Unlike XAttrIO, EditElementHandle schedules XAttribute changes. Scheduled changes are written to the cache when you rewrite the handle's underlying MSElementDescr (e.g., by using the AddToModel or ReplaceInModel methods).

The XAttributeChangeIter class can be used to inspect scheduled changes.

The ElementHandle::XAttributeIter class can be used to iterate XAtttributes on an element, taking scheduled changes into account.

Remarks: Required library : DgnPlatform<ApiNumber>.lib i.e. DgnPlatform5.lib

Constructor & Destructor Documentation

EditElementHandle ( )

construct a blank, invalid, EditElementHandle

EditElementHandle	(	MSElementDescrP	descr,
		bool	owned,
		bool	isUnmodified,
		DgnModelRefP	modelRef = `0`
	)

Construct an ElementHandle from an MSElementDescr.

See also: ElementHandle::ElementHandle

EditElementHandle	(	ElementRefP	elRef,
		DgnModelRefP	modelRef = `0`
	)

Construct an ElementHandle from an ElementRefP and a DgnModelRefP.

See also: ElementHandle::ElementHandle

EditElementHandle	(	MSElementCP	el,
		DgnModelRefP	modelRef
	)

Construct an ElementHandle from an MSElement and a DgnModelRef.

See also: ElementHandle::ElementHandle

EditElementHandle	(	ElementId	id,
		DgnModelRefP	modelRef
	)

Construct an ElementHandle from an ElementId and a DgnModelRefP.

Parameters

[in]	id	The ElementId of the element for this ElementHandle.
[in]	modelRef	The DgnModelRefP used to access the element.

Remarks: NOTE: test IsValid to determine whether the element was found!

EditElementHandle	(	ElementHandleCR	from,
		bool	duplicateDescr
	)

Construct an ElementHandle from another element handle.

Parameters

[in]	from	The other ElementHandle.
[in]	duplicateDescr	True if the new ElementHandle should duplicate the internal descriptor. If the element handles are to be modified seperately then this should be set.

Member Function Documentation

StatusInt AddToModel ( )

Add this EditElementHandle to the associated model.

The addition is via the current transaction (see ITxn::AddElement) and is always undoable.

Returns: SUCCESS if the element was added to its model. This method will fail if there is no MSElementDescr for this EditElementHandle, or if the MSElementDescr is not owned by this EditElementHandle, or if this EditElementHandle is not associated with a model.

Remarks: This method is just a wrapper for: return ITxnManager::GetCurrentTxn().AddElement (*this);; After the element is successfully added to the model, the ElementRefP of this EditElementHandle is set and the MSElementDescr is freed.

StatusInt AppendElementLinkage	(	ElementLinkageIterator *	newLinkageIt,
		LinkageHeaderCR	newLinkageHeader,
		void const *	newLinkageData
	)

Appends a new element data linkage to the end of this element.

Parameters

[out]	newLinkageIt	Points to new linkage on the element
	newLinkageHeader	new linkdage header (copied).
	newLinkageData	new linkdage data (copied).

Remarks: You must call LinkageUtil::SetWords on the new linkage header in order to record the total size of the new linkage (header and data) before passing it into this function.; newLinkageData is copied to the location immediately following the new linkage header on the element. No alignment padding is inserted between the two.

ElementLinkageIterator BeginElementLinkages ( UInt16 rl = 0 )

Get an iterator over the element's user data linkages.

Parameters

rl	Linkage ID filter value identifies the linkages of interest. Defaults to all linkages.

StatusInt CancelDeleteXAttribute	(	XAttributeHandlerIdCR	h,
		UInt32	xAttrId
	)

Cancel out the effects of a prior call to ScheduleDeleteXAttribute.

Parameters

[in]	h	XAttributeHandler ID
[in]	xAttrId	XAttribute ID

Returns: non-zero error status if the XAttribute was not scheduled for deletion

StatusInt CancelWriteXAttribute	(	XAttributeHandlerIdCR	h,
		UInt32	xAttrId
	)

Cancel out the effects of a prior call to ScheduleWriteXAttribute.

Parameters

[in]	h	XAttributeHandler ID
[in]	xAttrId	XAttribute ID

Returns: non-zero error status if the XAttribute was not scheduled for write

StatusInt DeleteFromModel ( )

Delete this EditElementHandle from its model.

The delete is via the current transaction (see ITxn::DeleteElement) and is always undoable. The deletion is via the current transaction (see ITxn::DeleteElement) and is always undoable.

Returns: SUCCESS if the element was deleted from the model.

Remarks: After the element is successfully deleted from the model, this EditElementHandle becomes invalid (see IsValid).

void Duplicate ( ElementHandleCR )

Duplicate the element descriptor and its scheduled XAttribute changes.

ElementLinkageIterator EndElementLinkages ( )

Get an iterator that marks the end of the element's user data linkages.

MSElementDescrP ExtractElementDescr ( )

Extract and take ownership of the MSElementDescr associated with this EditElementHandle.

Returns: The MSElementDescrP from the EditElementHandle. The MSElementDescr is no longer associated with the EditElementHandle, and the caller is responsible for freeing it.

Remarks: This method will fail if there is no "owned" MSElementDescr already associated with this EditElementHandle.; This method should not be called on a ChildEditElemIter.

StatusInt FindByID	(	ElementId	elemID,
		DgnModelP	dgnCache,
		bool	allowDeleted = `false`
	)

StatusInt FindByID	(	ElementId	elemID,
		DgnModelRefP	modelRef,
		bool	allowDeleted = `false`
	)

MSElementDescrP GetElementDescrP ( )

Get a writable MSElementDescr from this EditElementHandle.

If this EditElementHandle does not already have an MSElementDescr, allocate one using the ElementRefP/DgnModelRef.

Remarks: Use PeekElementDescrCP to see whether this EditElementHandle already has an MSElementDescr.; This method returns a pointer to the MSElementDescr in the EditElementHandle. It is still owned by the EditElementHandle and must not be freed by the caller.

MSElementP GetElementP ( )

Get a pointer to a writeable MSElement from this EditElementHandle.

Remarks: The element will be the "el" member of the MSElementDescr for this EditElementHandle. Therefore, it is not valid to modify the size of the element through this pointer. To do that, use ReplaceElement.; If this EditElementHandle does not already have an MSElementDescr, one will be allocated by this call.

References NULL.

IElementStateP GetIElementState ( )

StatusInt InsertElementLinkage	(	ElementLinkageIterator *	newLinkageIt,
		LinkageHeaderCR	newLinkageHeader,
		void const *	newLinkageData,
		ElementLinkageIterator &	wh,
		UInt16	rl = `0`
	)

Add a new element data linkage to this element.

Parameters

[out]	newLinkageIt	Points to new linkage on the element
	newLinkageHeader	new linkdage header (copied).
	newLinkageData	new linkdage data (copied).
	wh	where the new linkage should be inserted into the element's linkage data area. Pass EndElementLinkages() to append. Pass BeginElementLinkages() to insert before all existing linkages. Otherwise, pass an iterator that identifies an existing linkage, and this function will insert the new linkage before it.
	rl	Linkage ID filter value to assign to newLinkageIt. Defaults to all linkages.

Remarks: You must call LinkageUtil::SetWords on the new linkage header in order to record the total size of the new linkage (header and data) before passing it into this function.; newLinkageData is copied to the location immediately following the new linkage header on the element. No alignment padding is inserted between the two.

void Invalidate ( )

Mark this EditElementHandle as invalid. If there is an MSElementDescr associated with this EditElementHandle, it is freed.

StatusInt RemoveElementLinkage ( ElementLinkageIteratorR it )

Remove an element data linkage from this element.

When this function is called during the iterator, the resulting iterator will point to the next element, and should not be incremented. For example:

for (ElementLinkageIterator li = element.BeginElementLinkages(); li != element.EndElementLinkages(); )  // Incremented below
    {
    if (NeedsToBeDeleted)
       element.RemoveElementLinkage (li);
    else
       ++li;
    }

Parameters

it	The linkage that is to be removed

StatusInt ReplaceElement ( MSElementCP el )

Replace the element associated with this EditElementHandle with a new element.

Parameters

[in] el The new element. The element is copied from this buffer and allocated in a new MSElementDescr.

StatusInt ReplaceElementDescr ( MSElementDescrP elDscr )

Replace the MSElementDescr associated with the EditElementHandle with a new MSElementDescr.

Parameters

[in] elDscr The new MSElementDescr to be associated with the EditElementHandle. After this call, elDscr becomes owned by this EditElementHandle.

Returns: SUCCESS if the MSElementDescr was successfully replaced by elDscr, ERROR otherwise.

Remarks: This method will fail if the MSElementDescr is not "owned" by this EditElementHandle.; If the DgnModelRef in elDscr is NULL, the value from the existing MSElementDescr is copied into elDscr.

StatusInt ReplaceElementLinkage	(	ElementLinkageIteratorR	it,
		LinkageHeader const &	newLinkageHeader,
		void const *	newLinkageData
	)

Replace an element data linkage on this element.

Parameters

it	The linkage that is to be replaced
newLinkageHeader	new linkdage header (copied).
newLinkageData	new linkdage data (copied).

Returns: non-zero error status if the maximum element size would be exceeded

Remarks: You must call LinkageUtil::SetWords on the new linkage header in order to record the total size of the new linkage (header and data) before passing it into this function.; newLinkageData is copied to the location immediately following the new linkage header on the element. No alignment padding is inserted between the two.

StatusInt ReplaceInModel ( ElementRefP oldRef )

Replace the element referred to by the supplied ElementRefP with the modified MSElementDescr held by this EditElementHandle.

The replacement is via the current transaction (see ITxn::ReplaceElement) and is always undoable.

Parameters

[in] oldRef Element to replace.

Returns: SUCCESS if the element was replaced in the model. This method will fail if there is no MSElementDescr for this EditElementHandle.

Remarks: After the element is successfully replaced in the model, the ElementRefP of this EditElementHandle is updated with the (potentially new) ElementRefP of replaced element and the MSElementDescr is freed.

StatusInt ScheduleDeleteXAttribute	(	XAttributeHandlerIdCR	h,
		UInt32	xAttrId
	)

Schedule removal of the specified XAttribute from the MSElementDescr.

Parameters

[in]	h	XAttributeHandler ID
[in]	xAttrId	XAttribute ID

Returns: non-zero error status if the change cannot be scheduled. Normally, this would only happen in an out-of-memory situation.

Remarks: If the XAttribute was previously scheduled for write, this request to delete the XAttribute cancels the previous write request and schedules the XAttribute to be deleted instead.; If the XAttribute was previously scheduled for delete, this request effectively does nothing; the XAttribute will remain scheduled for deletion.

StatusInt ScheduleWriteXAttribute	(	XAttributeHandlerIdCR	h,
		UInt32	xAttrId,
		size_t	dataSize,
		void const *	data
	)

Schedule the specified XAttribute to be written to the MSElementDescr.

Remarks: This function makes a copy of data

Parameters

[in]	h	XAttributeHandler ID
[in]	xAttrId	XAttribute ID
[in]	dataSize	Number of bytes of data in XAttribute data
[in]	data	XAttribute data

Returns: non-zero error status if the change cannot be scheduled. Normally, this would only happen in an out-of-memory situation.

Remarks: EditElementHandle does not distinguish between adding a new XAttribute and replacing the value of an existing XAttribute. In both cases, you call ScheduleWriteXAttribute. If you have an ElementRefP, you can use the XAttributeHandle class to test if an XAttribute exists or not.
// Example of how to add an element with XAttributes to a cache

EditElementHandle eh;

eh.SetElementDescr ( ... );

...

eh.ScheduleWriteXAttribute (myXaHandlerId, xaIndex, nbytes, xaBytes);

...

eh.AddToModel (); // adds the element and the XAttribute to the active model cache; If the XAttribute was previously scheduled for write or delete, this request to write the specified data supercedes the previous request and schedules the specified data for write instead.

void SetElementDescr	(	MSElementDescrP	elDscr,
		bool	owned,
		bool	isUnmodified,
		DgnModelRefP	modelRef = `0`
	)

Assign a new MSElementDescr to this EditElementHandle.

The existing MSElementDescr (if present) is freed.

Remarks: This method should not be called on a ChildEditElemIter.

See also: ReplaceElementDescr.

Parameters

[in]	elDscr	MSElementDescr to be referenced by this ElementHandle.
[in]	owned	If true, destructor will free elDscr. Otherwise, caller maintains ownership of elDscr.
[in]	isUnmodified	If true, elDscr is an exact image of the element in the cache.
[in]	modelRef	Will be used if elDscr.h.dgnModelRef is NULL.