An XAttribute is data that is stored on an element, not in an element. More...


struct  XAttributeHandle
 A "handle" that can be used to access a single XAttribute of a persistent element. More...
struct  XAttributeCollection
 An collection that can be used to iterate over the XAttributes of a persistent element. More...
struct  ITxn
 The interface to write changes in the context of a transaction to elements, XAttributes, and models. More...
struct  IReplaceXAttribute
 Interface to the helper object passed to the XAttributeHandler::OnPreprocessCopy and IXAttributePointerContainerHandler::OnPreprocessCopyRemapIds methods. More...
struct  IDependencyHandler
 An element Handler should implement this interface if it wants to know when elements referenced by its XAttributes have changed. More...

Detailed Description

An XAttribute is data that is stored on an element, not in an element.

An XAttribute is not part of the element's data (that is, visible through an MSElement). By way of contrast, a user data linkage is part of an element's data.

XAttributes Vs. Linkages

Both XAttributes and Linkages provide a way for applications to persistently store additional variable length data with an element. The primary distinction between XAttributes and Linkages is that XAttributes can be accessed (read/written) independently of one another and independent of the element data. Linkages, on the other hand, can only be accessed by reading and writing the entire element (that is, the element's data plus all Linkages) together. Also, there is a maximum size for an element's data plus all it's linkgages (MAX_ELEMENT_SIZE.) There is no absolute maximum size for an individual XAttribute, nor is there a limit on the number of XAttributes per element.

Generally speaking, XAttributes and Linkages are substitutable concepts. That is, any place where you can use a Linkage, you can use an XAttribute. However, XAttributes are generally preferable for the reasons stated above (independent access and lack of size limitations), with the caveat that XAttributes are not supported on older versions of MicroStation.

Identifying XAttributes

XAttributes are stored on an element and are always referenced within the context of that element. Within a single element, XAttributes are identified by two parts: an XAttributeHandlerId and an XAttributeId. The XAttributeHandlerId specifies the "type" of the XAttribute, and designates the XAttributeHandler that, if present, will handle events for the XAttribute. A single element may contain XAttributes with many differnet XAttributeHandlerIds. However, all of the XAttributes on an element that have the same XAttributeHandlerId must have a unique XAttributeId. It should be obvious though that multiple XAttributes on the same element may have the same XAttributeId if they have different XAttributeHandlerIds.

Accessing XAttributes

The XAttributes of an element are accessed through an XAttributeHandle. The methods on XAttributeHandle provide access to the information in an XAttribute. An XAttributeHandle can be constructed from an ElementRefP, XAttributeHandlerId, and XAttributeId, or by using an XAttributeCollection::const_iterator (which is a subclass of XAttributeHandle) to step through the individual XAttributes of an element. NOTE: Any additions or deletions of XAttributes to an element will invalidate all existing XAttributeHandles for that element.

See ElementHandle::XAttributeIter for an XAttribute iterator that takes scheduled changes into account.

Modifying XAttributes

Generally, XAttributes are added, modified, or removed from an existing element via its ElementRefP, using the XAttribute methods in the Transaction Manager, Bentley::DgnPlatform::ITxnManager. The Transaction Manager guarantees that all element changes are properly journalled so that if the changes are reversed via an Undo, the previous state of all changed elements, including XAttribute data, are reinstated together. See Bentley::DgnPlatform::ITxn::AddXAttribute, etc.

However, sometimes it is necessary to store changes to XAttribute data in memory alongside the changes to the element data. For example, when constructing new elements, there is no ElementRefP yet to hold the XAttribute. For this purpose, you can "schedule" XAttribute changes via methods on EditElementHandle. These changes are stored with the element when and if the modifications in the EditElementHandle are committed.

See also
EditElementHandle::ScheduleWriteXAttribute and EditElementHandle::ScheduleDeleteXAttribute.

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.