Provides access to the design history of a specified file. More...

#include <DesignHistory.h>

Classes
struct	TagDefinition
	The definition of a tag. More...

Public Member Functions
DGNPLATFORM_EXPORT	DesignHistory (DgnFileR)
	Constructor. More...

DGNPLATFORM_EXPORT	DesignHistory ()

DgnFileP	GetDgnFileP () const
	Query the DgnFile to which this applies. More...

DGNPLATFORM_EXPORT StatusInt	CheckFormatVersion (bool prompt) const
	Utility to check design history file format version. More...

Query revisions in design history
DGNPLATFORM_EXPORT RevisionNumber	GetTip () const
	Query tip revision number. More...

DGNPLATFORM_EXPORT RevisionNumber	GetNextPossibleRevisionNumber (DgnHistory::RevisionNumber const &r)
	Query the next revision number that could possibly follow the specified number in this file. More...

DGNPLATFORM_EXPORT RevisionNumber	GetEarliest () const
	Query first revision number. More...

DGNPLATFORM_EXPORT StatusInt	GetRevisionNumbers (RevisionNumbersForFile &revNos, RevisionNumber const &startRevNo=RevisionNumber(), RevisionNumber const &endRevNo=RevisionNumber()) const
	Get revision numbers in specified range. More...

DGNPLATFORM_EXPORT StatusInt	GetRevisions (T_RevisionInfoVector &revs, RevisionNumbersForFile &nums, ElementChangeRecordFilter const *ssfilter=0, bool removeRejectedRevisions=false) const
	Get information about the specified revisions. More...

DGNPLATFORM_EXPORT StatusInt	GetTags (bvector< TagDefinition > &tags)
	Get all tags defined in design history. More...

DGNPLATFORM_EXPORT StatusInt	GetTag (DgnHistory::RevisionNumber revNo, WChar const tag)
	Get the revision number associated with the specified tag. More...

DGNPLATFORM_EXPORT StatusInt	SetTag (WChar const *tag, RevisionNumber const &revNo, bool replaceExisting)
	Associate a tag with the specified revision number. More...

DGNPLATFORM_EXPORT StatusInt	RemoveTag (WChar const *tag)
	Remove the specified tag from design history. More...

Query element versions in design history
DGNPLATFORM_EXPORT RefCountedPtr < ElementsAsOfQuery >	QueryPreChangeState (RevisionNumbersForFile const &range)
	Query the pre-change state of all elements involved in the specified revisions. More...

DGNPLATFORM_EXPORT RefCountedPtr < ElementsAsOfQuery >	QueryPostChangeState (RevisionNumbersForFile const &range)
	Query the post-change state of all elements involved in the specified revisions. More...

DGNPLATFORM_EXPORT StatusInt	QueryElementAsOf (EditElementHandleR historicalVersion, ModelId modelId, ElementId elementId, RevisionNumber const &rev)
	Query the state of the specified element as of the specified revision. More...

Commit changes to design history
DGNPLATFORM_EXPORT bool	CheckUncommittedChanges (bool force=false) const
	Check if there are any uncommitted changes. More...

DGNPLATFORM_EXPORT StatusInt	Commit (RevisionInfo *result, CommitInfo const &parms, bool ignoreVersion=false) const
	Commit recent changes to design history. More...

Static Public Member Functions
static DGNPLATFORM_EXPORT StatusInt	ExtractModelElementInfo (ModelInfoR pInfo, MSElementDescrCP modelElement, DgnFileP dgnFile)
	Extract the model info from a model header element. More...

static DGNPLATFORM_EXPORT StatusInt	GetLastError (WStringR details)
	Query the value of the most recent history-related error. More...

Detect, initialize, and delete design history
DGNPLATFORM_EXPORT StatusInt	CombineRevisions (RevisionNumber const &start, RevisionNumber const &end, CommitInfo const &parms)
	Combine a range of revisions into a single revision that captures the net outcome of the original change set. More...

DGNPLATFORM_EXPORT StatusInt	DeleteEarlyRevisions (RevisionNumber const &tooOld)
	Remove all revisions from and including tooOld to the beginning of history. More...

DGNPLATFORM_EXPORT StatusInt	UpdateRevision (RevisionNumber const &revNo, WChar const user, WChar const desc)
	Update the userid and/or description associated with the specified revision. More...

static DGNPLATFORM_EXPORT bool	ContainsHistory (DgnFileR)
	Test if the specified file has design history. More...

static DGNPLATFORM_EXPORT StatusInt	InitializeHistory (DgnFileR file, WChar const *comment)
	Initialize design history in the specified file. More...

static DGNPLATFORM_EXPORT StatusInt	RemoveHistory (DgnFileR)
	Remove design history from the specified file. More...

Revision number formatting and parsing
DGNPLATFORM_EXPORT WString	GetRevisionNumberFormat () const
	Get the revision number format to apply to revision numbers in this file. More...

DGNPLATFORM_EXPORT void	SetRevisionNumberFormat (WChar const *)
	Set the revision number format to apply to revision numbers in this file. More...

DGNPLATFORM_EXPORT WString	FormatRevisionNumber (DgnHistory::RevisionNumber const &)
	Format a revision number, using the registered format for this file. More...

DGNPLATFORM_EXPORT RevisionNumber	ParseRevisionNumber (WChar const str, WChar const fmt=0) const
	Format a revision number, using the specified format. More...

static DGNPLATFORM_EXPORT WString	FormatRevisionNumber (DgnHistory::RevisionNumber const &, WChar const *)
	Format a revision number, using the specified format. More...

Detailed Description

Provides access to the design history of a specified file.

Design history is a mechanism for recording changes to a design file. The main methods are:

DesignHistory::CheckUncommittedChanges - Query if the file has recent changes not yet committed to history
DesignHistory::Commit - Record recent changes in a new revision in history
DesignHistory::GetRevisionNumbers - Query revisions in a range in history
DesignHistory::GetRevisions - Get the time, description, etc. for revisions
DesignHistory::QueryPreChangeState - Get the historical state of elements
DesignHistory::QueryPostChangeState - Get the historical state of elements

Administrative methods:

DesignHistory::InitializeHistory - set up a file to begin recording design history.
DesignHistory::RemoveHistory - remove design history from a file.
DesignHistory::CombineRevisions - net out a range of revisions
DesignHistory::DeleteEarlyRevisions - delete old revisions
DesignHistory::UpdateRevision - modify revision annotation information

See also: DesignHistory Code Samples

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

Constructor & Destructor Documentation

DGNPLATFORM_EXPORT DesignHistory ( DgnFileR )

explicit

Constructor.

DGNPLATFORM_EXPORT DesignHistory ( )

Member Function Documentation

DGNPLATFORM_EXPORT StatusInt CheckFormatVersion ( bool prompt ) const

Utility to check design history file format version.

Returns: HISTORY_ERROR_FORWARD_COMPATIBILITY if file was created/modified by a newer version of MicroStation HISTORY_ERROR_BACKWARD_COMPATIBILITY if file was created/modified by an earlier version of MicroStation

Parameters

[in] prompt set to true if you want to prompt the user to confirm in the case where history was created/modified by an earlier version. If the user declines, HISTORY_ERROR_BACKWARD_COMPATIBILITY is returned.

DGNPLATFORM_EXPORT bool CheckUncommittedChanges ( bool force = false ) const

Check if there are any uncommitted changes.

Parameters

force in optional. If force is true, this method scans the file to check for changes. If it finds none, it also makes sure that the archive flags are clear on all elements.

Remarks: In force mode, this method can be time-consuming and can modify the file. In non-force mode, this method is very quick and does not modify the file.

DGNPLATFORM_EXPORT StatusInt CombineRevisions	(	RevisionNumber const &	start,
		RevisionNumber const &	end,
		CommitInfo const &	parms
	)

Combine a range of revisions into a single revision that captures the net outcome of the original change set.

If successful, a new revision is created and the original revisions are deleted.

Remarks: The new revision has the revision number and time of the end of the range. The new revision has the specified user ID and comment.; The start and end revisions are included in the range of revisions that are deleted and replaced.

Parameters

[in]	start	revision number of start of range of revisions to combine (inclusive)
[in]	end	revision number of end of range of revisions to combine (inclusive)
[in]	parms	the user and description for the combined revision

Returns: SUCCESS if the specified revisions were combined, HISTORY_ERROR_PERMISSION_DENIED if the delete capability is disabled, HISTORY_ERROR_NOCHANGES if there are one or zero revisions in the specified range, or a non-zero status code if history could not be updated.

Remarks: Capabilities:

This function requires the MS_DESIGN_HISTORY=delete=1 capability to be enabled.

Remarks: This function cannot be used directly on a distributed DGN server file. To combine revisions in a distributed DGN server file, the file must first be unshared.

See also: DeleteEarlyRevisions

DGNPLATFORM_EXPORT StatusInt Commit	(	RevisionInfo *	result,
		CommitInfo const &	parms,
		bool	ignoreVersion = `false`
	)		const

Commit recent changes to design history.

If successful, creates a new revision. Optionally reports the new revision in result.

Returns

a non-zero error status if the commit failed.

HISTORY_ERROR_NOCHANGES - there are no pending changes to commit. This is not really an error - just a warning that no revision was created.
HISTORY_ERROR_HISTORY_NOT_FOUND - design history is not initialized in the file.
HISTORY_ERROR_PERMISSION_DENIED - commit is disabled in MS_HISTORY_CAPABILITIES
HISTORY_ERROR_COULD_NOT_REOPEN_FILE_READWRITE - the design file is locked by another user or process.
HISTORY_ERROR_COULD_NOT_OPEN_FILE_READWRITE - Probably a function higher up on the callstack has history open read-only.
MDLERR_BADARG - parms is invalid - this usually means that the userid field has been left blank.
HISTORY_ERROR_INVALID_REVISION_NUMBER - parms specifies a new revision number, but the number is out of range.
HISTORY_ERROR_FORWARD_COMPATIBILITY - Design history is read-only, because it was last modified by a newer version of MicroStation.
HISTORY_ERROR_BACKWARD_COMPATIBILITY - Commit would upgrade history, making it read-only to older versions of MicroStation. See MS_HISTORY_CAPABILITIES.

See also: DesignHistory Code Samples

Parameters

result	if not NULL, this is set to the results of the commit
parms	user, description, and optional revision number for commit
ignoreVersion	skip the tests for forward and backward compatibility

static DGNPLATFORM_EXPORT bool ContainsHistory ( DgnFileR )

static

Test if the specified file has design history.

See also: DesignHistory Code Samples

DGNPLATFORM_EXPORT StatusInt DeleteEarlyRevisions ( RevisionNumber const & tooOld )

Remove all revisions from and including tooOld to the beginning of history.

Parameters

[in] tooOld delete all from 1.1 up to and including this revision

Returns: non-zero error status if revisions could not be deleted.

static DGNPLATFORM_EXPORT StatusInt ExtractModelElementInfo	(	ModelInfoR	pInfo,
		MSElementDescrCP	modelElement,
		DgnFileP	dgnFile
	)

static

Extract the model info from a model header element.

This function is useful when querying historical changes and encountering a model-level change. In that case, the history manager will supply an element representing the model's state as of that time. This function can be used to query the ID and other properties of the model as of that state.

Remarks: Normally, to get current information about an existing model, you would use DgnModel::GetModelInfo.

DGNPLATFORM_EXPORT WString FormatRevisionNumber ( DgnHistory::RevisionNumber const & )

Format a revision number, using the registered format for this file.

static DGNPLATFORM_EXPORT WString FormatRevisionNumber	(	DgnHistory::RevisionNumber const &	,
		WChar const *
	)

static

Format a revision number, using the specified format.

DgnFileP GetDgnFileP ( ) const

Query the DgnFile to which this applies.

DGNPLATFORM_EXPORT RevisionNumber GetEarliest ( ) const

Query first revision number.

static DGNPLATFORM_EXPORT StatusInt GetLastError ( WStringR details )

static

Query the value of the most recent history-related error.

Also returns a message from the O/S giving details about the error.

Remarks: This function should only be called after a history-related method call returns a non-zero error status.

Parameters

[out] details A message from the O/S giving details about the error.

Returns: non-zero error status

DGNPLATFORM_EXPORT RevisionNumber GetNextPossibleRevisionNumber ( DgnHistory::RevisionNumber const & r )

Query the next revision number that could possibly follow the specified number in this file.

Remarks: The returned number does not necessarily identify an actual revision in the file.; The returned number will have the same number of digits as the file's tip revision number.

DGNPLATFORM_EXPORT WString GetRevisionNumberFormat ( ) const

Get the revision number format to apply to revision numbers in this file.

DGNPLATFORM_EXPORT StatusInt GetRevisionNumbers	(	RevisionNumbersForFile &	revNos,
		RevisionNumber const &	startRevNo = `RevisionNumber()`,
		RevisionNumber const &	endRevNo = `RevisionNumber()`
	)		const

Get revision numbers in specified range.

See also: DesignHistory Code Samples

Parameters

[out]	revNos	revision numbers
	startRevNo	starting revision
	endRevNo	ending revision

DGNPLATFORM_EXPORT StatusInt GetRevisions	(	T_RevisionInfoVector &	revs,
		RevisionNumbersForFile &	nums,
		ElementChangeRecordFilter const *	ssfilter = `0`,
		bool	removeRejectedRevisions = `false`
	)		const

Get information about the specified revisions.

See also: DesignHistory Code Samples

Parameters

[out]	revs	revisions found
[in,out]	nums	revision numbers to look up. This method calls nums.SetFile(this). This method also breaks out revision numbers for shared file queries.
	ssfilter	if not NULL, specifies that this function should return only revisions that pass this filter (applied on the server)
	removeRejectedRevisions	if not NULL, specifies that, if ssfilter rejects a revision, this function should not include that revision in revs.

DGNPLATFORM_EXPORT StatusInt GetTag	(	DgnHistory::RevisionNumber *	revNo,
		WChar const *	tag
	)

Get the revision number associated with the specified tag.

Parameters

[out]	revNo	if not NULL, this is set to the revision number associated with the tag, if found.
[in]	tag	The tag to look up.

Returns: non-zero error status if the tag is not defined.

DGNPLATFORM_EXPORT StatusInt GetTags ( bvector< TagDefinition > & tags )

Get all tags defined in design history.

Returns: non-zero error status if history could not be accessed.

Remarks: this function returns SUCCESS if there are no tags.

Parameters

[out] tags tags found

DGNPLATFORM_EXPORT RevisionNumber GetTip ( ) const

Query tip revision number.

See also: DesignHistory Code Samples

static DGNPLATFORM_EXPORT StatusInt InitializeHistory	(	DgnFileR	file,
		WChar const *	comment
	)

static

Initialize design history in the specified file.

Returns

HISTORY_ERROR_NOT_A_DGN_FILE if the file is not a V8 design file
HISTORY_ERROR_PERMISSION_DENIED if the file already has design history, or if the create history capability is not enabled.
other non-zero status code if there was an error modifying the file

See also: DesignHistory Code Samples

Parameters

file	file in which to initialize history
comment	if not NULL, the comment to be stored in Audit Trail

DGNPLATFORM_EXPORT RevisionNumber ParseRevisionNumber	(	WChar const *	str,
		WChar const *	fmt = `0`
	)		const

Format a revision number, using the specified format.

Parameters

[in]	str	the string to parse
[in]	fmt	If not NULL, the format to use. If NULL, the registered the registered format for this file is used.

Returns: the RevisionNumber constructed from the parse

DGNPLATFORM_EXPORT StatusInt QueryElementAsOf	(	EditElementHandleR	historicalVersion,
		ModelId	modelId,
		ElementId	elementId,
		RevisionNumber const &	rev
	)

Query the state of the specified element as of the specified revision.

See also: QueryPostChangeState; DesignHistory Code Samples

Parameters

historicalVersion	the historical version of the element
modelId	the model that holds(held) the element
elementId	the element's id
rev	the point in history

DGNPLATFORM_EXPORT RefCountedPtr<ElementsAsOfQuery> QueryPostChangeState ( RevisionNumbersForFile const & range )

Query the post-change state of all elements involved in the specified revisions.

Query the state of these elements as of the most recent revision in the range.

See also: QueryPreChangeState; DesignHistory Code Samples

Parameters

range the revisions to query

DGNPLATFORM_EXPORT RefCountedPtr<ElementsAsOfQuery> QueryPreChangeState ( RevisionNumbersForFile const & range )

Query the pre-change state of all elements involved in the specified revisions.

Query the state of these elements as of the earliest revision in the range.

See also: QueryPostChangeState; DesignHistory Code Samples

Parameters

range the revisions to query

static DGNPLATFORM_EXPORT StatusInt RemoveHistory ( DgnFileR )

static

Remove design history from the specified file.

Returns

HISTORY_ERROR_PERMISSION_DENIED if the file does not have design history, if the delete history capability is not enabled, or if the file is marked as a workfile or as a distributed DGN server file.
other non-zero status code if there was an error modifying the file

See also: DesignHistory Code Samples

DGNPLATFORM_EXPORT StatusInt RemoveTag ( WChar const * tag )

Remove the specified tag from design history.

Parameters

[in] tag The tag to remove.

Returns: non-zero error status if the tag was not found or could not be removed.

DGNPLATFORM_EXPORT void SetRevisionNumberFormat ( WChar const * )

Set the revision number format to apply to revision numbers in this file.

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
        1.2                 A2                      {0,letter}{1}
        1.2                 A.2                     {0,letter}.{1}
        1.2                 1.B                     {0}.{1,letter}
        1.2                 2A                      {1}{0,letter}
        1.2                 B2                      {1,letter}{0}
        1.2                 RevA2                   Rev{1,letter}{0}
        1.2                 RevA2***                Rev{1,letter}{0}***
        1.28                1.BB                    {0}{1,letter,AA}
        1.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 from 2.1 to 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.

DGNPLATFORM_EXPORT StatusInt SetTag	(	WChar const *	tag,
		RevisionNumber const &	revNo,
		bool	replaceExisting
	)

Associate a tag with the specified revision number.

Parameters

[in]	tag	The tag to assign.
[in]	revNo	The revision number to be named.
[in]	replaceExisting	if true, revNo should replace the value of any existing tag by the same name. If false, SetTag should return HISTORY_ERROR_DUPLICATE_TAG if the tag already exists.

Returns: HISTORY_ERROR_DUPLICATE_TAG if the tag already exists and replaceExisting is false. Other non-zero error status if the tag could not be written to design history.

DGNPLATFORM_EXPORT StatusInt UpdateRevision	(	RevisionNumber const &	revNo,
		WChar const *	user,
		WChar const *	desc
	)

Update the userid and/or description associated with the specified revision.

Parameters

revNo	The revision to modify
user	if not NULL, the new userID
desc	if not NULL, the new description

The documentation for this class was generated from the following file:

DesignHistory.h

Classes

Public Member Functions

Static Public Member Functions

Detect, initialize, and delete design history

Revision number formatting and parsing

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation