WorkFiles

Typedefs
typedef int(*	ModelIndexTraverseFunctionP )(bool *pMayContinue, WCharP modelName, WCharP modelDesciption, DgnPlatform::DgnModelType modelType, bool is3D, bool isLocked, DgnPlatform::ModelId modelID, bool isDefault, bool isHidden, DgnFileP dgnFileObj, CallbackArgP pUserData)
	UserFunction called from mdlDgnFileObj_traverseModelIndex and mdlWorkDgn_traverseModels. More...

Functions
StatusInt	mdlWorkDgn_openFileWithRights (DgnModelRefP *pModelRef, DgnPlatform::DgnFileFormatType *pFormat, bool *pThreeD, WCharCP pName, WCharCP pModelName, bool readOnly, UInt32 rights, MessageDestination displayError, DgnFileSupplyRightsP loadContext)
	Opens the specified design file as a working file. More...
StatusInt	mdlWorkDgn_openFile (DgnModelRefP *pModelRef, DgnPlatform::DgnFileFormatType *pFormat, bool *pThreeD, WCharCP pName, WCharCP pModelName, bool readOnly)
	Opens the specified design file as a working file. More...
StatusInt	mdlWorkDgn_createFile (DgnModelRefP *pModelRef, WCharCP pName, DgnPlatform::DgnFileFormatType format, DgnModelRefP seedModelRef, DgnPlatform::SeedCopyFlags seedFlags, PFSeedFunc seedFunc, CallbackArgP pUserData, bool threeD)
	Creates a design file object in memory, reserving the required space for it. More...
StatusInt	mdlWorkDgn_saveChanges (DgnModelRefP modelRef)
	Write all pending changes to the specified file to the disk. More...
StatusInt	mdlWorkDgn_closeFile (DgnModelRefP modelRef)
	Close the design file identified by the given model reference, saving all changes. More...
StatusInt	mdlWorkDgn_discardFile (DgnModelRefP modelRef)
	Close the design file identified by the given model reference, discarding any changes since the last save. More...
int	mdlWorkDgn_delete (MSElementDescrP elemDescrP, UInt32 filePos, DgnModelRefP modelRef)
	Deletes elements from a work file. More...
UInt32	mdlWorkDgn_read (MSElementDescrH elemDescrPP, UInt32 filePos, DgnModelRefP modelRef, UInt32 *startFilePos)
	Reads an element and creates a new element descriptor. More...
UInt32	mdlWorkDgn_write (MSElementDescrP newElemDscrP, UInt32 filePos, DgnModelRefP modelRef)
	Writes element(s) to a work file. More...
StatusInt	mdlWorkDgn_traverseModels (WCharCP pName, ModelIndexTraverseFunctionP pCallbackFunc, CallbackArgP pCallbackArg)
	Traverses the models of a dgn file. More...
StatusInt	mdlWorkDgn_undeleteModel (DgnFileP dgnFileObj, DgnPlatform::ModelId modelID)
	Undelete a model that has been previously deleted with mdlModelRef_deleteModel. More...

Detailed Description

Typedef Documentation

typedef int(* ModelIndexTraverseFunctionP)(bool *pMayContinue, WCharP modelName, WCharP modelDesciption, DgnPlatform::DgnModelType modelType, bool is3D, bool isLocked, DgnPlatform::ModelId modelID, bool isDefault, bool isHidden, DgnFileP dgnFileObj, CallbackArgP pUserData)

UserFunction called from mdlDgnFileObj_traverseModelIndex and mdlWorkDgn_traverseModels.

Parameters

[out]	pMayContinue	true means keep going, false means stop now
[in]	modelName	Name of model
[in]	modelDesciption	Description of model (NULL if none)
[in]	modelType	type of model
[in]	is3D	true if model is 3D
[in]	isLocked	true if model is locked (read-only)
[in]	modelID	ID of model
[in]	isDefault	true if this is the default model
[in]	isHidden	true if model is designated as hidden
[in]	dgnFileObj	file which contains model
[in]	pUserData	userdata or NULL

Returns

non-zero return will stop traversal

Function Documentation

StatusInt mdlWorkDgn_closeFile

(

DgnModelRefP

modelRef

)

Close the design file identified by the given model reference, saving all changes.

The memory that was associated with the passed-in model reference will be freed. However, if there are any remaining open modelRefs from the work DGN file then the file will not be closed.

Parameters

[in]

modelRef

Reference to any model in the file to be closed. Usually this is the model ref from mdlWorkDgn_openFile.

Returns

SUCCESS if the given model reference is valid. MDLERR_BADMODELREF is returned if the given model reference is not to a valid open design file.

Remarks

All but the last model reference from this file (which is used as an argument to this function) must be freed with mdlModelRef_freeWorking.

See also

mdlWorkDgn_openFile mdlWorkDgn_createFile mdlWorkDgn_discardFile

StatusInt mdlWorkDgn_createFile	(	DgnModelRefP *	pModelRef,
		WCharCP	pName,
		DgnPlatform::DgnFileFormatType	format,
		DgnModelRefP	seedModelRef,
		DgnPlatform::SeedCopyFlags	seedFlags,
		PFSeedFunc	seedFunc,
		CallbackArgP	pUserData,
		bool	threeD
	)

Creates a design file object in memory, reserving the required space for it.

The file created can be modified using mdlWorkDgn_saveChanges . However, if a file with the same name already exists, it will be deleted from disk.

The model ref returned in the first parameter will be a working model ref. It must be freed by a matching call to mdlWorkDgn_closeFile.

Parameters

[out]	pModelRef	A modelRef referring to the default model of the newly created file.
[in]	pName	The name to be given to the file when the disk file is created.
[in]	format	A constant identifying how the contents of the file are to be stored. Valid values for this argument are: DgnFileFormatType::V7 DgnFileFormatType::V8 DgnFileFormatType::DWG
[in]	seedModelRef	Seed model ref.
[in]	seedFlags	Components to copy from seed file. See the constants SeedCopyFlags::TCBData, SeedCopyFlags::DefaultViews, etc. defined in mswrkdgn.fdf.
[in]	seedFunc	Function to be called to possibly modify seed components. Can be NULL. See remarks.
[in]	pUserData	User data passed to seedFunc. Can be NULL.
[in]	threeD	If true, the default model of the new file will be three-dimensional

Returns

SUCCESS if the file is created successfully in memory.

Remarks

The model ref created will not have any references loaded; if these are desired, call mdlModelRef_loadReferenceModels.

The user function seedFunc will be called only for elements that are to be copied based on the specified seedFlags. The user function should only be used to either, a) modify an element before it is copied, or b) to skip copying an element by returning a non-zero value. The element passed to the user function should not be replaced with a different element, nor should the user function add any elements directly to the file.

See also

mdlWorkDgn_openFile mdlWorkDgn_closeFile

int mdlWorkDgn_delete	(	MSElementDescrP	elemDescrP,
		UInt32	filePos,
		DgnModelRefP	modelRef
	)

Deletes elements from a work file.

Parameters

[in]	elemDescrP	Elements to delete. If an element descriptor is not available when doing the delete, pass NULL for this argument to cause MicroStation to read the element(s) from the file before performing the delete. This adds some overhead, so always pass the element descriptor if it is available.
[in]	filePos	File position
[in]	modelRef	model reference

Returns

SUCCESS if the element is deleted.

See also

mdlWorkDgn_read mdlElmdscr_undoableDeleteC

StatusInt mdlWorkDgn_discardFile

(

DgnModelRefP

modelRef

)

Close the design file identified by the given model reference, discarding any changes since the last save.

The memory that was associated with the passed-in model reference will be freed. However, if there are any remaining open modelRefs from the work DGN file then the file will not be closed.

Parameters

[in]

modelRef

Reference to any model in the file to be closed. Usually this is the model ref from mdlWorkDgn_openFile.

Returns

SUCCESS if the given model reference is valid. MDLERR_BADMODELREF is returned if the given model reference is not to a valid open design file.

Remarks

All but the last model reference from this file (which is used as an argument to this function) must be freed with mdlModelRef_freeWorking.

See also

mdlWorkDgn_openFile mdlWorkDgn_createFile mdlWorkDgn_closeFile

StatusInt mdlWorkDgn_openFile	(	DgnModelRefP *	pModelRef,
		DgnPlatform::DgnFileFormatType *	pFormat,
		bool *	pThreeD,
		WCharCP	pName,
		WCharCP	pModelName,
		bool	readOnly
	)

Opens the specified design file as a working file.

The model ref returned is a working model ref, and must be freed with a matching call to mdlWorkDgn_closeFile.

Remarks

The model ref returned will not have any references loaded; if these are desired, then call mdlModelRef_loadReferenceModels.

This function works with V7 and V8 DGN files and DWG files. It does not work with V7 cell libraries.

Writable files are not shared. So if you request a writable file that is already open in MicroStation for write, this function will fail. Furthermore, if you request a read-only DgnFileObj for a DGN file opened for write, you will get a different DgnFileObj and all of the caches associated with it will be copies of the last saved version of the file. The new caches will not reflect any future changes to the file. The exception to this is the active file, where requesting a read-only version of the file will return the current active file and changes made by the user will be reflected in the cache.

If you need to check permissions when opening a file, you should use mdlWorkDgn_openFileWithRights.

Parameters

[out]	pModelRef	A reference to the specified model once it is opened.
[out]	pFormat	The format of the opened file. Valid values are: DgnFileFormatType::V7 DgnFileFormatType::V8 DgnFileFormatType::DWG
[out]	pThreeD	If true, the opened model is three dimensional.
[in]	pName	The name of the file to be opened.
[in]	pModelName	The name of the model to get from the file once it is opened. Pass NULL for the default model.
[in]	readOnly	If true, the file will be opened in read-only mode. If false, the file will be opened with write access. Note that if the requested file is the same as the active file, the model ref will always be writable because it shares the internal cache with the MicroStation core.

Returns

SUCCESS if the file is found and it contains design data.

See also

mdlWorkDgn_closeFile mdlWorkDgn_createFile mdlWorkDgn_openFileWithRights

StatusInt mdlWorkDgn_openFileWithRights	(	DgnModelRefP *	pModelRef,
		DgnPlatform::DgnFileFormatType *	pFormat,
		bool *	pThreeD,
		WCharCP	pName,
		WCharCP	pModelName,
		bool	readOnly,
		UInt32	rights,
		MessageDestination	displayError,
		DgnFileSupplyRightsP	loadContext
	)

Opens the specified design file as a working file.

The model ref returned is a working model ref, and must be freed with a matching call to mdlWorkDgn_closeFile.

Remarks

The model ref returned will not have any references loaded; if these are desired, then call mdlModelRef_loadReferenceModels.

This function works with V7 and V8 DGN files and DWG files. It does not work with V7 cell libraries.

Writable files are not shared. So if you request a writable file that is already open in MicroStation for write, this function will fail. Furthermore, if you request a read-only DgnFileObj for a DGN file opened for write, you will get a different DgnFileObj and all of the caches associated with it will be copies of the last saved version of the file. The new caches will not reflect any future changes to the file. The exception to this is the active file, where requesting a read-only version of the file will return the current active file and changes made by the user will be reflected in the cache.

Parameters

[out]	pModelRef	A reference to the specified model once it is opened.
[out]	pFormat	The format of the opened file. Valid values are: DgnFileFormatType::V7 DgnFileFormatType::V8 DgnFileFormatType::DWG
[out]	pThreeD	If true, the opened model is three dimensional.
[in]	pName	The name of the file to be opened.
[in]	pModelName	The name of the model to get from the file once it is opened. Pass NULL for the default model.
[in]	readOnly	If true, the file will be opened in read-only mode. If false, the file will be opened with write access. Note that if the requested file is the same as the active file, the model ref will always be writable because it shares the internal cache with the MicroStation core.
[in]	rights	The rights that you require DgnPlatform::DGNFILE_RIGHT_Any – No rights checking DgnPlatform::DGNFILE_RIGHT_Print – Print, print preview, e-plot, etc. DgnPlatform::DGNFILE_RIGHT_Export – SaveAs, Export, Copy to clipboard, File Fence, etc. DgnPlatform::DGNFILE_RIGHT_Edit – Modify file contents (implies not read-only) DgnPlatform::DGNFILE_RIGHT_Unlimited – All rights, present and future
[in]	displayError	How to handle a rights violation error.
[in]	loadContext	Used in combination with rights checking in mdlDialog_fileOpenExt to prevent repeated password prompting. The load context can be obtained by setting the reloadContextP member of the paramsP argument to that function.

Returns

SUCCESS if the file is found and it contains design data.

See also

mdlWorkDgn_closeFile mdlWorkDgn_createFile mdlWorkDgn_openFile

UInt32 mdlWorkDgn_read	(	MSElementDescrH	elemDescrPP,
		UInt32	filePos,
		DgnModelRefP	modelRef,
		UInt32 *	startFilePos
	)

Reads an element and creates a new element descriptor.

The caller is responsible for freeing the element descriptor using mdlElmdscr_freeAll.

Remarks

If the element at address filePos is a complex header, this function reads, and allocates memory for, the header and all of its components.

This function never returns deleted elements; they are skipped. Therefore, the file position for the element descriptor elemDescrPP can differ from the input filePos if the input filePos points to a deleted element. The actual file position from which elements were read is returned in startFilePos.

Parameters

[out]	elemDescrPP	Element descriptor return area
[in]	filePos	File read position
[in]	modelRef	model reference
[out]	startFilePos	actual file position, pass NULL if not requested.

Returns

the file position of the next element in the file. If the value returned is 0, an error occurred and the reason is returned in mdlErrno.

See also

mdlElmdscr_freeAll

StatusInt mdlWorkDgn_saveChanges

(

DgnModelRefP

modelRef

)

Write all pending changes to the specified file to the disk.

Parameters

[in]

modelRef

Reference to any model in the file to be saved.

Returns

SUCCESS if the changes are successfully saved.

StatusInt mdlWorkDgn_traverseModels	(	WCharCP	pName,
		ModelIndexTraverseFunctionP	pCallbackFunc,
		CallbackArgP	pCallbackArg
	)

Traverses the models of a dgn file.

The callback will be called once for each model in the dgn file. This function either returns an error, or it returns the last status returned by the callback.

Parameters

[in]	pName	name of the dgn file to traverse
[in]	pCallbackFunc	function to call for each model
[in]	pCallbackArg	argument to pass into callback

Returns

status

Remarks

Required Library: mdlbltin.lib

StatusInt mdlWorkDgn_undeleteModel	(	DgnFileP	dgnFileObj,
		DgnPlatform::ModelId	modelID
	)

Undelete a model that has been previously deleted with mdlModelRef_deleteModel.

This function can be used until a file is compressed or closed, at which point the model is lost.

Parameters

[in]	dgnFileObj	Indicates the design file which contains the deleted model.
[in]	modelID	The ID of the model to undelete.

Returns

MDLERR_BADARG if the file reference is invalid; MDLERR_ALREADYEXISTS if the model exists in the file and is not deleted; MDLERR_CACHENOTFOUND if the model with the specified ID is not found in the file; otherwise, if the model is undeleted then SUCCESS is returned.

Remarks

View groups pointing to a model are deleted when the model is deleted and will not be restored by this function.

Required Library: mdlbltin.lib

See also

mdlModelRef_deleteModel

UInt32 mdlWorkDgn_write	(	MSElementDescrP	newElemDscrP,
		UInt32	filePos,
		DgnModelRefP	modelRef
	)

Writes element(s) to a work file.

Parameters

[in]	newElemDscrP	Element descriptor to write
[in]	filePos	If filePos has a value of -1, the element(s) are appended to the end of the file. If filePos does not specify the EOF position and the element(s) at filePos are the same size as those pointed to by newElemDscrP then the old one is overwritten, otherwise the old one is deleted and the new one is appended to the end of the file.
[in]	modelRef	model reference

Returns

the file position of the next element in the file. If the value returned is 0, an error occurred and the reason is returned in mdlErrno.

See also

mdlModelRef_getEof

Remarks

Required Library: mdlbltin.lib