Typedefs | Functions
Element Depencency C Api

Typedefs

typedef struct mdlDesc MdlDesc
 
typedef StatusInt(* DependencyProcessingCallback )(DgnPlatform::ElementId dependentID, DgnModelRefP modelRef, DgnPlatform::DependencyLinkage *pLinkage, UChar *pRootStatus, UChar selfStatus)
 UserFunction called by mdlDependency_processAffected when a dependent element is affected by changes to root elements. More...
 
typedef void(* DependencyProcessingCallbackForUndoRedo )(DgnPlatform::ElementId dependentID, DgnModelRefP modelRef, DgnPlatform::DependencyLinkage *pLinkage, UChar *pRootStatus, UChar selfStatus)
 Callback to be invoked whenever changes affecting a dependent element are undone or redone. More...
 
typedef void(* DependencyProcessingCallbackForLoad )(DgnPlatform::ElementId dependentID, DgnModelRefP modelRef, DgnPlatform::DependencyLinkage *pLinkage, bool futureUse)
 Callback to be invoked whenever an element carrying the specifying dependency linkage is loaded. More...
 

Functions

StatusInt mdlDependency_registerCallback (UShort appID, MdlDesc *pMdlDescr, DependencyProcessingCallback func)
 Register a callback to be invoked whenever MDL detects changes that affect elements with a DgnPlatform::DependencyLinkage having the specified appID. More...
 
StatusInt mdlDependency_getCallback (MdlDesc **ppMdlDescr, DependencyProcessingCallback *pFunc, UShort appID)
 Get the current callback that is registered to handle dependencies with the specified appID. More...
 
void mdlDependency_removeCallback (UShort appID)
 Un-register the current callback for dependencies having the specified appID. More...
 
StatusInt mdlDependency_registerCallbackForUndoRedo (UShort appID, MdlDesc *pDesc, DependencyProcessingCallbackForUndoRedo func)
 Register a callback to be invoked whenever changes affecting a dependent element are undone or redone. More...
 
StatusInt mdlDependency_getCallbackForUndoRedo (MdlDesc **ppMdlDescr, DependencyProcessingCallbackForUndoRedo *pFunc, UShort appID)
 Get the current callback that is registered to handle dependencies with the specified appID for undo/redo purposes. More...
 
void mdlDependency_removeCallbackForUndoRedo (UShort appID)
 Un-register the current callback for dependencies having the specified appID for undo/redo purposes. More...
 
StatusInt mdlDependency_registerCallbackForLoad (UShort appID, MdlDesc *pDesc, DependencyProcessingCallbackForLoad func)
 Register a callback to be invoked whenever an element carrying the specifying dependency linkage is loaded or unloaded. More...
 
StatusInt mdlDependency_getCallbackForLoad (MdlDesc **ppMdlDescr, DependencyProcessingCallbackForLoad *pFunc, UShort appID)
 Get the current load/unload callback for this appID. More...
 
void mdlDependency_removeCallbackForLoad (UShort appID)
 Un-register the current load/unload callback for this appID. More...
 
DgnPlatform::DependencyStatus mdlDependency_processAffected ()
 This function invokes callbacks on all dependent elements affected by changes to root elements since the last call to this function. More...
 
void mdlDependency_rootChanged (ElementRefP root)
 Declare that the specified root is changed and its dependents should be notified. More...
 
bool mdlDependency_wasAdded (ElementRefP ref)
 Query if the specified element is new. More...
 
void mdlDependency_setProcessingDisabled (bool bSuppress)
 Disable or enable post-processing of affected dependent elements. More...
 
int mdlDependency_getProcessingDisabled (void)
 Query if processing of affected elements has been disabled. More...
 
void mdlDependency_setIgnoreMissingCallbacks (bool b)
 Set the policy for what post-processing should do when a dependent element requires an application to process root changes, but the callback is not currently registered. More...
 
bool mdlDependency_getIgnoreMissingCallbacks (void)
 Query the policy for what to do when a dependent element requires an application to process root changes, but the callback is not not currently registered. More...
 
StatusInt mdlDependency_initLinkage (DgnPlatform::DependencyLinkage *pLinkage, UShort appID, int dataType, int copyOptions)
 This is a convenience function to initialize a DgnPlatform::DependencyLinkage. More...
 
StatusInt mdlDependency_appendLinkage (MSElementP pEl, DgnPlatform::DependencyLinkage *pLinkage)
 This function adds the specified DgnPlatform::DependencyLinkage to an element. More...
 
StatusInt mdlDependency_appendLinkageEx (MSElementP pEl, DgnPlatform::DependencyLinkage *pLinkage, int xtrabytes)
 This function adds the specified DgnPlatform::DependencyLinkage to an element. More...
 
StatusInt mdlDependency_appendLinkageUsingDescr (MSElementDescrH ppEd, DgnPlatform::DependencyLinkage *pLinkage, int xtrabytes)
 Add DgnPlatform::DependencyLinkage to an element descriptor. More...
 
int mdlDependency_deleteLinkage (MSElementP pEl, UShort appID, UShort appValue)
 Remove DependencyLinkages from an element. More...
 
StatusInt mdlDependency_updateLinkage (MSElementP pEl, DgnPlatform::DependencyLinkage *pDep, int xtrabytes)
 Update a DependencyLinkages on an element. More...
 
StatusInt mdlDependency_getLinkage (DgnPlatform::DependencyLinkage *pLinkage, size_t maxSize, MSElementCP pEl, UShort appID, UShort appValue)
 Retrieve the DgnPlatform::DependencyLinkage on the specified element with matching appID and type. More...
 
StatusInt mdlDependency_getLinkageEx (DgnPlatform::DependencyLinkage *pDependencyLinkage, DgnPlatform::DependencyLinkage **ppDependencyLinkageInplace, size_t *pDependencyLinkageSize, size_t maxSize, MSElementCP pEl, UShort appID, UShort appValue)
 Retrieve the DgnPlatform::DependencyLinkage on the specified element with matching appID and type. More...
 
DgnPlatform::DependencyLinkage * mdlDependency_bufferFromFileFormat (LinkageHeaderP pHeader)
 Memory format DgnPlatform::DependencyLinkage from the specified user data linkage. More...
 
DgnPlatform::DependencyLinkage * mdlDependency_bufferToFileFormat (LinkageHeaderP pHeader)
 File format DgnPlatform::DependencyLinkage from the specified user data linkage. More...
 
size_t mdlDependency_sizeof (DgnPlatform::DependencyLinkage *pDep, int xtrabytes)
 Get the stored size of the specified dependency linkage. More...
 
int mdlDependency_getDependentElementRefs (ElementRefP *pDependents, DgnPlatform::ElementId rootElemId, DgnModelRefP rootModelRef, int maxDependents)
 This function returns a list of ElementRefs that depend on the specified element. More...
 
int mdlDependency_getNumOfDependents (DgnPlatform::ElementId rootElemId, DgnModelRefP modelRef)
 This function returns a number of the elements that depend on the specified element. More...
 
void mdlDependency_setTraceLevel (int traceLevel)
 For debugging purposes only: More...
 
void mdlDependency_fmtRoot (WStringR buf, DgnModelRefP modelRef, DgnPlatform::DependencyLinkage *pLinkage, int iRoot)
 Formats the specified root in the specified linkage for display in a debugging message. More...
 
unsigned mdlDependency_getRoots (DgnPlatform::DependencyRoot *pRoots, DgnModelRefP modelRef, DgnPlatform::DependencyLinkage *pDep, int iRoot)
 This function returns a list of root elements on which the specified item in a dependency linkage depends. More...
 
StatusInt mdlDependency_setRoots (DgnPlatform::DependencyLinkage *pDep, DgnModelRefP modelRef, const DgnPlatform::DependencyRoot *pRoots, int iRoot)
 This function updates the roots identified by the specified item in the dependency linkage. More...
 
int mdlDependency_addSimpleDependencyLinkageToDescr (MSElementDescrH nodeEdPP, UShort appId, UShort appValue, int copyOption, DgnPlatform::ElementId uniqueId)
 This function creates a simple dependency linkage on an element descr. More...
 
StatusInt mdlDependencyAssoc1_fromAssocAndSubtype (DgnPlatform::DependencyLinkage *dl, int iRoot, DgnPlatform::AssocPoint const *assocPoint, int assoc1Subtype)
 Define an DEPENDENCY_DATA_TYPE_ASSOC1_I dependency linkage root to capture the state of the specified DgnPlatform::AssocPoint. More...
 
StatusInt mdlDependencyAssoc1_fromAssoc (DgnPlatform::DependencyLinkage *dl, int iRoot, DgnPlatform::AssocPoint const *assocPoint)
 Define an DEPENDENCY_DATA_TYPE_ASSOC1_I dependency linkage root to capture the state of the specified DgnPlatform::AssocPoint. More...
 
StatusInt mdlDependencyAssoc1_toAssoc (DgnPlatform::AssocPoint *assocPoint, DgnPlatform::DependencyLinkage const *dl, int iRoot)
 Recreate an DgnPlatform::AssocPoint from an DEPENDENCY_DATA_TYPE_ASSOC1_I root. More...
 
size_t mdlDependency_sizeofRootDataType (int rootDataType)
 Calculates the size of a single dependency root of the specified type. More...
 
DgnModelRefP mdlDependency_resolveReferenceAttachment (DgnModelRefP homeModelRef, DgnPlatform::ElementId refAttId)
 Evaluate a root model ref for the target file. More...
 
DgnModelRefP mdlDependency_resolveReferenceAttachmentRelative (DgnModelRefP homeModelRef, DgnPlatform::ElementId refAttId)
 Evaluate a reference model ref for the target file. More...
 
bool mdlDependency_isUnsupportedDependency (ElementRefP targetElement, DgnModelP dependentCache)
 Query if MicroStation cannot support a dependency of an element in the dependentCache on the specified target element. More...
 
bool mdlDependency_isRefMergeInProgress ()
 Query if reference file merging was done since the last time mdlDependency_processAffected was called. More...
 

Detailed Description

Typedef Documentation

typedef StatusInt(* DependencyProcessingCallback)(DgnPlatform::ElementId dependentID, DgnModelRefP modelRef,DgnPlatform::DependencyLinkage *pLinkage,UChar *pRootStatus, UChar selfStatus)

UserFunction called by mdlDependency_processAffected when a dependent element is affected by changes to root elements.

Remarks
If the dependency callback returns non-zero MicroStation will stop change processing and will undo all changes to the previous undo mark. Returning a non-zero status is not recommended. Preferrably, the callback should indicate failure in some other way, such as changing element symbology.

The dependentID and modelRef parameters identify the affected dependent element.

The pLinkage parameter points to a copy of the linkage that caused the callback.

Note: If a dependent element has multiple DependencyLinkages, the appropriate callback is invoked for each one that identifies changed roots. An element can even have multiple DependencyLinkages, each with the same appID. In this case, the callback for that appID is invoked once for each linkage.

Note: Since multiple callbacks may be made on the same element and each callback may modify and rewrite the element, possibly moving it, each callback must use mdlAssoc_getElement to read the element from its element ID to get the current version.

The pRootStatus parameter points to an array of status values, one for each root item in the dependency linkage root array. Each entry can have one of the following values:

  • DEPENDENCY_STATUS_UNCHANGED => not changed
  • DEPENDENCY_STATUS_CHANGED => modified in some way
  • DEPENDENCY_STATUS_DELETED => deleted
  • DEPENDENCY_STATUS_RESOLVED => found in a different model or file
  • DEPENDENCY_STATUS_UNRESOLVED => not found

The DEPENDENCY_STATUS_RESOLVED status is passed when the corresponding root comes from a different model than the dependent. The root might have been changed without notifying the dependent, so the callback should check this.

The DEPENDENCY_STATUS_UNRESOLVED status is passed when the corresponding root cannot be found. This normally happens only when the root is in a different model (or file) and that model is not loaded. The situtation may be temporary. If the root is resolved later on, the callback will be invoked and the root status will move to DEPENDENCY_STATUS_RESOLVED.

(Note: If an entry in the pLinkage->root array refers to more than one root element, then the corresponding entry in pRootStatus is the greatest of the individual root change status values.)

The selfStatus parameter is the change status of the dependent element itself. This can have one of the following values:

  • DEPENDENCY_STATUS_UNCHANGED => not changed
  • DEPENDENCY_STATUS_CHANGED => modified in some way
  • DEPENDENCY_STATUS_DELETED => deleted

All callbacks on a given dependent element will see the same selfStatus value.

If the dependent was changed directly and none of its roots was changed, then the values in the pRootStatus array will all be zero, while the value of selfStatus will be non-zero. The selfStatus parameter is meant to be a convenience to the callback, so that it can know if the dependent had been changed at the same time that it is notified about root changes.

A callback may modify the dependent element and even add or delete DependencyLinkages on it. Changes to dependency linkages will not affect the remaining callbacks on this element during the current wave but will affect the next wave (if any). Note that the linkage passed in is a copy and should not be modified. The callback must call the necessary MDL functions to write any changes to file.

If multiple applications want to handle the same dependency, then they must cooperate among themselves. See mdlDependency_getCallback for notes on how to chain callbacks together.

Remarks
The modelRef parameter identifies the model containing the dependent element.

If "far" or DgnPlatform::AssocPoint root references are used, then the root elements may not be in this model.

This modelRef cannot be used to display the element. This modelRef is a "working model ref." This model ref is not attached to any view. To display the dependent element (or a root), you must call mdlElmdscr_displayAllReferences.

Remarks

Detecting Drop

If a dependent or a root element is complex, your dependency callback can detect if it is dropped (i.e., converted from complex to non-complex). This is done as follows:

  • If the element is complex, and
  • If your dependency callback sees a change status for this element of DEPENDENCY_STATUS_CHANGED, and
  • If you detect that the element has in fact been deleted,

Then you know that the complex element was dropped.

As a concrete example, suppose that you have added a dependency linkage to a cell. The basic logic outlined here works equally well for other complex types and for cases where the complex element is a root. Suppose that a user has just applied the DROP command to that cell. Your dependency callback will be invoked as soon as the user accepts the drop.

When your dependency callback is invoked, the "selfChanged" status of the cell header will be DEPENDENCY_STATUS_CHANGED. This is misleading, because in fact the cell header element was effectively deleted by the drop command. You can detect this in one of two ways: if you call mdlAssoc_getElement and pass in the cell header element's DgnPlatform::ElementId, you will get an error status. That tells you that the cell header has been deleted. Or, you can call dgnCache_findElemById. That should return the cell header's ElementRefP. You can then call elementRef_isDeleted to verify that the cell header element itself has been deleted.

Detecting Group:

When elements are grouped, the elements become complex components of a new orphan cell. The elements retain their unique ElementIDs.

If an element has a dependency linkage, then when it is moved into a group, the DependencyProcessingCallback function will be called twice on it: once with selfStatus == DEPENDENCY_STATUS_DELETED and once with selfStatus == DEPENDENCY_STATUS_CHANGED (not necessarily in that order).

The DEPENDENCY_STATUS_CHANGED status indicates that the element has been re-added as a complex component. Calling mdlDependency_wasAdded will return true.

The DEPENDENCY_STATUS_DELETED status indicates that the original, stand-alone version of the element was deleted. To distinguish this from a real deletion, call

if (mdlAssoc_getElement (NULL, NULL, dependentID, modelRef) == SUCCESS)
{
// Element is not deleted
}

When this function returns SUCCESS, than means that the element with this unique ID is not deleted. Therefore, the element was only moved.

Parameters
[in]dependentIDelement ID of dependent element
[in]modelRefmodel containing dependent element (see remarks)
[in]pLinkagecopy of dependent element's linkage
[in]pRootStatuschange status of each root in linkage: DEPENDENCY_STATUS_XXX
[in]selfStatuschange status of dependent itself : DEPENDENCY_STATUS_XXX
See also
mdlElmdscr_displayAllReferences
Returns
ERROR if the change should be rejected and all changes rolled back to previous undo mark; SUCCESS otherwise.
typedef void(* DependencyProcessingCallbackForLoad)(DgnPlatform::ElementId dependentID, DgnModelRefP modelRef,DgnPlatform::DependencyLinkage *pLinkage,bool futureUse)

Callback to be invoked whenever an element carrying the specifying dependency linkage is loaded.

Remarks
This callback is read-only.
To detect when element refs are unloaded, you should hook the cache unload event. When a cache is unloaded, you know that all elements in that cache will be unloaded. Element refs are only unloaded when the cache is unloaded.
Parameters
[in]dependentIDelement ID of dependent element
[in]modelRefmodelRef of dependent element
[in]pLinkagecopy of dependent element's linkage
[in]futureUsefor future use (always true)
typedef void(* DependencyProcessingCallbackForUndoRedo)(DgnPlatform::ElementId dependentID, DgnModelRefP modelRef,DgnPlatform::DependencyLinkage *pLinkage,UChar *pRootStatus, UChar selfStatus)

Callback to be invoked whenever changes affecting a dependent element are undone or redone.

Remarks
This callback is read-only.

Detecting Undo of Group:

When elements are grouped, the elements become complex components of a new orphan cell. The elements retain their unique ElementIDs.

When the Group operation is undone, each component element is moved out of the orphan cell. If an element has a dependency linkage, then the DependencyProcessingCallbackForUndoRedo function will be called twice on it when the Group operation is undone: once with selfStatus == DEPENDENCY_STATUS_CHANGED and once with selfStatus == DEPENDENCY_STATUS_DELETED (not necessarily in that order).

The DEPENDENCY_STATUS_CHANGED status indicates that the original, non-complex element has been re-added. Calling mdlDependency_wasAdded will return true.

The DEPENDENCY_STATUS_DELETED status indicates that the grouped version of the element as a complex component has been deleted. To distinguish this from a real deletion, call

if (mdlAssoc_getElement (NULL, NULL, dependentID, modelRef) == SUCCESS)
{
// Element is not deleted
}

When this function returns SUCCESS, than means that the element with this unique ID is not deleted. Therefore, the element was only moved.

Parameters
[in]dependentIDelement ID of dependent element
[in]modelRefmodelRef of dependent element
[in]pLinkagecopy of dependent element's linkage
[in]pRootStatuschange status of each root in linkage: DEPENDENCY_STATUS_XXX
[in]selfStatuschange status of dependent itself : DEPENDENCY_STATUS_XXX
typedef struct mdlDesc MdlDesc

Dependency API

The Dependency API provides functions that allow an application to create and manage dependencies between elements and to do selective change tracking of marked elements. See the overview for the terms and concepts behind the dependency manager.

Function Documentation

int mdlDependency_addSimpleDependencyLinkageToDescr ( MSElementDescrH  nodeEdPP,
UShort  appId,
UShort  appValue,
int  copyOption,
DgnPlatform::ElementId  uniqueId 
)

This function creates a simple dependency linkage on an element descr.

See also
DgnPlatform::DependencyLinkage
Returns
ERROR if the linkage cannot be added
Parameters
[in,out]nodeEdPPelement desciptor to add linkage to
[in]appIdapplication ID of dependency to watch.
[in]appValueappValue of linkage to delete
[in]copyOptionDEPENDENCY_ON_COPY_...
[in]uniqueIdelementid of root element
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_appendLinkage ( MSElementP  pEl,
DgnPlatform::DependencyLinkage *  pLinkage 
)

This function adds the specified DgnPlatform::DependencyLinkage to an element.

The pLinkage parameter should point to a fully specified DgnPlatform::DependencyLinkage structure containing a valid appID, type, and refs list.

Remarks
The element buffer must be large enough to hold the additional linkage!

The dependencies are not actually registered until you write the element to the cache.

A given dependent element can have multiple DependencyLinkages, specifying dependencies with the same appID and type on various root elements or dependencies with various appIDs and types on the same root elements. A given element can be both a dependent and a root. Circular dependencies are allowed. An element may depend on itself.

To test for existing linkages, call mdlDependency_getLinkage.

To set up a linkage, call mdlDependency_appendLinkage.

To remove a DgnPlatform::DependencyLinkage from an element, call mdlDependency_deleteLinkage.

To update a DgnPlatform::DependencyLinkage in place on an element, call mdlDependency_updateLinkage.

A note on dependency linkage size:

The dependency linkage is a variable-length linkage. When a DgnPlatform::DependencyLinkage is appended to an element, mdlDependency_appendLinkage looks at the nRoots field to determine how much root data is actually used, and it allocates only that amount of space on the element.

Binary portability:

This function converts the stored linkage data to disk format if necessary.

See also
mdlDependency_appendLinkageEx, mdlDependency_appendLinkageUsingDescr
Parameters
[in,out]pElelement to receive the linkage
[in]pLinkagelinkage data to append
Returns
ERROR if linkage cannot be appended
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_appendLinkageEx ( MSElementP  pEl,
DgnPlatform::DependencyLinkage *  pLinkage,
int  xtrabytes 
)

This function adds the specified DgnPlatform::DependencyLinkage to an element.

The pLinkage parameter should point to a fully specified DgnPlatform::DependencyLinkage structure containing a valid appID, type, and refs list. See mdlDependency_appendLinkage for more details.

Remarks
This function allows the caller to specifiy that "extra" data has been appended to the DgnPlatform::DependencyLinkage that is to be stored. The xtrabytes parameter specifies how many bytes of extra data should be copied beyond the end of the DgnPlatform::DependencyLinkage data. The extra data is expected to be immediately contiguous with the DependencyData.

The format (and binary-portability) of the additional data is up to the caller.

For example:

MyData *pExtra;
DgnPlatform::DependencyLinkage dl; // std DgnPlatform::DependencyLinkage
// Create a standard DgnPlatform::DependencyLinkage
mdlDependency_initLinkage (&dl, DEPENDENCYAPPID_MyAppID, DEPENDENCY_DATA_TYPE_ELEMID, DEPENDENCY_ON_COPY_DropDependency);
dl.dep.nRoots = 1;
dl.dep.root.elemid[0] = someRoot;
// Extra data immediately follows the dependency root data.
pExtra = (MyData*) &dl.root.elemid[dl.dep.nRoots]; // point past end of root data
pExtra->field = ...
...
// Add the DgnPlatform::DependencyLinkage plus extra data to an element
mdlDependency_appendLinkageEx (pElement, MASTERFILE, &data.dep, sizeof (MyStruct));

A note on dependency linkage size:

In the previous example, we used a short-cut: we know that the in-memory DgnPlatform::DependencyLinkage structure pre-allocates about 1000 bytes of space for root data, of which we would use only 8 bytes. (When dependency linkage data is appended to an element, we allocate space for only the exact amount of root data used.) So, we know that the DgnPlatform::DependencyLinkage struct would have ample space following the first root to hold our extra data. But, what if we needed to specify a great deal of root data and/or extra data and could not use this trick? In that case, we would have to allocate contiguous space on the stack or heap sufficient to hold both. For example:

// Big data example:
MyBigData *pExtra;
DgnPlatform::DependencyLinkage *pdl; // std DgnPlatform::DependencyLinkage, plus extra data space
// Allocate lots of space
pdl = (DgnPlatform::DependencyLinkage*) _alloca (sizeof (DgnPlatform::DependencyLinkage) + sizeof (MyBigData));
// Create a standard DgnPlatform::DependencyLinkage
mdlDependency_initLinkage (pdl, DEPENDENCYAPPID_MyAppID, DEPENDENCY_DATA_TYPE_ELEMID, DEPENDENCY_ON_COPY_DropDependency);
pdl->dep.nRoots = nroots;
pdl->dep.root.elemid[0]= someRoot;
...
// Extra data immediately follows the dependency root data.
pExtra = (MyBigData*) &pdl->root.elemid[pdl->dep.nRoots]; // point past end of root data
pExtra->field = ...
...
// Add the DgnPlatform::DependencyLinkage plus extra data to an element
mdlDependency_appendLinkageEx (pElement, MASTERFILE, &data.dep, sizeof (MyBigStruct));

Binary portability:

This function converts the stored DgnPlatform::DependencyLinkage data to disk format if necessary. Extra data is not converted.

See also
mdlDependency_appendLinkage, mdlDependency_appendLinkageUsingDescr
Parameters
[in,out]pElelement to receive the linkage
[in]pLinkagelinkage data to append
[in]xtrabytesnumber of bytes of "extra" stuff tacked onto the end by the caller
Returns
ERROR if linkage cannot be appended
StatusInt mdlDependency_appendLinkageUsingDescr ( MSElementDescrH  ppEd,
DgnPlatform::DependencyLinkage *  pLinkage,
int  xtrabytes 
)

Add DgnPlatform::DependencyLinkage to an element descriptor.

See also
mdlDependency_addLinkageEx
Parameters
[in,out]ppEddescriptor to receive the linkage
[in]pLinkagelinkage data to append
[in]xtrabytesnumber of bytes of "extra" stuff tacked onto the end by the caller
Returns
ERROR if linkage cannot be appended
See also
mdlDependency_appendLinkageEx, mdlDependency_appendLinkage
Remarks
Required Library: mdlbltin.lib
DgnPlatform::DependencyLinkage* mdlDependency_bufferFromFileFormat ( LinkageHeaderP  pHeader)

Memory format DgnPlatform::DependencyLinkage from the specified user data linkage.

"Extra" data will immediately follow the linkage.

Binary portability:

This function converts the linkage data from native format in place if necessary. Extra data is not converted.

See also
DgnPlatform::DependencyLinkage
Returns
pointer to start of DgnPlatform::DependencyLinkage (converted in place)
Parameters
[in]pHeaderlinkage data in raw file format
Remarks
Required Library: mdlbltin.lib
DgnPlatform::DependencyLinkage* mdlDependency_bufferToFileFormat ( LinkageHeaderP  pHeader)

File format DgnPlatform::DependencyLinkage from the specified user data linkage.

"Extra" data will immediately follow the linkage.

Binary portability:

This function converts the linkage data to native format in place if necessary. Extra data is not converted.

See also
DgnPlatform::DependencyLinkage
Returns
pointer to start of DgnPlatform::DependencyLinkage (converted in place)
Parameters
[in]pHeaderlinkage data in raw file format
Remarks
Required Library: mdlbltin.lib
int mdlDependency_deleteLinkage ( MSElementP  pEl,
UShort  appID,
UShort  appValue 
)

Remove DependencyLinkages from an element.

Only DependencyLinkages having the specified appID and type are removed. If the element has multiple matching DependencyLinkages, all are removed. See mdlDependency_appendLinkage for adding a linkage.

Remarks
The dependencies are not actually un-registered until you write the element to the cache.
See also
DgnPlatform::DependencyLinkage, mdlDependency_appendLinkage
Parameters
[in,out]pElelement to strip
[in]appIDappID of linkage to delete
[in]appValueappValue of linkage to delete
Returns
number of linkages matched and deleted
Remarks
Required Library: mdlbltin.lib
void mdlDependency_fmtRoot ( WStringR  buf,
DgnModelRefP  modelRef,
DgnPlatform::DependencyLinkage *  pLinkage,
int  iRoot 
)

Formats the specified root in the specified linkage for display in a debugging message.

Remarks
For debugging purposes only.
Parameters
[out]bufformatted root
[in]modelRefmodelRef that contains the dependent element
[in]pLinkagelinkage to query
[in]iRootroot within linkage to query
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_getCallback ( MdlDesc **  ppMdlDescr,
DependencyProcessingCallback pFunc,
UShort  appID 
)

Get the current callback that is registered to handle dependencies with the specified appID.

Remarks
This function can be used to implement cooperative "chaining" of callbacks. An application might use mdlDependency_getCallback to get and store the current callback for an appID before deleting and overriding the appID itself. When its own callback is invoked, the application can invoke the original callback before or after doing its own processing.
See also
mdlDependency_registerCallback, mdlDependency_removeCallback
Parameters
[out]ppMdlDescrcurrent callback: MDL descriptor
[out]pFunccurrent callback: function (MDL or native)
[in]appIDappID of dependency
Returns
ERROR if no callback is registered; else SUCCESS
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_getCallbackForLoad ( MdlDesc **  ppMdlDescr,
DependencyProcessingCallbackForLoad pFunc,
UShort  appID 
)

Get the current load/unload callback for this appID.

Parameters
[out]ppMdlDescrcurrent callback: MDL descriptor
[out]pFunccurrent callback: function (MDL or native)
[in]appIDappID of dependency
Returns
ERROR if no callback is registered; else SUCCESS
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_getCallbackForUndoRedo ( MdlDesc **  ppMdlDescr,
DependencyProcessingCallbackForUndoRedo pFunc,
UShort  appID 
)

Get the current callback that is registered to handle dependencies with the specified appID for undo/redo purposes.

Parameters
[out]ppMdlDescrcurrent callback: MDL descriptor
[out]pFunccurrent callback: function (MDL or native)
[in]appIDappID of dependency
Returns
ERROR if no callback is registered; else SUCCESS
Remarks
Required Library: mdlbltin.lib
int mdlDependency_getDependentElementRefs ( ElementRefP *  pDependents,
DgnPlatform::ElementId  rootElemId,
DgnModelRefP  rootModelRef,
int  maxDependents 
)

This function returns a list of ElementRefs that depend on the specified element.

The specified element is a "root" element. The elements identified in the return array are its "dependents".

Remarks
The returned list includes dependents of all types, regardless of what type of dependency linkage created the dependency, and including dependencies created by other means (e.g., association points).

See mdlDependency_appendLinkage for adding dependencies to an element.

See mdlDependency_getNumOfDependents to query the total number of dependents.

See mdlDependency_getLinkage for inspecting linkages.

See mdlDependency_getRoots and for the inverse lookup from dependent to roots.

See mdlElmdscr_getByElemRef to get an element descriptor from an ElementRefP.

See elementRef_getElemID to get the DgnPlatform::ElementId for an ElementRefP.

Returns
# dependencies actually returned
Parameters
[out]pDependentselementRefs of dependent elements
[in]rootElemIdelement ID of root element
[in]rootModelRefmodelRef that contains root element
[in]maxDependentsmax # dependent elementRefs to return in pDependents
Remarks
Required Library: mdlbltin.lib
bool mdlDependency_getIgnoreMissingCallbacks ( void  )

Query the policy for what to do when a dependent element requires an application to process root changes, but the callback is not not currently registered.

See also
mdlDependency_setIgnoreMissingCallbacks
Returns
true if missing callbacks are ignored.
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_getLinkage ( DgnPlatform::DependencyLinkage *  pLinkage,
size_t  maxSize,
MSElementCP  pEl,
UShort  appID,
UShort  appValue 
)

Retrieve the DgnPlatform::DependencyLinkage on the specified element with matching appID and type.

If multiple DependencyLinkages with the same appID and type are present, the first is returned. This function returns SUCCESS if a matching DgnPlatform::DependencyLinkage is found; ERROR otherwise. The pLinkage parameter may be NULL, if the caller just wants to test for the presence of a matching linkage.

Remarks
"Extra" data will be copied along with the linkage into the output buffer, and so the buffer must be large enough.

Binary portability:

This function converts the linkage data to native format if necessary. Extra data is not converted.

Returns
SUCCESS if at least one matching linkage was found
Parameters
[out]pLinkageexisting linkage if any (optional)
[in]maxSizemax amount of data to return in output buffer
[in]pElelement to scan
[in]appIDappID to match
[in]appValueappValue of linkage to delete
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_getLinkageEx ( DgnPlatform::DependencyLinkage *  pDependencyLinkage,
DgnPlatform::DependencyLinkage **  ppDependencyLinkageInplace,
size_t *  pDependencyLinkageSize,
size_t  maxSize,
MSElementCP  pEl,
UShort  appID,
UShort  appValue 
)

Retrieve the DgnPlatform::DependencyLinkage on the specified element with matching appID and type.

If multiple DependencyLinkages with the same appID and type are present, the first is returned. This function returns SUCCESS if a matching DgnPlatform::DependencyLinkage is found; ERROR otherwise. The pLinkage parameter may be NULL, if the caller just wants to test for the presence of a matching linkage.

Remarks
Pass NULL for the pLinkage parameter and non-NULL for the pDependencyLinkageSize parameter to query the size of the linkage.
"Extra" data will be copied along with the linkage into the output buffer, and so the buffer must be large enough.

Binary portability:

This function converts the linkage data to native format if necessary. Extra data is not converted.

Returns
SUCCESS if at least one matching linkage was found; otherwise, ERROR
Parameters
[out]pDependencyLinkageoptional: where to copy DgnPlatform::DependencyLinkage if found
[out]ppDependencyLinkageInplaceoptional: where to return pointer to start of DgnPlatform::DependencyLinkage in pEl if found
[out]pDependencyLinkageSizeoptional: size in bytes of DgnPlatform::DependencyLinkage found
[in]maxSizemax amount of data to return in output buffer
[in]pElelement to scan
[in]appIDappID to match
[in]appValueappValue of linkage to delete
Remarks
Required Library: mdlbltin.lib
int mdlDependency_getNumOfDependents ( DgnPlatform::ElementId  rootElemId,
DgnModelRefP  modelRef 
)

This function returns a number of the elements that depend on the specified element.

The specified element is a "root" element.

See also
mdlDependency_getDependents
Remarks
See mdlDependency_getRoots for the inverse lookup from dependent to roots.
See also
mdlDependency_getRoots
Returns
# dependencies in root element
Parameters
[in]rootElemIdelement ID of root element
[in]modelRefmodelRef that contains the root element
Remarks
Required Library: mdlbltin.lib
int mdlDependency_getProcessingDisabled ( void  )

Query if processing of affected elements has been disabled.

Returns
Number of times disable has been called.
Remarks
Required Library: mdlbltin.lib
unsigned mdlDependency_getRoots ( DgnPlatform::DependencyRoot *  pRoots,
DgnModelRefP  modelRef,
DgnPlatform::DependencyLinkage *  pDep,
int  iRoot 
)

This function returns a list of root elements on which the specified item in a dependency linkage depends.

The input dependency linkage comes from from the "dependent" element. The elements identified in the returned array are its "roots".

Remarks
This function should be called once for each item in the roots array. For example:
unsigned i;
for (i=0; i&ltpDep-&gtnRoots; ++i)
{
unsigned j, n = mdlDependency_getRoots (roots, modelRef, pDep, i);
for (j=0; j&ltn; ++j)
process_the_root (roots[j]);
}

Note: A NULL value in the 'ref' field of a DgnPlatform::DependencyRoot indicates that the dependency is unresolved because the root element cannot be found. This may be because the target is in another file or model that is not open.

See mdlDependency_getDependents for the inverse lookup from a root to its dependents.

Returns
number of roots written to pRoots
Parameters
[out]pRootselements referenced by the i'th root (max: DEPENDENCY_MAX_TARGETS_PER_ROOT)
[in]modelRefmodelRef of dependent element
[in]pDepdependency linkage to query
[in]iRootroot in the linkage to query
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_initLinkage ( DgnPlatform::DependencyLinkage *  pLinkage,
UShort  appID,
int  dataType,
int  copyOptions 
)

This is a convenience function to initialize a DgnPlatform::DependencyLinkage.

The arguments are the required values to define a linkage. The rest of the linkage fields are initialized to zero.

To add a linkage to an element, call mdlDependency_appendLinkage.

Parameters
[in,out]pLinkagelinkage data to initialize
[in]appIDappID
[in]dataTypeDEPENDENCY_DATA_TYPE_...
[in]copyOptionsDEPENDENCY_ON_COPY_...
Returns
ERROR if invalid type or appID specified
Remarks
Required Library: mdlbltin.lib
bool mdlDependency_isRefMergeInProgress ( )

Query if reference file merging was done since the last time mdlDependency_processAffected was called.

Returns
true if any reference models were merged since the last time mdlDependency_processAffected was called.
Remarks
Required Library: mdlbltin.lib
bool mdlDependency_isUnsupportedDependency ( ElementRefP  targetElement,
DgnModelP  dependentCache 
)

Query if MicroStation cannot support a dependency of an element in the dependentCache on the specified target element.

Parameters
[in]targetElementthe target (root) of the dependency
[in]dependentCachethe cache containing the dependent element
Returns
true if the dependency is unsupported
Remarks
Required Library: mdlbltin.lib
DgnPlatform::DependencyStatus mdlDependency_processAffected ( )

This function invokes callbacks on all dependent elements affected by changes to root elements since the last call to this function.

Remarks
See mdlDependency_registerCallback for how to register a callback.

See DependencyProcessingCallback for how a dependency callback is defined.

Processing of affected dependent elements occurs at frequent intervals, but not necessarily on every file update. Applications may call this function directly to force processing. (See mdlDependency_setEager for the post-processing schedule. See mdlDependency_setProcessingDisabled for how to suspend or disable post-processing.)

All changes must be written to file before calling this function.

If callbacks cause further changes to root elements, then processing will iterate until no more changes are detected or until the maximum number of iterations is reached.

Changes caused by processing may become part of the undo group of the immediately preceeding command. So, undo will encompass both the results of the preceeding command and the effects of post-processing the dependent elements affected by it. (See mdlDependency_setAppendChanges for how to control this policy.)

If a callback returns a non-zero status or if the maximum number of iterations is reached, processing will normally halt, and MicroStation will undo all changes to the previous mark. (See mdlDependency_setErrorLevel for how to control failure policies.)

See DgnPlatform::DependencyLinkage .u.f.requireApp and u.f.dontRequireAppForDelete and mdlDependency_setIgnoreMissingCallback for what MDL does when a dependent element is affected and no callback is registered.

Self-dependencies

Normally an element depends on other (root) elements and callbacks are invoked when the roots are changed.

An element is also considered to depend on itself it if contains a DgnPlatform::DependencyLinkage (of any kind). The DgnPlatform::DependencyLinkage does not have to refer to the element as a root, but it may. The registered callback for the element's DgnPlatform::DependencyLinkage(s) will be fired by mdlDependency_processAffected as a result of a change to the element itself.

Background:

An element with a DgnPlatform::DependencyLinkage is called a "dependent element". A dependent element depends on other elements, called "root elements". A callback is triggered by a change to a root element (or to the dependent element itself).

An application registers an interest in DependencyLinkages that have a particular appID. When a dependency is triggered, MDL examines each DgnPlatform::DependencyLinkage found on the affected dependent element and invokes the callback that is registered for the appID of the linkage.

If an element contains a single DgnPlatform::DependencyLinkage that references multiple root elements, the registered callback for that linkage will be invoked only once, even if multiple root elements have changed.

A given dependent element can have multiple DependencyLinkages, specifying dependencies with the same appID on various root elements or dependencies with various appIDs and types on the same root elements. A callback will be made on each linkage whose roots have changed. (If there is more than one linkage with the same appID on the same element, the registered callback will be invoked on each one.)

A given element can be both a dependent and a root. Circular dependencies are allowed. An element may depend on itself.

Example:

In the following example, suppose that:

  • ELEMENT1 depends on ELEMENT2. That is, ELEMENT1 has a DgnPlatform::DependencyLinkage that references ELEMENT2.
  • The appID stored in the linkage has the value 1001.
  • An application called App is loaded and registers an interest in dependencies with an appID of 1001. That is, App calls mdlDependency_registerCallback, specifying the appID of 1001 as the key and its own MDL descriptor and the function func as the callback.

Behind the scenes:

When MDL first noticed the DgnPlatform::DependencyLinkage on ELEMENT1, it updated the system's dependency graph to indicate that ELEMENT2 has ELEMENT1 as a dependent. Dependency registration happens when ELEMENT1 is appended or rewritten to the file after mdlDependency_appendLinkage was called initially and every time the design file containing ELEMENT1 is loaded thereafter. See the note on "Dependency Maintenance" below for more details on when dependencies are registered and when changes to dependencies become effective.

When App called mdlDependency_registerCallback, dependency added an entry to its run-time callback registry associating App:func with appID 1001. Note that the app must call registerCallback every time it loads, since the callback registry is not persistent. (See DgnPlatform::DependencyLinkage u.f.requireApp and u.f.dontRequireAppForDelete and mdlDependency_setIgnoreMissingCallback for what MDL does when a dependent elementis affected and no callback is registered.)

Triggering a dependency:

Now suppose that ELEMENT2 is changed. ELEMENT2 has dependents (ELEMENT1). Dependency notes the change but does not fire callbacks at this point.

When mdlDependency_processAffected is called, dependency looks at the change list, determines that ELEMENT1 affects ELEMENT2, examines ELEMENT2's DependencyLinkages, and finds one with appID:1001. Dependency then looks up 1001 in its callback registry, finds App:func and fires it.

Cycles

Post-processing iterates as long as new changes are produced. To prevent infinite cycles, post-processing is terminated at a pre-set maximum of 200 iterations. To help prevent infinite cycles, MDL ignores calls to rewrite an element when the before and after versions of the element are identical. This test is sometimes insufficient to detect nearly equal floating point numbers. To prevent infinite cycles, a post-processing callback should check its results and should not call element rewrite if all relevant data is unchanged. Comparisons involving floating point values (and DPoint3ds) should be done to a tolerance. See mdlVec_pointEqualUOR for example.

Dependency Maintenance

When the cache containing a dependent element is loaded, MicroStation notices the element's DependencyLinkages and creates live dependencies on the root elements that it references. Therefore, the result of calling mdlDependency_getDependents on a root element will include the dependent element immediately after the dependent's cache is loaded.

When the cache containing a dependent element is unloaded (e.g., when the file is closed), MicroStation "unplugs" the dependent element from its roots. Therefore, the result of calling mdlDependency_getDependents on a root element will omit the unloaded dependent element after the dependent's cache is unlaoded. The dependent element still has its DependencyLinkages, of course, so that MicroStation will reconnect it to its roots the next time it is loaded.

When a dependent element is created or rewritten, MicroStation detects new DependencyLinkages on it and connects it to its roots immediately. Therefore, the result of calling mdlDependency_getDependents on a root element will include the dependent element right after the dependent is appended or rewritten to the file with a new reference to that root in its DgnPlatform::DependencyLinkage.

Note that calling mdlDependency_appendLinkage or mdlDependency_updateLinkage does not connect the dependent to new roots. This happens only when the element is subsequently appended or rewritten to the file.

When a dependent is rewritten to the file, MicroStation detects changed and removed DependencyLinkages on it, but does not remove dependencies immediately. Instead, MicroStation waits until the next call to mdlDependency_processAffected to remove dropped dependencies. Therefore, after removing a root from a dependent's DgnPlatform::DependencyLinkage and until mdlDependency_processAffected is called, the result of calling mdlDependency_getDependents on the root will continue include the dependent element, even though the result of calling mdlDependency_getRoots will not include the root element. The result of mdlDependency_getDependents will omit the dependent after mdlDependency_processAffected is called.

When a dependent changes in size and is rewritten to the file, causing it to move within the file, MicroStation will maintain the dependency of the dependent on its roots. Until mdlDependency_processAffected is called, however, the result of calling mdlDependency_getDependents on one of its roots will include the dependent twice. That is, the results will include both the element reference that identified the dependent before the move and the element reference the identifies the element after the move. The pre-move element reference is removed from the root's dependency list by mdlDependency_processAffected.

Debugging

mdlDependency_setTraceLevel and mdlDependency_fmtRoot can be used to debug change processing.

Returns
DependencyStatus::Success if processing was done; otherwise, one of the non-zero DgnPlatform::DependencyStatus values if there is a processing problem or if a callback failed.
StatusInt mdlDependency_registerCallback ( UShort  appID,
MdlDesc pMdlDescr,
DependencyProcessingCallback  func 
)

Register a callback to be invoked whenever MDL detects changes that affect elements with a DgnPlatform::DependencyLinkage having the specified appID.

Remarks
A callback is associated with a specified appID. A change affecting a dependent element with a DgnPlatform::DependencyLinkage that has the same appID will cause the callback to be invoked. Dependency callbacks are invoked by mdlDependency_processAffected.

Note: ONLY ONE APPLICATION MAY REGISTER FOR A GIVEN appID.

If multiple applications want to handle the same dependency, then they must cooperate among themselves. See mdlDependency_getCallback for notes on how to chain callbacks together.

The same application can register an interest in multiple dependencies.

A registered callback can be an MDL function or a native function. See the DependencyProcessingCallback typedef for the arguments of the callback.

See also
mdlDependency_removeCallback
Parameters
[in]appIDapplication ID of dependency to watch.
[in]pMdlDescrMDL descriptor for callback
[in]funccallback function, can be either MDL or native code.
Returns
non-zero if there is already a callback registered for this appID
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_registerCallbackForLoad ( UShort  appID,
MdlDesc pDesc,
DependencyProcessingCallbackForLoad  func 
)

Register a callback to be invoked whenever an element carrying the specifying dependency linkage is loaded or unloaded.

Remarks
Load callbacks are read-only.

The load/unload callback allows an initapp to monitor the loading and unloading of specific elements. A load/unload callback is registered for a specific appID and is invoked whenever an element carrying a dependency linkage with that appID is loaded or unloaded.

The load/unload callback is distinct from the changed and undo/redo callbacks. Load callbacks are invoked after the cache is completely loaded. Unload callbacks are invoked just before the cache is unloaded.

The status of reference attachments is undefined at the time of load and unload callbacks.

Parameters
[in]appIDappID of dependency to watch
[in]pDescMDL descriptor for callback
[in]funccallback function (MDL or native)
Returns
non-zero if there is already a callback registered for this appID
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_registerCallbackForUndoRedo ( UShort  appID,
MdlDesc pDesc,
DependencyProcessingCallbackForUndoRedo  func 
)

Register a callback to be invoked whenever changes affecting a dependent element are undone or redone.

Remarks
Undo/redo callbacks are read-only.
Parameters
[in]appIDappID of dependency to watch
[in]pDescMDL descriptor for callback
[in]funccallback function (MDL or native)
Returns
non-zero if there is already a callback registered for this appID
Remarks
Required Library: mdlbltin.lib
void mdlDependency_removeCallback ( UShort  appID)

Un-register the current callback for dependencies having the specified appID.

See also
mdlDependency_getCallback, mdlDependency_registerCallback
Parameters
[in]appIDappID of dependency
Remarks
Required Library: mdlbltin.lib
void mdlDependency_removeCallbackForLoad ( UShort  appID)

Un-register the current load/unload callback for this appID.

Parameters
[in]appIDappID of dependency
void mdlDependency_removeCallbackForUndoRedo ( UShort  appID)

Un-register the current callback for dependencies having the specified appID for undo/redo purposes.

Parameters
[in]appIDappID of dependency
Remarks
Required Library: mdlbltin.lib
DgnModelRefP mdlDependency_resolveReferenceAttachment ( DgnModelRefP  homeModelRef,
DgnPlatform::ElementId  refAttId 
)

Evaluate a root model ref for the target file.

Remarks
This function differs from mdlDependency_resolveReferenceAttachmentRelative in that it tries to convert homeModelRef into a root model ref and then looks up the reference relative to it. This results in a reference path leading back to the root model ref that refers to the cache of homeModelRef. This is required when you want to see references from the point of view of an element in another model.
Note: You must not hold onto the returned DgnModelRefP for long. In some cases, the model ref will be freed at the end if the next (or current) call to mdlDependency_processAffected.
Parameters
[in]homeModelRefmodelref containing reference attachment
[in]refAttIdreference attachment element id
Returns
a root modelref
Remarks
Required Library: mdlbltin.lib
DgnModelRefP mdlDependency_resolveReferenceAttachmentRelative ( DgnModelRefP  homeModelRef,
DgnPlatform::ElementId  refAttId 
)

Evaluate a reference model ref for the target file.

Remarks
This function differs from mdlDependency_resolveReferenceAttachment in that it looks up the reference relative to homeModelRef, even if homeModelRef is itself a reference model ref. This results in a reference path leading back to the parent of homeModelRef. This is useful when a particular reference transform is needed, e.g., for drawing.
Note: You must not hold onto the returned DgnModelRefP for long. In some cases, the model ref will be freed at the end if the next (or current) call to mdlDependency_processAffected.
Parameters
[in]homeModelRefmodelref containing reference attachment
[in]refAttIdreference attachment element id
Returns
a root modelref
Remarks
Required Library: mdlbltin.lib
void mdlDependency_rootChanged ( ElementRefP  root)

Declare that the specified root is changed and its dependents should be notified.

The root need not really be changed. This function is useful for propagating changes across indirect references, e.g., an element reference path.

Parameters
[in]rootthe root element
Remarks
Required Library: mdlbltin.lib
void mdlDependency_setIgnoreMissingCallbacks ( bool  b)

Set the policy for what post-processing should do when a dependent element requires an application to process root changes, but the callback is not currently registered.

Remarks
If set, the DgnPlatform::DependencyLinkage.u.f.requireApp field means that any changes affecting the element that contains the linkage must be processed by the specified application. Normally, the dependency manager will reject and roll back the root change if the required callback is not registered. This happens, for example, when an application wants to validate all changes that affect a given element and wants to block changes to the element's roots when the application is not loaded. If an element contains a self-dependency, then the requireApp flag means that the application wants to control all changes to the element and to block changes to the element if the application is not loaded.

This function can be used to override the DgnPlatform::DependencyLinkage.u.f.requireApp field (on all linkages), so that root changes are allowed, even if some callbacks are not available to post-process affected dependency elements.

See mdlDependency_processAffected for more details on post-processing.

See also
mdlDependency_getIgnoreMissingCallbacks
Parameters
[in]btrue: ignore; false: don't ignore
void mdlDependency_setProcessingDisabled ( bool  bSuppress)

Disable or enable post-processing of affected dependent elements.

Remarks
Call mdlDependency_setTrackingDisabled to suppress change-tracking. (Without change-tracking, there is no post-processing.)

Call mdlDependency_setErrorLevel to control post-processing failure handling without disabling post-processing.

See mdlDependency_processAffected for more details on post-processing.

Parameters
[in]bSuppressif true, disable; else enable
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_setRoots ( DgnPlatform::DependencyLinkage *  pDep,
DgnModelRefP  modelRef,
const DgnPlatform::DependencyRoot *  pRoots,
int  iRoot 
)

This function updates the roots identified by the specified item in the dependency linkage.

Remarks
Dependency changes take effect only after the element that contains the linkage is re-written to the cache.
Returns
ERROR if invalid root encountered
Parameters
[in,out]pDepdependency linkage to query
[in]modelRefmodelRef of dependent element
[in]pRootselements referenced by the i'th root
[in]iRootroot in the linkage to query
Remarks
Required Library: mdlbltin.lib
void mdlDependency_setTraceLevel ( int  traceLevel)

For debugging purposes only:

Enable or disable tracing messages to help debug dependencies and callbacks.

Parameters
[in]traceLevel1 to enable tracing messages; 0 to to disable
Remarks
Required Library: mdlbltin.lib
size_t mdlDependency_sizeof ( DgnPlatform::DependencyLinkage *  pDep,
int  xtrabytes 
)

Get the stored size of the specified dependency linkage.

This can be useful in order to predict whether adding a linkage to an element will exceed the maximum element size.

The returned size includes the standard DgnPlatform::LinkageHeader size. The returned size is padded and rounded as required for stored linkage sizes.

The returned size is in in bytes.

Remarks
This function does not calculate possible extra data added behind the dependency linkage by function mdlDependency_appendLinkageEx. In that case user needs to add the size of extra data to get correct size of linkage.
Parameters
[in]pDeplinkage to test
[in]xtrabytes# bytes of "extra" stuff tacked onto the end by the caller
Returns
the stored size of the specified dependency linkage.
Remarks
Required Library: mdlbltin.lib
size_t mdlDependency_sizeofRootDataType ( int  rootDataType)

Calculates the size of a single dependency root of the specified type.

Parameters
[in]rootDataTypea dependency root data type.
  • DEPENDENCY_DATA_TYPE_ELEM_ID => DgnPlatform::ElementId
  • DEPENDENCY_DATA_TYPE_ELEM_ID_V => FarElementID
  • DEPENDENCY_DATA_TYPE_ASSOC_POINT => ElementID_V
  • DEPENDENCY_DATA_TYPE_ASSOC_POINT_I => FarElementID_V
  • DEPENDENCY_DATA_TYPE_FAR_ELEM_ID => DgnPlatform::AssocPoint
  • DEPENDENCY_DATA_TYPE_FAR_ELEM_ID_V => AssocPoint_I
Returns
the size in bytes
See also
DependencyLinkage
DgnPlatform::DependencyLinkage
Remarks
Required Library: mdlbltin.lib
StatusInt mdlDependency_updateLinkage ( MSElementP  pEl,
DgnPlatform::DependencyLinkage *  pDep,
int  xtrabytes 
)

Update a DependencyLinkages on an element.

This function will update the linkage in place, as long as it hasn't changed size. Otherwise, it will delete the current version of linkage from the element and append the new version.

NOTE: Changes to dependencies are not actually recognized until you rewrite the element to the cache.

Parameters
[in,out]pElelement to receive the linkage
[in]pDepnew version of linkage
[in]xtrabytesnumber of bytes of "extra" stuff tacked onto the end by the caller
Returns
SUCCESS if matching linkage was found and updated
Remarks
Required Library: mdlbltin.lib
bool mdlDependency_wasAdded ( ElementRefP  ref)

Query if the specified element is new.

Remarks
This function should be called only from a dependency callback.
Parameters
[in]refthe element to query
Returns
true if the element is new
StatusInt mdlDependencyAssoc1_fromAssoc ( DgnPlatform::DependencyLinkage *  dl,
int  iRoot,
DgnPlatform::AssocPoint const *  assocPoint 
)

Define an DEPENDENCY_DATA_TYPE_ASSOC1_I dependency linkage root to capture the state of the specified DgnPlatform::AssocPoint.

Parameters
[out]dlthe dependency linkage to write to
[in]iRootindex into the dl roots array to write to
[in]assocPointthe input DgnPlatform::AssocPoint
Returns
non-zero error code if the assocPoint cannot be captured by an DEPENDENCY_DATA_TYPE_ASSOC1_I root.
Remarks
Required Library: mdlbltin.lib
See also
DgnPlatform::DependencyLinkage
StatusInt mdlDependencyAssoc1_fromAssocAndSubtype ( DgnPlatform::DependencyLinkage *  dl,
int  iRoot,
DgnPlatform::AssocPoint const *  assocPoint,
int  assoc1Subtype 
)

Define an DEPENDENCY_DATA_TYPE_ASSOC1_I dependency linkage root to capture the state of the specified DgnPlatform::AssocPoint.

Parameters
[out]dlthe dependency linkage to write to
[in]iRootindex into the dl roots array to write to
[in]assocPointthe input DgnPlatform::AssocPoint
[in]assoc1Subtypethe assocPoint subtype to define. Should be a DEPENDENCY_ASSOC1_SUBTYPE_... value
Returns
non-zero error code if the assocPoint cannot be captured by an DEPENDENCY_DATA_TYPE_ASSOC1_I root.
Remarks
Required Library: mdlbltin.lib
See also
DgnPlatform::DependencyLinkage
StatusInt mdlDependencyAssoc1_toAssoc ( DgnPlatform::AssocPoint *  assocPoint,
DgnPlatform::DependencyLinkage const *  dl,
int  iRoot 
)

Recreate an DgnPlatform::AssocPoint from an DEPENDENCY_DATA_TYPE_ASSOC1_I root.

Parameters
[out]assocPointthe DgnPlatform::AssocPoint to write to
[in]dlthe input dependency linkage
[in]iRootindex into the dl roots array
Returns
non-zero error code if linkage does not contain DEPENDENCY_DATA_TYPE_ASSOC1_I roots.
Remarks
Required Library: mdlbltin.lib
See also
DgnPlatform::DependencyLinkage

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