Classes
struct	HistoryCommitParms
	Documents a set of changes to be committed to design history. More...

struct	historyRevisionInfo
	Documents a set of changes in design history. More...

Typedefs
typedef struct historyRevisionInfo	HistoryRevisionInfo
	Documents a set of changes in design history. More...

typedef StatusInt	HistoryFunc_RestorePre (DgnFileP file, WCharCP targetRev, BentleyDgnHistoryModelsToElementChangesMapCP elements)
	Signature of callback invoked before changes are restored from design history. More...

typedef void	HistoryFunc_RestorePost (DgnFileP file, WCharCP targetRev, BentleyDgnHistoryModelsToElementChangesMapCP elements)
	Signature of callback invoked after changes are restored from design history. More...

typedef void	HistoryFunc_CommitPre (DgnFileP pFile, const HistoryCommitParms *pParms)
	Signature of callback invoked just before changes are committed to design history. More...

typedef void	HistoryFunc_CommitPost (HistoryRevisionInfo const *pInfo, DgnFileP pFile, BentleyDgnHistoryRevisionInfoCP infoObject, StatusInt status)
	Signature of callback invoked after a set of changes is committed to design history. More...

typedef StatusInt	HistoryFunc_CreatePre (DgnFileP pFile)
	Signature of callback invoked before design history is initialized in a file. More...

typedef void	HistoryFunc_CreatePost (DgnFileP pFile)
	Signature of callback invoked after design history is initialized in a file. More...

typedef StatusInt	HistoryFunc_DeletePre (DgnFileP pFile)
	Signature of callback invoked before design history is deleted from a file. More...

typedef void	HistoryFunc_DeletePost (DgnFileP pFile, StatusInt status)
	Signature of callback invoked after design history is deleted from a file. More...

typedef StatusInt	HistoryFunc_FmtRevisionNumber (WCharP buf, WCharCP num, int maxbuf, DgnFileP file)
	Signature of callback invoked to format history revision number. More...

typedef StatusInt	HistoryFunc_CombinePre (DgnFileP file, WCharCP start, WCharCP end)
	Signature of callback invoked before revisions in history are netted out and combined. More...

typedef void	HistoryFunc_CombinePost (DgnFileP file, WCharCP start, WCharCP end, StatusInt status)
	Signature of callback invoked after revisions in history are netted out and combined, or after the attempt to combine fails. More...

typedef StatusInt	HistoryFunc_DeleteEarlyRevisionsPre (DgnFileP file, WCharCP tooOld)
	Signature of callback invoked before revisions in history are removed. More...

typedef void	HistoryFunc_DeleteEarlyRevisionsPost (DgnFileP file, WCharCP tooOld, StatusInt status)
	Signature of callback invoked after revisions in history are removed, or if the attempt to delete revisions failed. More...

typedef StatusInt	HistoryFunc_UpdateRevisionUserDescPre (DgnFileP file, WCharCP rev, WCharCP user, WCharCP desc)
	Signature of callback invoked before the description and/or user name of the specified revision are modified. More...

typedef void	HistoryFunc_UpdateRevisionUserDescPost (DgnFileP file, WCharCP rev, WCharCP user, WCharCP desc, StatusInt status)
	Signature of callback invoked after the description and/or user name, or if the attempt to change the data failed. More...

typedef StatusInt	HistoryFunc_CompareElements (int *affinity, DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP preChange, MSElementDescrCP postChange, WCharCP title, WCharCP preChangeDescription, WCharCP postChangeDescription)
	Signature of custom element diff analyzer. More...

typedef StatusInt	HistoryFunc_DisplayElement (int *affinity, DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP element, WCharCP descriptionString, WCharCP changeTypeString)
	Signature of custom element display handler. More...

typedef StatusInt	HistoryFunc_DescribeElement (int *affinity, WCharP type, WCharP name, DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP element, int maxtype, int maxname)
	Signature of custom element description handler. More...

Functions
StatusInt	mdlHistory_create (DgnFileP pFile)
	Initializes design history in file. More...

StatusInt	mdlHistory_delete (DgnFileP pFile)
	Removes design history from file. More...

StatusInt	mdlHistory_commit (HistoryRevisionInfo pInfo, DgnFileP pFile, const HistoryCommitParms pParms)
	Record all changes to specified file in its design history since last commit. More...

static void	AddCommitPreFunction (HistoryFunc_CommitPre newFunc)
	An MDL application can use this to set a function to be called just before changes are committed to design history. More...

static bool	RemoveCommitPreFunction (HistoryFunc_CommitPre oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddCommitPreFunction. More...

static void	AddCommitPostFunction (HistoryFunc_CommitPost newFunc)
	An MDL application can use this to set a function to be called after a set of changes is committed to design history. More...

static bool	RemoveCommitPostFunction (HistoryFunc_CommitPost oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddCommitPostFunction. More...

static void	AddCreatePreFunction (HistoryFunc_CreatePre newFunc)
	An MDL application can use this to set a function to be called before design history is initialized in file. More...

static bool	RemoveCreatePreFunction (HistoryFunc_CreatePre oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddCreatePreFunction. More...

static void	AddCreatePostFunction (HistoryFunc_CreatePost newFunc)
	An MDL application can use this to set a function to be called after design history is initialized in a file. More...

static bool	RemoveCreatePostFunction (HistoryFunc_CreatePost oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddCreatePostFunction. More...

static void	AddDeletePreFunction (HistoryFunc_DeletePre newFunc)
	An MDL application can use this to set a function to be called before design history is deleted from a file. More...

static bool	RemoveDeletePreFunction (HistoryFunc_DeletePre oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddDeletePreFunction. More...

static void	AddDeletePostFunction (HistoryFunc_DeletePost newFunc)
	An MDL application can use this to set a function to be called after design history is deleted from a file. More...

static bool	RemoveDeletePostFunction (HistoryFunc_DeletePost oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddDeletePostFunction. More...

static void	AddRestorePreFunction (HistoryFunc_RestorePre newFunc)
	An MDL application can use this to set a function to be called before changes are restored from design history. More...

static bool	RemoveRestorePreFunction (HistoryFunc_RestorePre oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddRestorePreFunction. More...

static void	AddRestorePostFunction (HistoryFunc_RestorePost newFunc)
	An MDL application can use this to set a function to be called after changes are restored from design history. More...

static bool	RemoveRestorePostFunction (HistoryFunc_RestorePost oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddRestorePostFunction. More...

static void	AddCombinePreFunction (HistoryFunc_CombinePre newFunc)
	An MDL application can use this to set a function to be called before revisions in history are netted out and combined. More...

static bool	RemoveCombinePreFunction (HistoryFunc_CombinePre oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddCombinePreFunction. More...

static void	AddCombinePostFunction (HistoryFunc_CombinePost newFunc)
	An MDL application can use this to set a function to be called after revisions in history are netted out and combined, or after the attempt to combine fails. More...

static bool	RemoveCombinePostFunction (HistoryFunc_CombinePost oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddCombinePostFunction. More...

static void	AddDeleteEarlyRevisionsPreFunction (HistoryFunc_DeleteEarlyRevisionsPre newFunc)
	An MDL application can use this to set a function to be called before revisions in history are removed. More...

static bool	RemoveDeleteEarlyRevisionsPreFunction (HistoryFunc_DeleteEarlyRevisionsPre oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddDeleteEarlyRevisionsPreFunction. More...

static void	AddDeleteEarlyRevisionsPostFunction (HistoryFunc_DeleteEarlyRevisionsPost newFunc)
	An MDL application can use this to set a function to be called after revisions in history are removed, or if the attempt to delete revisions failed. More...

static bool	RemoveDeleteEarlyRevisionsPostFunction (HistoryFunc_DeleteEarlyRevisionsPost oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddDeleteEarlyRevisionsPostFunction. More...

static void	AddFmtRevisionNumberFunction (HistoryFunc_FmtRevisionNumber newFunc)
	An MDL application can use this to set a function to be called to format history revision number. More...

static bool	RemoveFmtRevisionNumberFunction (HistoryFunc_FmtRevisionNumber oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddFmtRevisionNumberFunction. More...

static void	AddCompareElementsFunction (HistoryFunc_CompareElements newFunc)
	An MDL application can use this to set a function to be called when design history needs to allow the user to interactively compare revisions of an element. More...

static bool	RemoveCompareElementsFunction (HistoryFunc_CompareElements oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddCompareElementsFunction. More...

static void	AddDisplayElementFunction (HistoryFunc_DisplayElement newFunc)
	An MDL application can use this to set a function to be called when design history needs to interactively display the properties of an element to the user. More...

static bool	RemoveDisplayElementFunction (HistoryFunc_DisplayElement oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddDisplayElementFunction. More...

static void	AddDescribeElementFunction (HistoryFunc_DescribeElement newFunc)
	An MDL application can use this to set a function to be called when design history needs to show the user a description of an element. More...

static bool	RemoveDescribeElementFunction (HistoryFunc_DescribeElement oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddDisplayElementFunction. More...

static void	AddUpdateRevisionUserDescPreFunction (HistoryFunc_UpdateRevisionUserDescPre newFunc)
	An MDL application can use this to set a function to be called before the description and/or user name of the specified revision are modified. More...

static bool	RemoveUpdateRevisionUserDescPreFunction (HistoryFunc_UpdateRevisionUserDescPre oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddUpdateRevisionUserDescPreFunction. More...

static void	AddUpdateRevisionUserDescPostFunction (HistoryFunc_UpdateRevisionUserDescPost newFunc)
	An MDL application can use this to set a function to be called after the description and/or user name, or if the attempt to change the data failed. More...

static bool	RemoveUpdateRevisionUserDescPostFunction (HistoryFunc_UpdateRevisionUserDescPost oldFunc)
	Removes a callback function previously installed using HistoryCallback::AddUpdateRevisionUserDescPostFunction. More...

void	mdlHistory_fmtRevisionNumberByFormat (WCharP buf, WCharCP num, WCharCP fmt, int maxbuf, bool reserved)
	Format a history revision number according to the specified format. More...

void	mdlHistory_fmtRevisionNumber (WCharP buf, WCharCP num, int maxbuf, DgnFileP file)
	Formats a history revision number. More...

StatusInt	mdlHistory_compareElementsEx (DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP preChange, MSElementDescrCP postChange, WCharCP title, WCharCP preChangeDescription, WCharCP postChangeDescription)
	Invoke custom element diff analyzer. More...

StatusInt	mdlHistory_queryCompareElements (DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP postChange)
	Query if any registered compare hook will handle this element. More...

StatusInt	mdlHistory_displayElement (DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP element, WCharCP descriptionString, WCharCP changeTypeString)
	Invoke custom element display handler. More...

StatusInt	mdlHistory_queryDisplayElement (DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP element)
	Query if any registered element display hook will handle this element. More...

StatusInt	mdlHistory_describeElement (WCharP type, WCharP name, DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP element, int maxtype, int maxname)
	Invoke custom element description handler. More...

StatusInt	mdlHistory_queryDescribeElement (DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP element)
	Query if any registered element describe hook will handle this element. More...

StatusInt	mdlHistory_collectRevisionDescriptors (WCharCP fileName, WCharP desc, int bufLen, WCharCP separator)
	collect all of the uncommitted revision descriptors. More...

bool	mdlHistory_exists (DgnFileP pFile)
	Check if the specified file has design history. More...

Detailed Description

Typedef Documentation

typedef void HistoryFunc_CombinePost(DgnFileP file, WCharCP start, WCharCP end, StatusInt status)

Signature of callback invoked after revisions in history are netted out and combined, or after the attempt to combine fails.

Parameters

[in]	file	the file containing history that was modified
[in]	start	the revision number identifying the start of the range of history
[in]	end	the revision number identifying the end of the range of history
[in]	end	the revision number identifying the end of the range of history
	status	if non-zero, then the attempt to combine failed

See also: HistoryFunc_CombinePre; HistoryCallback::AddCombinePostFunction

typedef StatusInt HistoryFunc_CombinePre(DgnFileP file, WCharCP start, WCharCP end)

Signature of callback invoked before revisions in history are netted out and combined.

Parameters

[in]	file	the file containing history to be modified
[in]	start	the revision number identifying the start of the range of history
[in]	end	the revision number identifying the end of the range of history

Returns: If the callback may return a non-zero error status, the combine will not be done. To allow the combine, return 0.

See also: HistoryFunc_CombinePost; HistoryCallback::AddCombinePreFunction

typedef void HistoryFunc_CommitPost(HistoryRevisionInfo const *pInfo, DgnFileP pFile, BentleyDgnHistoryRevisionInfoCP infoObject, StatusInt status)

Signature of callback invoked after a set of changes is committed to design history.

Parameters

[in]	pInfo	revision number, etc. of new revision
[in]	pFile	file containing changes to commit
[in]	infoObject	C++ only: full revision info
[in]	status	the result of the commit: SUCCESS of changes were committed, HISTORY_ERROR_NOCHANGES if there were no changes to commit, or a non-zero HISTORY_ERROR code if the commit failed.

See also: HistoryFunc_CommitPre; HistoryCallback::AddCommitPostFunction; mdlHistory_commit

typedef void HistoryFunc_CommitPre(DgnFileP pFile, const HistoryCommitParms *pParms)

Signature of callback invoked just before changes are committed to design history.

Parameters

[in]	pFile	file containing changes to commit
[in]	pParms	time, user, desc, etc.

See also: HistoryFunc_CommitPost; HistoryCallback::AddCommitPreFunction; mdlHistory_commit

typedef StatusInt HistoryFunc_CompareElements(int *affinity, DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP preChange, MSElementDescrCP postChange, WCharCP title, WCharCP preChangeDescription, WCharCP postChangeDescription)

Signature of custom element diff analyzer.

Remarks: This function is called in one of two modes:

1. When Design History wants to query the hook function's affinity to the specified element, the affinity parameter is non-NULL (the preChange parameter will also be NULL). In this case, the hook should not actually do the comparison but should set the affinity parameter to a number between DESIGN_HISTORY_HOOK_AFFINITY_MIN and DESIGN_HISTORY_HOOK_AFFINITY_MAX in order to indicate its affinity to the element, where MIN indicates little or no affinity and MAX indicates very high affinity. If the hook returns DESIGN_HISTORY_HOOK_AFFINITY_MAX, then it will be chosen (unless a hook that was registered earlier also returns this value). If the hook function does not or cannot handle the specified element at all, then it should just return ERROR.

2. When Design History wants the hook to do the comparison, the affinity parameter will be NULL. In this case, the hook should do the comparison.

Remarks: preChange and postChange are temporary copies that will be freed soon after this call is made.; The compare hook is normally expected to display a modal dialog. There will be no bookend callback to tell the caller when the user is done examining the element.

Returns: ERROR if custom handler does not apply to the specified element

Parameters

[out]	affinity	optional: if specified, return the compare hook's affinity to this element as a number between DESIGN_HISTORY_HOOK_AFFINITY_MIN and DESIGN_HISTORY_HOOK_AFFINITY_MAX
[in]	file	the file containing the element
[in]	model	the ID of the model containing the element
[in]	preChange	the pre-change version of the element
[in]	postChange	the post-change version of the element
[in]	title	the purpose of the comparison or the source of the versions. When called from the Design History Element Changes dialog, this string will be "Element Changes". When called from the Conflicts dialog, this string will be "Conflict".
[in]	preChangeDescription	a description of the pre-change version. When called from the Design History Element Changes dialog, this string will be the earlier of the two revision numbers. When called from the Conflicts dialog, this string will be "Pre-existing version".
[in]	postChangeDescription	a description of the post-change version. When called from the Design History Element Changes dialog, this string will be the later of the two revision numbers. When called from the Conflicts dialog, this string will be "New version".

See also: mdlHistory_compareElements

typedef void HistoryFunc_CreatePost(DgnFileP pFile)

Signature of callback invoked after design history is initialized in a file.

Parameters

[in] pFile file in which history was initialized

See also: mdlHistory_Delete

typedef StatusInt HistoryFunc_CreatePre(DgnFileP pFile)

Signature of callback invoked before design history is initialized in a file.

Parameters

[in] pFile file in which history is to be initialized

Returns: callback should return non-zero if history should NOT be initialized.

See also: mdlHistory_create

typedef void HistoryFunc_DeleteEarlyRevisionsPost(DgnFileP file, WCharCP tooOld, StatusInt status)

Signature of callback invoked after revisions in history are removed, or if the attempt to delete revisions failed.

All revisions from 'tooOld' and earlier were deleted.

Parameters

[in]	file	the file containing history that was modified
[in]	tooOld	the revision number identifying the end of the range of history removed
	status	if non-zero, then the attempt to delete revisions failed

See also: HistoryFunc_DeleteEarlyRevisionsPost; HistoryCallback::AddDeleteEarlyRevisionsPostFunction

typedef StatusInt HistoryFunc_DeleteEarlyRevisionsPre(DgnFileP file, WCharCP tooOld)

Signature of callback invoked before revisions in history are removed.

All revisions from 'tooOld' and earlier are deleted.

Parameters

[in]	file	the file containing history to be modified
[in]	tooOld	the revision number identifying the end of the range of history to be removed

Returns: If the callback may return a non-zero error status, the deleting will not be done. To allow the deletion, return 0.

See also: HistoryFunc_DeleteEarlyRevisionsPost; HistoryCallback::AddDeleteEarlyRevisionsPreFunction

typedef void HistoryFunc_DeletePost(DgnFileP pFile, StatusInt status)

Signature of callback invoked after design history is deleted from a file.

Parameters

[in]	pFile	file in which history was deleted
[in]	status	the result of the delete

See also: mdlHistory_Delete

typedef StatusInt HistoryFunc_DeletePre(DgnFileP pFile)

Signature of callback invoked before design history is deleted from a file.

Parameters

[in] pFile file in which history is to be deleted

Returns: callback should return non-zero if history should NOT be deleted.

See also: mdlHistory_Delete

typedef StatusInt HistoryFunc_DescribeElement(int *affinity, WCharP type, WCharP name, DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP element, int maxtype, int maxname)

Signature of custom element description handler.

Remarks: This function is called in one of two modes:

1. When Design History wants to query the hook function's affinity to the specified element, the affinity parameter is non-NULL (the type and name parameters will also be NULL). In this case, the hook should not describe the element, but should set the affinity parameter to a number between DESIGN_HISTORY_HOOK_AFFINITY_MIN and DESIGN_HISTORY_HOOK_AFFINITY_MAX in order to indicate its affinity to the element, where MIN indicates little or no affinity and MAX indicates very high affinity. If the hook returns DESIGN_HISTORY_HOOK_AFFINITY_MAX, then it will be chosen (unless a hook that was registered earlier also returns this value). If the hook function does not or cannot handle the specified element at all, then it should just return ERROR.

2. When Design History wants the hook to describe the element, the affinity parameter will be NULL. In this case, the hook should describe the element.

Remarks: element is a temporary copy that will be freed soon after this call is made.

Returns: ERROR if custom handler does not apply to the specified element

Parameters

[out]	affinity	optional: if specified, return the hook's affinity to this element as a number between DESIGN_HISTORY_HOOK_AFFINITY_MIN and DESIGN_HISTORY_HOOK_AFFINITY_MAX
[out]	type	a description of the element's type
[out]	name	a string that identifies the element
[in]	file	the file containing the element
[in]	model	the ID of the model containing the element
[in]	element	the ID of the element to query
[in]	maxtype	max number of characters to write to type
[in]	maxname	max number of characters to write to name

See also: mdlHistory_describeElement

typedef StatusInt HistoryFunc_DisplayElement(int *affinity, DgnFileP file, DgnPlatform::ModelId model, MSElementDescrCP element, WCharCP descriptionString, WCharCP changeTypeString)

Signature of custom element display handler.

Remarks: This function is called in one of two modes:

1. When Design History wants to query the hook function's affinity to the specified element, the affinity parameter is non-NULL. In this case, the hook should not actually display the element, but should set the affinity parameter to a number between DESIGN_HISTORY_HOOK_AFFINITY_MIN and DESIGN_HISTORY_HOOK_AFFINITY_MAX in order to indicate its affinity to the element, where MIN indicates little or no affinity and MAX indicates very high affinity. If the hook returns DESIGN_HISTORY_HOOK_AFFINITY_MAX, then it will be chosen (unless a hook that was registered earlier also returns this value). If the hook function does not or cannot handle the specified element at all, then it should just return ERROR.

2. When Design History wants the hook to display the element, the affinity parameter will be NULL. In this case, the hook should display the element.

Remarks: element is a temporary copy that will be freed soon after this call is made.; The display hook is normally expecited to display a modal dialog. There will be no bookend callback to tell the caller when the user is done examining the element.

Returns: ERROR if custom handler does not apply to the specified element

Parameters

[out]	affinity	optional: if specified, return the hook's affinity to this element as a number between DESIGN_HISTORY_HOOK_AFFINITY_MIN and DESIGN_HISTORY_HOOK_AFFINITY_MAX
[in]	file	the file containing the element to query
[in]	model	the ID of the model containing the element to query
[in]	element	the element to display
[in]	descriptionString	element description.
[in]	changeTypeString	description of the change type.

See also: mdlHistory_displayElement

typedef StatusInt HistoryFunc_FmtRevisionNumber(WCharP buf, WCharCP num, int maxbuf, DgnFileP file)

Signature of callback invoked to format history revision number.

Parameters

[out]	buf	buffer into which formatted revision number is to be written
[in]	num	revision number to be formatted
[in]	maxbuf	max number of characters to be written to buf
[in]	file	the design file that contains design history

Returns: non-zero if number could not be formatted

See also: HistoryFunc_FmtRevisionNumber

typedef void HistoryFunc_RestorePost(DgnFileP file, WCharCP targetRev, BentleyDgnHistoryModelsToElementChangesMapCP elements)

Signature of callback invoked after changes are restored from design history.

Parameters

[in]	file	the file being modified
[in]	targetRev	the revision number to which the file is being restored
[in]	elements	optional: the specific elements being restored. If NULL, all changed elements are being restored.

See also: HistoryFunc_RestorePre

typedef StatusInt HistoryFunc_RestorePre(DgnFileP file, WCharCP targetRev, BentleyDgnHistoryModelsToElementChangesMapCP elements)

Signature of callback invoked before changes are restored from design history.

Parameters

[in]	file	the file being modified
[in]	targetRev	the revision number to which the file is being restored
[in]	elements	optional: the specific elements being restored. If NULL, all changed elements are being restored.

Returns: non-zero if these elements should not be restored.

See also: HistoryFunc_RestorePost

typedef void HistoryFunc_UpdateRevisionUserDescPost(DgnFileP file, WCharCP rev, WCharCP user, WCharCP desc, StatusInt status)

Signature of callback invoked after the description and/or user name, or if the attempt to change the data failed.

Parameters

[in]	file	the file containing history that was modified
[in]	rev	the revision number identifying the revision that was modified
[in]	user	if non-NULL, the new user name that was assigned to the revision
[in]	desc	if non-NULL, the new description that was assigned to the revision
	status	if non-zero, then the attempt to change the data failed

See also: HistoryCallback::AddUpdateRevisionUserDescPostFunction; HistoryFunc_UpdateRevisionUserDescPre

typedef StatusInt HistoryFunc_UpdateRevisionUserDescPre(DgnFileP file, WCharCP rev, WCharCP user, WCharCP desc)

Signature of callback invoked before the description and/or user name of the specified revision are modified.

Parameters

[in]	file	the file containing history to be modified
[in]	rev	the revision number identifying the revision to be modified
[in]	user	if non-NULL, the new user name to be assigned to the revision
[in]	desc	if non-NULL, the new description to be assigned to the revision

Returns: If the callback may return a non-zero error status, the update will not be done. To allow the update, return 0.

See also: HistoryCallback::AddUpdateRevisionUserDescPreFunction; HistoryFunc_UpdateRevisionUserDescPost

typedef struct historyRevisionInfo HistoryRevisionInfo

Documents a set of changes in design history.

Function Documentation

static void AddCombinePostFunction ( HistoryFunc_CombinePost newFunc )

static

An MDL application can use this to set a function to be called after revisions in history are netted out and combined, or after the attempt to combine fails.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveCombinePostFunction

See also: HistoryFunc_CombinePost

static void AddCombinePreFunction ( HistoryFunc_CombinePre newFunc )

static

An MDL application can use this to set a function to be called before revisions in history are netted out and combined.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveCombinePreFunction

See also: HistoryFunc_CombinePre

static void AddCommitPostFunction ( HistoryFunc_CommitPost newFunc )

static

An MDL application can use this to set a function to be called after a set of changes is committed to design history.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveCommitPostFunction

See also: HistoryFunc_CommitPost

static void AddCommitPreFunction ( HistoryFunc_CommitPre newFunc )

static

An MDL application can use this to set a function to be called just before changes are committed to design history.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveCommitPreFunction.

See also: HistoryFunc_CommitPre

static void AddCompareElementsFunction ( HistoryFunc_CompareElements newFunc )

static

An MDL application can use this to set a function to be called when design history needs to allow the user to interactively compare revisions of an element.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveCompareElementsFunction

See also: HistoryFunc_CompareElements

static void AddCreatePostFunction ( HistoryFunc_CreatePost newFunc )

static

An MDL application can use this to set a function to be called after design history is initialized in a file.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveCreatePostFunction

See also: HistoryFunc_CreatePost

static void AddCreatePreFunction ( HistoryFunc_CreatePre newFunc )

static

An MDL application can use this to set a function to be called before design history is initialized in file.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveCreatePreFunction

See also: HistoryFunc_CreatePre

static void AddDeleteEarlyRevisionsPostFunction ( HistoryFunc_DeleteEarlyRevisionsPost newFunc )

static

An MDL application can use this to set a function to be called after revisions in history are removed, or if the attempt to delete revisions failed.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveDeleteEarlyRevisionsPostFunction

See also: HistoryFunc_DeleteEarlyRevisionsPost

static void AddDeleteEarlyRevisionsPreFunction ( HistoryFunc_DeleteEarlyRevisionsPre newFunc )

static

An MDL application can use this to set a function to be called before revisions in history are removed.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveDeleteEarlyRevisionsPreFunction

See also: HistoryFunc_DeleteEarlyRevisionsPre

static void AddDeletePostFunction ( HistoryFunc_DeletePost newFunc )

static

An MDL application can use this to set a function to be called after design history is deleted from a file.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveDeletePostFunction

See also: HistoryFunc_DeletePost

static void AddDeletePreFunction ( HistoryFunc_DeletePre newFunc )

static

An MDL application can use this to set a function to be called before design history is deleted from a file.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveDeletePreFunction

See also: HistoryFunc_DeletePre

static void AddDescribeElementFunction ( HistoryFunc_DescribeElement newFunc )

static

An MDL application can use this to set a function to be called when design history needs to show the user a description of an element.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveDisplayElementFunction

See also: HistoryFunc_DescribeElement

static void AddDisplayElementFunction ( HistoryFunc_DisplayElement newFunc )

static

An MDL application can use this to set a function to be called when design history needs to interactively display the properties of an element to the user.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveDisplayElementFunction

See also: HistoryFunc_DisplayElement

static void AddFmtRevisionNumberFunction ( HistoryFunc_FmtRevisionNumber newFunc )

static

An MDL application can use this to set a function to be called to format history revision number.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveFmtRevisionNumberFunction

See also: HistoryFunc_FmtRevisionNumber

static void AddRestorePostFunction ( HistoryFunc_RestorePost newFunc )

static

An MDL application can use this to set a function to be called after changes are restored from design history.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveRestorePostFunction

See also: HistoryFunc_RestorePost

static void AddRestorePreFunction ( HistoryFunc_RestorePre newFunc )

static

An MDL application can use this to set a function to be called before changes are restored from design history.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveRestorePreFunction

See also: HistoryFunc_RestorePre

static void AddUpdateRevisionUserDescPostFunction ( HistoryFunc_UpdateRevisionUserDescPost newFunc )

static

An MDL application can use this to set a function to be called after the description and/or user name, or if the attempt to change the data failed.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveUpdateRevisionUserDescPostFunction

See also: HistoryFunc_UpdateRevisionUserDescPost

static void AddUpdateRevisionUserDescPreFunction ( HistoryFunc_UpdateRevisionUserDescPre newFunc )

static

An MDL application can use this to set a function to be called before the description and/or user name of the specified revision are modified.

Parameters

[in] newFunc The new function to call, or NULL.

Remarks: NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use HistoryCallback::RemoveUpdateRevisionUserDescPreFunction

See also: HistoryFunc_UpdateRevisionUserDescPre

StatusInt mdlHistory_collectRevisionDescriptors	(	WCharCP	fileName,
		WCharP	desc,
		int	bufLen,
		WCharCP	separator
	)

collect all of the uncommitted revision descriptors.

Parameters

[in]	fileName	the file to collect revision descriptors from
[out]	desc	the buffer for descriptor string
[in]	bufLen	the buffer length for descriptor string
[in]	separator	the seperator for seperating multiple comments

Returns: ERROR if the file cannot be opened for retrieving info.

StatusInt mdlHistory_commit	(	HistoryRevisionInfo *	pInfo,
		DgnFileP	pFile,
		const HistoryCommitParms *	pParms
	)

Record all changes to specified file in its design history since last commit.

Remarks: The HistoryRevisionInfo and HistoryCommitParms structures are defined in historylib.h

Parameters

[out]	pInfo	revision number, etc. of new revision if successful
[in]	pFile	file containing changes to commit
[in]	pParms	time, user, desc, etc.

Returns: SUCCESS if changes were committed successfully

See also: HistoryFunc_CommitPre HistoryFunc_CommitPost

StatusInt mdlHistory_compareElementsEx	(	DgnFileP	file,
		DgnPlatform::ModelId	model,
		MSElementDescrCP	preChange,
		MSElementDescrCP	postChange,
		WCharCP	title,
		WCharCP	preChangeDescription,
		WCharCP	postChangeDescription
	)

Invoke custom element diff analyzer.

Remarks: This function first calls the compare hooks to check their affinity to this element. It then calls the best compare hook to do the comparison.; preChange and postChange are temporary copies that will be freed soon after this call is made.

Returns: ERROR if no custom diff handler could be found or if none succeeded

Parameters

[in]	file	the file containing the element
[in]	model	the ID of the model containing the element
[in]	preChange	the pre-change version of the element
[in]	postChange	the post-change version of the element
[in]	title	the purpose or source of the comparison.
[in]	preChangeDescription	a description of the pre-change version.
[in]	postChangeDescription	a description of the post-change version.

See also: HistoryFunc_CompareElements

StatusInt mdlHistory_create ( DgnFileP pFile )

Initializes design history in file.

Parameters

[in] pFile file in which history is to be initialized

Returns: non-zero if history could not be initialized or is not permitted.

StatusInt mdlHistory_delete ( DgnFileP pFile )

Removes design history from file.

Parameters

[in] pFile file from which history is to be removed.

Returns: non-zero if history could not be removed or removal is not permitted.

StatusInt mdlHistory_describeElement	(	WCharP	type,
		WCharP	name,
		DgnFileP	file,
		DgnPlatform::ModelId	model,
		MSElementDescrCP	element,
		int	maxtype,
		int	maxname
	)

Invoke custom element description handler.

Remarks: This function will first call each hook to get its affinity and then will call the best hook to describe the element.; element is a temporary copy that will be freed soon after this call is made.

Parameters

[out]	type	a description of the element's type
[out]	name	a string that identifies the element
[in]	file	the file containing the element
[in]	model	the ID of the model containing the element
[in]	element	the ID of the element to query
[in]	maxtype	max number of characters to write to type
[in]	maxname	max number of characters to write to name

Returns: ERROR if no custom description handler could be applied to the specified element

See also: HistoryFunc_DescribeElement

StatusInt mdlHistory_displayElement	(	DgnFileP	file,
		DgnPlatform::ModelId	model,
		MSElementDescrCP	element,
		WCharCP	descriptionString,
		WCharCP	changeTypeString
	)

Invoke custom element display handler.

Remarks: This function will first call each hook to get its affinity and then will call the best hook to display the element.; element is a temporary copy that will be freed soon after this call is made.; If element is NULL, then the element display handler should close

Returns: ERROR if no custom element display handler could be found or if none succeeded

Parameters

[in]	file	the file containing the element or NULL
[in]	model	the ID of the model containing the element or 0
[in]	element	the element to display or NULL
[in]	descriptionString	element description.
[in]	changeTypeString	description of the change type.

See also: HistoryFunc_DisplayElement

bool mdlHistory_exists ( DgnFileP pFile )

Check if the specified file has design history.

Parameters

[in] pFile file for which history is checked

Returns: true if the file has history enabled

See also: mdlHistory_create; mdlHistory_create

void mdlHistory_fmtRevisionNumber	(	WCharP	buf,
		WCharCP	num,
		int	maxbuf,
		DgnFileP	file
	)

Formats a history revision number.

Remarks: Will call on registered formatting functions

Parameters

[out]	buf	buffer into which formatted revision number is to be written
[in]	num	revision number to be formatted
[in]	maxbuf	max number of characters to be written to buf
[in]	file	the file in which the revision number appears - this determines what format to use

See also: HistoryFunc_FmtRevisionNumber

void mdlHistory_fmtRevisionNumberByFormat	(	WCharP	buf,
		WCharCP	num,
		WCharCP	fmt,
		int	maxbuf,
		bool	reserved
	)

Format a history revision number according to the specified format.

Remarks

The format specifies how the two fields of the revision number are to be formatted, in the context of other text. The two fields of the revision number are the major revision number and minor revision number. The major number is identified in the format as field number 0, and the minor number is field number 1.

The format is of the form:

formatClause := { [ "[" range "]" ] messageFormatPattern }+
messageFormatPattern := string [ "{" messageFormatElement "}" string ]*
range := start [,end]
messageFormatElement := argument [ "," elementFormat ]
elementFormat := "letter" [ "," letterStyle ]
               | "number"
letterStyle   := { "uppercase"|"lowercase"|"AA"|"AB"|{"omit" letter}* }+

If a range is specified, then the formatting instructions that follow apply only to revisions in the specified range. A messageFormatPattern can have multiple ranges and their associated messageFormatElements.

The elementFormat is optional. The default is to format the number as a number.

When formatting a revision number as a letter, the numerical value selects the corresponding number in the alphabet. That is, 1->A, 2->B, etc. The optional letterStyle specifies if uppercase or lowercase letters are used. Uppercase is the default. The optional letterStyle can also be used to omit specific letters from the alphabet. When the numerical value passes 26, a combination of letters is produced. The letterStyle specifies how letters are combined. If AA is specified, then the letters are repeated. If AB is specified, then the letters accumulate kind of like an odometer. More specifically, the revision number is first converted to a base-0 index and then converted to a base-26 number. If AA is specified, then the lowest base-26 digit is used as a 0-based index to select a letter, and that letter is repeated as many times as the number is a multiple of 26, plus 1. If AB is specified, then the highest base-26 digit is the decremented, and each base-26 digit is used as a 0-based index to select a letter. (If letters are omitted, then the base will not be 26, but however many letters remain in the alphabet.)

Num     AA      AB
---     ---     ---
1       A       A
2       B       B
..
26      Z       Z
27      AA      AA
28      BB      AB
..
52      ZZ      AZ
53      AAA     BA
54      BBB     BB
..
78      ZZZ     BZ
79      AAAA    CA

Examples

Revision Number     Desired Appearance      Format Specifier
2                 A2                      {0,letter}{1}
2                 A.2                     {0,letter}.{1}
2                 1.B                     {0}.{1,letter}
2                 2A                      {1}{0,letter}
2                 B2                      {1,letter}{0}
2                 RevA2                   Rev{1,letter}{0}
2                 RevA2***                Rev{1,letter}{0}***
28                1.BB                    {0}{1,letter,AA}
28                1.AB                    {0}{1,letter,AB}

Range examples:

[2.1] {0}.{1,letter}

means that revisions starting with 2.1 should be formatted as number.letter, while all revisions before that should be formatted in the default manner (i.e., number.number).

[2.1] {0}.{1,letter} [3.3] {0},{1,letter,AB}

means that revisions between 2.1 and 3.3 (inclusive) should be formatted as number.letter in AA style, while revisions after 3.3 should be formatted as number.letter in AB style.

Parameters

[out]	buf	buffer into which formatted revision number is to be written
[in]	num	revision number to be formatted
[in]	maxbuf	max number of characters to be written to buf
[in]	fmt	the format specifier
[in]	reserved	reserved for future use - must be 0

StatusInt mdlHistory_queryCompareElements	(	DgnFileP	file,
		DgnPlatform::ModelId	model,
		MSElementDescrCP	postChange
	)

Query if any registered compare hook will handle this element.

Remarks: This function calls the compare hooks to check their affinity to this element.

Parameters

[in]	file	the file containing the element
[in]	model	the ID of the model containing the element
[in]	postChange	the post-change version of the element

See also: HistoryFunc_CompareElements

Returns: ERROR if no custom diff handler could be applied to the specified element

StatusInt mdlHistory_queryDescribeElement	(	DgnFileP	file,
		DgnPlatform::ModelId	model,
		MSElementDescrCP	element
	)

Query if any registered element describe hook will handle this element.

Parameters

[in]	file	the file containing the element
[in]	model	the ID of the model containing the element
[in]	element	the ID of the element to query

Returns: ERROR if no custom description handler applies to the specified element

StatusInt mdlHistory_queryDisplayElement	(	DgnFileP	file,
		DgnPlatform::ModelId	model,
		MSElementDescrCP	element
	)

Query if any registered element display hook will handle this element.

Parameters

[in]	file	the file containing the element or NULL
[in]	model	the ID of the model containing the element or 0
[in]	element	the element to display or NULL

Returns: ERROR if no custom display handler could be applied to the specified element

static bool RemoveCombinePostFunction ( HistoryFunc_CombinePost oldFunc )

static

Removes a callback function previously installed using HistoryCallback::AddCombinePostFunction.

Parameters