A DgnFile is an in-memory representation of a physical file, regardless of its format. More...

#include <DgnFile.h>

Classes
struct	LoadedModelsCollection
	Collection of all models that are currently loaded in a DgnFile. More...

Public Member Functions
void	GetUniqueModelName (WStringR uniqueModelName, WCharCP baseName, bool forCopy=false)
	Generate a model name that is not currently in use in this file. More...

DgnColorMapP	GetColorMapP ()
	Get the color map associated with this DgnFile. More...

DgnFontNumMapP	GetDgnFontMapP ()
	Get the font map associated with this DgnFile. More...

LsDgnFileMapP	GetLineStyleMapP ()
	Get the line style map associated with this DgnFile. More...

ViewGroupCollectionCR	GetViewGroups ()
	Get a const reference to the View Groups in this DgnFile. More...

NamedViewCollectionCR	GetNamedViews ()
	Get a const reference to the Named Views in this DgnFile. More...

BentleyStatus	SetModelBackgroundColor (RgbColorDef const &color, DgnModelType type)
	Set the background color for all models of a given type. More...

BentleyStatus	GetModelBackgroundColor (RgbColorDef &color, DgnModelType type)
	Get the background color for all models of the given type. More...

ModelId	GetLastActiveModelId ()
	Get the ModelId of the last active model. More...

Opening a design file
DgnFileStatus	LoadDgnFile (StatusInt *openForWriteStatus)
	Attempt to "load" this file. More...

StatusInt	FillDictionaryModel ()
	Make sure the dictionary model is filled. More...

StatusInt	FillSectionsInModel (DgnModelP model, DgnModelSections sectionsToFill=DgnModelSections::Model, DgnModelFillContext *unused=0)
	Make sure the specified model is filled. More...

Reference-Counting
int	AddRef ()
	Increment the reference count of this file. More...

int	Release ()
	Decrement the reference count of this file. More...

Finding Models
LoadedModelsCollection	GetLoadedModelsCollection () const
	Get the collection that can be used to iterate all models currently loaded from this file. More...

ModelIndex const &	GetModelIndex () const

DgnModelR	GetDictionaryModel ()
	Get the dictionary model for this file. More...

ModelId	FindModelIdByName (WCharCP name) const
	Find the ModelId of the model with the specified name. More...

ModelId	GetDefaultModelId () const
	Get the ModelId of the default model in this file. More...

DgnModelP	FindLoadedModelById (ModelId)
	Query if the specified model has already been loaded. More...

DgnModelPtr	LoadModelById (ModelId modelID)
	Search this file for a model with the specific ModelId, loading from disk if necessary. More...

Saving Changes, Abandoning Changes, Save As, and Save To
bool	HasPendingChanges ()
	Determine whether this file has any changes that need to be written to the disk. More...

void	SetFullSaveFlag ()
	Set the "full save" flag. More...

void	SetAbandonChangesFlag ()
	Set the "abandon changes" flag. More...

void	ClearAbandonChangesFlag ()
	Turn off the "abandon changes" flag. More...

StatusInt	ProcessChanges (DgnSaveReason reason, double timestamp=0)
	Process the changes in all of the DgnModels of this file, saving them to disk if appropriate. More...

StatusInt	DoSaveAs (DgnDocumentR newDoc, DgnFileFormatType format=DgnFileFormatType::V8, bool saveChanges=false, bool doPreSaveAsHooks=true)
	Save the DgnFile to a new physical file with the given file name. More...

StatusInt	DoSaveTo (WCharCP newFileName, DgnFileFormatType format=DgnFileFormatType::V8)
	Save the DgnFile to a new physical file with the given file name. More...

void	SetTransactable (bool yesNo)
	Allow ITxnManager to log changes to this file. More...

DgnFileAppData Management
StatusInt	AddAppData (DgnFileAppData::Key const &key, DgnFileAppData *appData)
	Add an application data object onto this DgnFile. More...

StatusInt	DropAppData (DgnFileAppData::Key const &key)
	Remove a DgnFileAppData object from this DgnFile by its key. More...

DgnFileAppData *	FindAppData (DgnFileAppData::Key const &key)
	Search for the DgnFileAppData on this DgnFile with `key`. More...

Static Public Member Functions
static bool	IsSameFile (WCharCP fileName1, WCharCP fileName2, FileCompareMask compareMask)
	Check if two fully qualified file-names represent the same physical file. More...

Prepare to open a DgnFile
static DgnFilePtr	Create (DgnDocumentR document, DgnFileOpenMode openMode)
	Create a new instance of a DgnFile. More...

static DgnFilePtr	CreateNew (DgnFileStatus &status, DgnDocumentR document, DgnFileOpenMode openMode, SeedDataCR seedData, DgnFileFormatType format, bool threeD)
	Create a new instance of a DgnFile, optionally from a seed file. More...

File properties
enum	SignatureCountType { SIGNATURE_COUNT_File =0, SIGNATURE_COUNT_Model =1, SIGNATURE_COUNT_All =-1 }
	Identifies which digital signatures should be counted by GetSignatureCount. More...

double	GetLastSaveTime ()
	Get the time that this file was last saved. More...

DgnDocumentPtr	GetDocumentPtr () const
	Get the DgnDocument associated with this file. More...

DgnDocumentCR	GetDocument () const
	Get the DgnDocument associated with this file. More...

WString	GetFileName () const
	Get the full path of the physical file associated with this file. More...

WString	GetPackagedName ()
	Get the PackagedFileName of this DgnFile. More...

WString	GetPackageName ()
	Get the PackageName for this DgnFile. More...

WString	GetEmbeddedName () const
	Get the EmbeddedName of this DgnFile. More...

UInt32	GetEmbeddedFileId () const
	Get the Embedded Id for this file. If the file is not embedded, the value will be 0. More...

bool	IsEmbeddedFile () const

StatusInt	GetVersion (DgnFileFormatType format, int majorVersion, int *minorVersion)
	Get the version information for this file. More...

bool	IsTransactable () const
	Determine whether this file is transactable (journalled by the ITxnManager and subject to undo/redo). More...

bool	IsLoaded () const
	Determine whether this file is currently "loaded". More...

bool	IsOpen () const
	Determine whether this file is currently opened. More...

bool	IsReadOnly () const
	Determine whether this file is read only. More...

bool	IsIModel () const
	Determine whether this file represents an IModel. More...

StatusInt	GetDocumentProperty (int propIDP, WCharCP nameP, int propType, int streamToUse, void *value)
	Get a document property Here is an example of how to update the editing time property in the summary stream: More...

StatusInt	SaveDocumentProperty (int propIDP, WCharCP nameP, int propType, int streamToUse, const void value)
	Set a document property. More...

FileLevelCacheR	GetLevelCacheR ()
	Get access to levels defined in this file. More...

size_t	GetSignatureCount (SignatureCountType ct=SIGNATURE_COUNT_All) const
	Get the number of digital signatures in this file. More...

Models
DgnModelP	CreateNewModel (DgnModelStatus *, WCharCP, DgnModelType, bool, DgnModelCP seedModel=0, ModelId modelId=(-2))
	Create a new root model (calls ITxn::CreateNewModel). More...

DgnModelP	CreateNewModel (DgnModelStatus *error, DgnFileR file, ModelInfoCR modelInfo, ModelId modelId=(-2))
	Create a new root model (calls ITxn::CreateNewModel). More...

StatusInt	DeleteModel (DgnModelR)
	Delete a model (calls ITxn::DeleteModel). More...

DgnModelP	LoadRootModelById (StatusInt *errorDetails, ModelId modelID, bool fillCache=false, bool andRefs=false, bool processAffected=false)
	Find a model in this file by its ModelId. More...

static BentleyStatus	CopyModelContents (DgnModelR destModel, DgnModelCR sourceModel, T_StdElementRefVector *dictionaryElements)
	Copy the contents of one model into another. More...

Detailed Description

A DgnFile is an in-memory representation of a physical file, regardless of its format.

Accessing an existing file

To create a new design file:

Call Create to create a DgnFile object.
Call LoadDgnFile to attempt to open an existing seed file.
Call DoSaveAs to create the new file.

Accessing an existing file

To open a design file:

Call Create to create a DgnFile object.
Call LoadDgnFile to attempt to open the disk file.

To access models:

A DgnFile is composed of Design Models. To access models:

Call GetModelIndex to detect what models are stored in a file.
Call FindModelIdByName to look up a specific model.
Call LoadRootModelById to get a DgnModel.

Call GetDictionaryModel to access data that applies to all models in a DgnFile. Levels, linestyles, and other styles are defined in the dictionary model. Special elements such as Shared cell definitions are also defined there.

To access elements:

All data for a DgnFile is stored in its Elements and their XAttributes. Elements are stored in models within a file. Opening a DgnFile does not cause it to load any element or XAttribute data. Likewise, model look-up functions such as LoadModelById do not load element data. To access elements, you must access a DgnModel and then "fill" it.

Call FillSectionsInModel before attempting to access elements in a DgnModel.
Use DgnModel methods to access elements.

Creating a new file

You must start with an existing file, which serves as a "seed". To create a DGN file:

Call Create to create a DgnFile object.
Call LoadDgnFile to attempt to open the seed file.
Call DoSaveAs to save the file to a new name.
DgnFilePtr file = DgnFile::Create (seedFileDocument, DgnFileOpenMode::ReadOnly);

if (file->LoadDgnFile () != DGNFILE_STATUS_Success)

return;

if (file->DoSaveAs (newFileDocument) != SUCCESS)

return;

Making changes

Call CreateNewModel to create a new model.
Use EditElementHandle to add, rewrite, or delete elements.
Call CopyModelContents to copy a model.
Call DeleteModel to remove a model.
Call ProcessChanges to save changes to disk.

Closing a file

A DgnFile is a reference-counted object. When done with a file:

Call Release (this is generally automatic via the DgnFilePtr smart pointer class).

Styles, Colors, Levels

Elements refer to levels, fonts, color definitions, and line styles defined in the containing DgnFile.

Call GetLevelCacheR to access level definitions used or available for use by elements in the file.
Call GetColorMapP to access color definitions used in the file.
Call GetDgnFontMapP to access the fonts used in the file.

Collections and Iterators

Document Properties

To read document properties, use ref GetDocumentProperty for simple properties and ref GetThumbnail for the thumbnail. To enumerate user properties, open the file as an IStorage and use the Windows property set api.

To write document properties, use ref SaveDocumentProperty for simple properties and ref SaveThumbnail for the thumbnail.

See also: Document Manager

Member Enumeration Documentation

enum SignatureCountType

Identifies which digital signatures should be counted by GetSignatureCount.

Enumerator
SIGNATURE_COUNT_File
SIGNATURE_COUNT_Model
SIGNATURE_COUNT_All

Member Function Documentation

StatusInt AddAppData	(	DgnFileAppData::Key const &	key,
		DgnFileAppData *	appData
	)

Add an application data object onto this DgnFile.

After this call, the appData object will be notified for the events in the DgnFileAppData interface. This is a useful technique for applications to store data that is specific to this DgnFile, as it can be retrieved quickly through a pointer to this DgnFile and because its lifecycle can be made to match the DgnFile.

Parameters

[in]	key	A unique key to differentiate `appData` from all of the other DgnFileAppData objects stored on this DgnFile. By convention, uniqueness is enforced by using the address of a (any) static object in your application. Since all applications share the same address space, every key will be unique. Note that this means that the value of your key will be different for every session. But that's OK, the only thing important about `key` is that it be unique.
[in]	appData	The application's instance of a subclass of DgnFileAppData to store on this DgnFile.

Returns: SUCCESS if appData was successfully added to this DgnFile. Note that it is not legal to add or drop DgnFileAppData to/from this DgnFile from within any of the methods of DgnFileAppData.

int AddRef ( )

Increment the reference count of this file.

Returns: the new reference count

void ClearAbandonChangesFlag ( )

Turn off the "abandon changes" flag.

When the "abandon" flag is on, none of the changes are written to the disk, even if ProcessChanges is called.

See also: SetAbandonChangesFlag

static BentleyStatus CopyModelContents	(	DgnModelR	destModel,
		DgnModelCR	sourceModel,
		T_StdElementRefVector *	dictionaryElements
	)

static

Copy the contents of one model into another.

Parameters

[in]	destModel	The destination of the copy. Should be a newly created model that is empty.
[in]	sourceModel	The model to be copied.
[in]	dictionaryElements	A list of elements from the dictionaryModel that should be copied. Generally, these are ViewGroups or NamedViews.

Remarks: To copy a model, first call CreateNewModel to create a new, empty model. Then call CopyModelContents to copy the contents of the source model into the new model.

static DgnFilePtr Create	(	DgnDocumentR	document,
		DgnFileOpenMode	openMode
	)

static

Create a new instance of a DgnFile.

Parameters

[in]	document	The document to open or create.
[in]	openMode	The open mode to use for LoadFile.

See also: LoadFile

static DgnFilePtr CreateNew	(	DgnFileStatus &	status,
		DgnDocumentR	document,
		DgnFileOpenMode	openMode,
		SeedDataCR	seedData,
		DgnFileFormatType	format,
		bool	threeD
	)

static

Create a new instance of a DgnFile, optionally from a seed file.

Parameters

[out]	status	Result of attempt to create file.
[in]	document	The document to create.
[in]	openMode	The open mode to use for LoadFile.
[in]	seedData	Specifies the data that is to be copied from the seed file.
[in]	format	The format of the output file.
[in]	threeD	Set the dimensionality of the default model.

Remarks: If the file specified by the document object exists, it will be deleted and replaced with the new file.; If a seed file is specified, the settings data specified by seedCopyFlags will be copied to the new file. The seed data can be modified by the seedProcessor, if one is specified.

See also: LoadFile

DgnModelP CreateNewModel	(	DgnModelStatus *	,
		WCharCP	,
		DgnModelType	,
		bool	,
		DgnModelCP	seedModel = `0`,
		ModelId	modelId = `(-2)`
	)

Create a new root model (calls ITxn::CreateNewModel).

DgnModelP CreateNewModel	(	DgnModelStatus *	error,
		DgnFileR	file,
		ModelInfoCR	modelInfo,
		ModelId	modelId = `(-2)`
	)

Create a new root model (calls ITxn::CreateNewModel).

StatusInt DeleteModel ( DgnModelR )

Delete a model (calls ITxn::DeleteModel).

StatusInt DoSaveAs	(	DgnDocumentR	newDoc,
		DgnFileFormatType	format = `DgnFileFormatType::V8`,
		bool	saveChanges = `false`,
		bool	doPreSaveAsHooks = `true`
	)

Save the DgnFile to a new physical file with the given file name.

After this call, this file refers to the new physical file.

Parameters

[in]	newDoc	The document that identifies the new file. Must have a full path.
[in]	format	The file format. Only DgnFileFormatType::V8 is supported unless hosted by MicroStation.
[in]	saveChanges	If there are changes to this file, save them to the original file before saving the new file.
[in]	doPreSaveAsHooks	If true, call pre-saveAs hooks functions (only when hosted by MicroStation).

See also: DoSaveTo

Remarks: newDoc must have a full path.

StatusInt DoSaveTo	(	WCharCP	newFileName,
		DgnFileFormatType	format = `DgnFileFormatType::V8`
	)

Save the DgnFile to a new physical file with the given file name.

After this call, this file continues to refer to the original file.

Parameters

[in]	newFileName	The new file name
[in]	format	The file format. Only DgnFileFormatType::V8 is supported unless hosted by MicroStation.

See also: DoSaveAs

StatusInt DropAppData ( DgnFileAppData::Key const & key )

Remove a DgnFileAppData object from this DgnFile by its key.

Parameters

[in] key The key to find the appropriate DgnFileAppData. See discussion of keys in AddAppData.

Returns: SUCCESS if a DgnFileAppData object with key was found and was dropped. ERROR if no DgnFileAppData with key exists.

Note: After the DgnFileAppData object is removed, its DgnFileAppData::_OnCleanup method is called.

StatusInt FillDictionaryModel ( )

Make sure the dictionary model is filled.

See also: LoadDgnFile, GetDictionaryModel

StatusInt FillSectionsInModel	(	DgnModelP	model,
		DgnModelSections	sectionsToFill = `DgnModelSections::Model`,
		DgnModelFillContext *	unused = `0`
	)

Make sure the specified model is filled.

Parameters

model	the model to fill
sectionsToFill	sections of the model to be filled. Defaults to both control and graphics sections.
unused	unused - must be NULL

See also: LoadDgnFile, FillDictionaryModel

DgnFileAppData* FindAppData ( DgnFileAppData::Key const & key )

Search for the DgnFileAppData on this DgnFile with key.

See discussion of keys in AddAppData.

Returns: A pointer to the DgnFileAppData object with key. NULL if not found.

DgnModelP FindLoadedModelById ( ModelId )

Query if the specified model has already been loaded.

See also: GetLoadedModelsCollection; LoadModelById

ModelId FindModelIdByName ( WCharCP name ) const

Find the ModelId of the model with the specified name.

Returns: The model's ModelId or INVALID_MODELID if not found.

DgnColorMapP GetColorMapP ( )

Get the color map associated with this DgnFile.

ModelId GetDefaultModelId ( ) const

Get the ModelId of the default model in this file.

DgnFontNumMapP GetDgnFontMapP ( )

Get the font map associated with this DgnFile.

DgnModelR GetDictionaryModel ( )

Get the dictionary model for this file.

See also: FillDictionaryModelSections

DgnDocumentCR GetDocument ( ) const

Get the DgnDocument associated with this file.

Returns: the DgnDocument associated with this file, or NULL

Note: This method returns NULL if this DgnFile does not represent a file or any actual document. For example, this DgnFile might be a temporary buffer used to hold data in memory only.

StatusInt GetDocumentProperty	(	int *	propIDP,
		WCharCP	nameP,
		int *	propType,
		int	streamToUse,
		void *	value
	)

Get a document property Here is an example of how to update the editing time property in the summary stream:

int    format = 0;
Int64  totalEditingTime = 0;
int    propID = PIDSI_EDITTIME;
GetDocumentProperty (&propID, NULL, &format, SUMMARY_STREAM, &totalEditingTime);
BeAssert (format == VT_FILETIME);
totalEditingTime += elapsedTime;
SaveDocumentProperty (&propID, NULL, VT_FILETIME, SUMMARY_STREAM, &totalEditingTime);

Here is an example of how to retrieve a string property from the mediasummary stream:

int propID = PIDMSI_SOURCE;
WChar sourceProperty[MAXFILELENGTH] = {L'\0'};    // must supply a buffer big enough to hold the longest string that might be stored.
int propType;
GetDocumentProperty (&propID, NULL, &propType, MEDIASUMMARY_STREAM, sourceProperty);

Parameters

[in]	propIDP	The id of the property to get. Must be specified if streamToUse is SUMMARY_STREAM, DOCSUMMARY_STREAM, or MEDIASUMMARY_STREAM. Must be one of the Windows PIDSI_, PIDDSI_, or PIDMSI_ identifiers, as appropriate for streamToUse.
[in]	nameP	If not NULL, the name of the property to get. Must be specified if streamToUse is USERDEFINED_PROPERTIES.
[in]	propType	Pointer to a variable that is set to the property value format on return. Will be set to one of the Windows VARENUM values.
[in]	streamToUse	The stream in which the property is stored. Must be one of: SUMMARY_STREAM DOCSUMMARY_STREAM USERDEFINED_STREAM MEDIASUMMARY_STREAM
[in]	value	A pointer to a buffer where the property value is returned. The buffer must be large enough to hold the value.

Returns: SUCCESS if the property was retrieved or non-zero if the property could not be retrieved.

Remarks: This function is not for retrieving the thumbnail property. See #GetThumbnail

DgnDocumentPtr GetDocumentPtr ( ) const

Get the DgnDocument associated with this file.

Returns: the DgnDocument associated with this file, or NULL

Note: This method returns NULL if this DgnFile does not represent a file or any actual document. For example, this DgnFile might be a temporary buffer used to hold data in memory only.

UInt32 GetEmbeddedFileId ( ) const

Get the Embedded Id for this file. If the file is not embedded, the value will be 0.

WString GetEmbeddedName ( ) const

Get the EmbeddedName of this DgnFile.

If the file is an embedded file, this will be just the Embed part of the PackagedFileName. If the file is not embedded, it will be the same as "GetName". Therefore this may or may not be a physical file and may or may not contain path information, depending on whether this file is embedded.

WString GetFileName ( ) const

Get the full path of the physical file associated with this file.

See also: GetDocument

ModelId GetLastActiveModelId ( )

Get the ModelId of the last active model.

Returns: The ModelId of the last active model, or INVALID_MODELID if there is no active model

double GetLastSaveTime ( )

Get the time that this file was last saved.

The DgnFile must be loaded before calling this method.

See also: ProcessChanges

FileLevelCacheR GetLevelCacheR ( )

Get access to levels defined in this file.

LsDgnFileMapP GetLineStyleMapP ( )

Get the line style map associated with this DgnFile.

LoadedModelsCollection GetLoadedModelsCollection ( ) const

Get the collection that can be used to iterate all models currently loaded from this file.

Does not include the dictionary model.

Example:

DgnFileR file = ...
for each (DgnModelP model in file.GetLoadedModelsCollection ())
    {
    file.FillSectionsInModel (model, DgnModelSections::All);
      ...
    }

See also: LoadModelById; GetModelIndex; DgnModel::GetElementsCollection

BentleyStatus GetModelBackgroundColor	(	RgbColorDef &	color,
		DgnModelType	type
	)

Get the background color for all models of the given type.

Returns: ERROR if type is not found.

ModelIndex const& GetModelIndex ( ) const

NamedViewCollectionCR GetNamedViews ( )

Get a const reference to the Named Views in this DgnFile.

WString GetPackagedName ( )

Get the PackagedFileName of this DgnFile.

This will be in Package<id>Embed format for embedded files and a filename for non-embedded files. Note: "Package" will have path information but "Embed" will not. This string MAY contain the "<>" characters that make it an illegal filename.

WString GetPackageName ( )

Get the PackageName for this DgnFile.

If the file is an embedded file this will be just the Package part of the PackagedFileName. If the file is not embedded, this will be the same as "GetName()". It is always the name of a physical file.

size_t GetSignatureCount ( SignatureCountType ct = SIGNATURE_COUNT_All ) const

Get the number of digital signatures in this file.

void GetUniqueModelName	(	WStringR	uniqueModelName,
		WCharCP	baseName,
		bool	forCopy = `false`
	)

Generate a model name that is not currently in use in this file.

Parameters

[out]	uniqueModelName	unique name that was generated, if possible
[in]	baseName	base model name to start with (optional)
[in]	forCopy	If the object with the new name is a copy of the object of 'baseName', then new name will be built with "- Copy" suffix

StatusInt GetVersion	(	DgnFileFormatType *	format,
		int *	majorVersion,
		int *	minorVersion
	)

Get the version information for this file.

The DgnFile must be loaded before calling this method.

Parameters

[out]	format	The format of this file (will be one of the values in DgnFileFormatType). May be NULL.
[out]	majorVersion	The major version number of this file. May be NULL.
[out]	minorVersion	The minor version number of this file. May be NULL.

ViewGroupCollectionCR GetViewGroups ( )

Get a const reference to the View Groups in this DgnFile.

bool HasPendingChanges ( )

Determine whether this file has any changes that need to be written to the disk.

See also: ProcessChanges

bool IsEmbeddedFile ( ) const

bool IsIModel ( ) const

Determine whether this file represents an IModel.

bool IsLoaded ( ) const

Determine whether this file is currently "loaded".

This will be true if LoadDgnFile has been successfully called.

See also: LoadDgnFile

bool IsOpen ( ) const

Determine whether this file is currently opened.

Note: Readonly files are opened, read, and then closed inside the call to LoadDgnFile. Therefore, readonly files will never return true for this method.

bool IsReadOnly ( ) const

Determine whether this file is read only.

static bool IsSameFile	(	WCharCP	fileName1,
		WCharCP	fileName2,
		FileCompareMask	compareMask
	)

static

Check if two fully qualified file-names represent the same physical file.

Parameters

[in]	fileName1	Fully qualified name of first file
[in]	fileName2	Fully qualified name of second file
[in]	compareMask	Mask which controls degree of comparison

Returns: true if the two files represent the same file

Remarks

The parameter compareMask is the OR'ed mask of one or more of the possible values:

FileCompareMask::BaseNameAndExtension: Check if base-name and extension are different. Set this if you wish to conclude that different base-name and extension represent different files. If different then return value is false.
FileCompareMask::FileStat: Check if file-stats are different. If different then return value is false.
FileCompareMask::All: Do all the checks

If the fully qualified names are the same, then the function will always return that the file-names represent the same file

bool IsTransactable ( ) const

Determine whether this file is transactable (journalled by the ITxnManager and subject to undo/redo).

DgnFileStatus LoadDgnFile ( StatusInt * openForWriteStatus )

Attempt to "load" this file.

"Loading" a file means to attempt to open the physical file and read the file header.

Note

This can fail for several reasons, such as:

the file doesn't exist
it can't be opened for read access (either because of access control or someone else is writing to it).
it is not in a valid format
it has an invalid version
etc.

Loading a file does NOT read any data from the file other than the file header. After calling this routine the file will ONLY be opened (IsOpen is true) if the file is opened for write access. However, it will always be "loaded" (IsLoaded returns true). In other words, DgnFiles that are readonly are loaded but not opened.

Parameters

[out] openForWriteStatus Set to the open-for-write status. This is useful if openMode is DgnFileOpenMode::PreferablyReadWrite, since the load will succeed even if the file can only be opened readonly. May be NULL.

See also: IsLoaded, FillDictionaryModel, FillSectionsInModel

DgnModelPtr LoadModelById ( ModelId modelID )

Search this file for a model with the specific ModelId, loading from disk if necessary.

Parameters

[in] modelID The ModelId of the model of interest.

See also: FillSectionsInModel; GetLoadedModelsCollection; GetModelIndex; GetDictionaryModel

Remarks: see DgnFile::AddRootModel; see DgnFile::LoadRootModelById

DgnModelP LoadRootModelById	(	StatusInt *	errorDetails,
		ModelId	modelID,
		bool	fillCache = `false`,
		bool	andRefs = `false`,
		bool	processAffected = `false`
	)

Find a model in this file by its ModelId.

Optionally fill the model and load its DgnAttachments. Calls LoadModelById and AddRootModel if successful.

Parameters

[out]	errorDetails	Set to non-zero if the model could not be found DGNMODEL_STATUS_NotFound DGNMODEL_STATUS_BadFileRefCount
	modelID	Identifies the model to load
	fillCache	If true, calls FillSectionsInModel with DgnModelSections::Model
	andRefs	If true, calls ReadAndLoadDgnAttachments on the model
	processAffected	If true, calls DependencyManager::ProcessAffected after the model and refs are filled

Returns: a pointer to the model loaded or NULL if no model by the specified ID was found in the file

Remarks: This file retains a reference to the returned model by calling AddRootModel.; LoadRootModelById returns NULL and sets errorDetails to DGNMODEL_STATUS_BadFileRefCount if the DgnFile's reference count is 0. This can happen if all the file's open models are DgnAttachments. To avoid this error, a program can save the DgnFile pointer in a DgnFilePtr to increment the reference count.

StatusInt ProcessChanges	(	DgnSaveReason	reason,
		double	timestamp = `0`
	)

Process the changes in all of the DgnModels of this file, saving them to disk if appropriate.

If the "abandon changes" flag is on for this file, then all of the DgnModels are emptied. After this call, HasPendingChanges will return false.

Parameters

[in]	reason	The reason the changes are being processed. This reason will be passed to listeners so they can take appropriate action.
[in]	timestamp	The time (in milliseconds since 1/1/1970 - see BeTimeUtilities::GetCurrentTimeAsUnixMillisDouble) to be saved in the header and returned by GetLastFileTime. This is supplied by the caller, rather than using the current time, so that it can be saved and compared. If timestamp is 0, the current time is used.

See also: SetAbandonChangesFlag, HasPendingChanges, GetLastSaveTime

int Release ( )

Decrement the reference count of this file.

If this is the last reference to the file and if there are no outstanding references to models loaded from this file, then the associated disk file is close and this object is deleted.

Returns: the new reference count

StatusInt SaveDocumentProperty	(	int *	propIDP,
		WCharCP	nameP,
		int	propType,
		int	streamToUse,
		const void *	value
	)

Set a document property.

Parameters

[in]	propIDP	The id of the property to get. Must be specified if streamToUse is SUMMARY_STREAM, DOCSUMMARY_STREAM, or MEDIASUMMARY_STREAM. Must be one of the Windows PIDSI_, PIDDSI_, or PIDMSI_ identifiers, as appropriate for streamToUse.
[in]	nameP	If not NULL, the name of the property to get. Must be specified if streamToUse is USERDEFINED_PROPERTIES.
[in]	propType	The format of the property value. Must be one of the Windows VARENUM values.
[in]	streamToUse	The stream in which the property is stored. Must be one of: SUMMARY_STREAM DOCSUMMARY_STREAM USERDEFINED_STREAM MEDIASUMMARY_STREAM
[in]	value	A pointer to a buffer that holds the property value.

See also: GetDocumentProperty

Remarks: This function is not for updating the thumbnail property. See #SaveThumbnail

Returns: SUCCESS if the property was set or non-zero if the property could not be set.

void SetAbandonChangesFlag ( )

Set the "abandon changes" flag.

When the "abandon" flag is on, none of the changes are written to the disk, even if ProcessChanges is called.

See also: ClearAbandonChangesFlag

void SetFullSaveFlag ( )

Set the "full save" flag.

This forces the entire file to be rewritten on the next call to ProcessChanges, even if there have been no changes to it in this session.

See also: ProcessChanges

BentleyStatus SetModelBackgroundColor	(	RgbColorDef const &	color,
		DgnModelType	type
	)

Set the background color for all models of a given type.

Returns: ERROR if type is not found.

Remarks: If the model type is DgnModelType::Normal, the DgnColorMap's background color entry will be updated.

void SetTransactable ( bool yesNo )

Allow ITxnManager to log changes to this file.

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

DgnFile.h

Classes

Public Member Functions

Static Public Member Functions

File properties

Models

Detailed Description

Accessing an existing file

Accessing an existing file

Creating a new file

Making changes

Closing a file

Styles, Colors, Levels

Collections and Iterators

Document Properties

Member Enumeration Documentation

Member Function Documentation