The interface to write changes in the context of a transaction to elements, XAttributes, and models. More...

#include <ITxnManager.h>

Inheritance diagram for ITxn:

Classes
struct	ICustomEntry
	Interface for a custom entry to be stored in the undo buffer. More...

Public Types
typedef RefCountedPtr < ICustomEntry >(*	DeserializeCustomItemFunc )(byte const *data, size_t numBytes)

Public Member Functions
XAttributes
StatusInt	AddXAttribute (ElementRefP elRef, XAttributeHandlerId handlerId, UInt32 xAttrId, void const xAttrData, UInt32 length, UInt32 outXAttrId=0, TxnXAttributeAddOptions const &opts=TxnXAttributeAddOptions())
	Add a new XAttribute to an existing element. More...

StatusInt	DeleteXAttribute (XAttributeHandleR xAttr, TxnXAttributeWriteOptions const &opts=TxnXAttributeWriteOptions())
	Delete an existing XAttribute from an element. More...

StatusInt	ModifyXAttributeData (XAttributeHandleCR xAttr, void const *data, UInt32 start, UInt32 length, TxnXAttributeWriteOptions const &opts=TxnXAttributeWriteOptions())
	Modify all or part of an existing XAttribute. More...

StatusInt	ReplaceXAttributeData (XAttributeHandleCR xAttr, void const *data, UInt32 newSize=0, TxnXAttributeWriteOptions const &opts=TxnXAttributeWriteOptions())
	Replace an existing XAttribute with a new value. More...

Element I/O
StatusInt	DeleteElement (ElementRefP elem, TxnElementWriteOptions const &opts=TxnElementWriteOptions())
	Delete an element from a model. More...

StatusInt	AddElement (EditElementHandleR newEl, TxnElementAddOptions const &opts=TxnElementAddOptions())
	Add a new element to a model. More...

StatusInt	ReplaceElement (EditElementHandleR el, ElementRefP in, TxnElementWriteOptions const &opts=TxnElementWriteOptions())
	Replace an existing element in a model with a different one. More...

Model I/O
DgnModelP	CreateNewModel (DgnModelStatus *error, DgnFileR file, WCharCP name, DgnModelType type, bool is3D, DgnModelCP seedModel=0, ModelId modelId=(-2))
	Create a new model in the specified file and make it a root. More...

DgnModelP	CreateNewModel (DgnModelStatus *error, DgnFileR file, ModelInfoCR modelInfo, ModelId modelId=(-2))
	Create a new model in the specified file and make it a root. More...

StatusInt	DeleteModel (DgnModelR dgnModel)
	Delete a model. More...

StatusInt	SaveModelProperties (DgnModelR model, bool bSaveSettings=false, bool forceSave=false)
	Update the model's properties. More...

Custom Data
void	SaveCustomEntryInUndo (byte const *data, size_t numBytes, DeserializeCustomItemFunc func)
	Append a custom entry to the undo buffer. More...

Additional Inherited Members
Protected Member Functions inherited from NonCopyableClass
	NonCopyableClass ()

	~NonCopyableClass ()

Detailed Description

The interface to write changes in the context of a transaction to elements, XAttributes, and models.

Calls TxnMonitors and may support undo/redo.

Member Typedef Documentation

typedef RefCountedPtr<ICustomEntry>(* DeserializeCustomItemFunc)(byte const *data, size_t numBytes)

Member Function Documentation

StatusInt AddElement	(	EditElementHandleR	newEl,
		TxnElementAddOptions const &	opts = `TxnElementAddOptions()`
	)

Add a new element to a model.

Remarks: newEl must already be associated with a model.

Parameters

[in,out]	newEl	The element to be added. Must hold an MSElementDescr.
[in]	opts	options

Returns: SUCCESS if the element was added or non-zero indicating failure. Possible reasons for failure include: – newEl is not associated with a model, – the model is not writable, – the element handler blocked the add, – the element could not be assigned an ElementId, – any scheduled XAttribute change failed.

StatusInt AddXAttribute	(	ElementRefP	elRef,
		XAttributeHandlerId	handlerId,
		UInt32	xAttrId,
		void const *	xAttrData,
		UInt32	length,
		UInt32 *	outXAttrId = `0`,
		TxnXAttributeAddOptions const &	opts = `TxnXAttributeAddOptions()`
	)

Add a new XAttribute to an existing element.

Parameters

[in]	elRef	The ElementRefP of the element.
[in]	handlerId	The XAttributeHandlerId of the new XAttribute.
[in]	xAttrId	The XAttributeId of the new XAttribute. If INVALID_XATTR_ID, then a new, unique, id will be assigned. The value of the new id will be returned in outXAttrId.
[in]	xAttrData	A buffer of at least length bytes long that holds the value to be saved in the new XAttribute.
[in]	length	The number of bytes in xAttrData.
[out]	outXAttrId	Optional, the id of the new XAttribute. This is necessary only if xAttrId is INVALID_XATTR_ID, in which case the new XAttribute is assigned a new unique id.
[in]	opts	options Remarks Implementation must use DependencyMgrXAttributeChangeTracker

Returns: SUCCESS if the XAttribute was added to the ElementRefP.

DgnModelP CreateNewModel	(	DgnModelStatus *	error,
		DgnFileR	file,
		WCharCP	name,
		DgnModelType	type,
		bool	is3D,
		DgnModelCP	seedModel = `0`,
		ModelId	modelId = `(-2)`
	)

Create a new model in the specified file and make it a root.

The model is assigned the next available ModelId.

Parameters

[out]	error	if not NULL, error is set to a non-zero error status if the return value is NULL. Possible values include: DGNMODEL_STATUS_InvalidModelName if name is NULL or cannot be used as a model name DGNMODEL_STATUS_DuplicateModelName if an existing model in this file already uses the specified name DGNMODEL_STATUS_NotFound if seedModel is NULL and if no default seed model can be found
[in]	file	The file where the new model will be created.
[in]	name	The name of the model to be created. Must be unique.
[in]	type	Model type to create.
[in]	is3D	True to create 3D model else a 2D model is created.
[in]	seedModel	Seed model used to set default model settings. If NULL then the Default model will be used as seed.
[in]	modelId	id for new model. Leave as INVALID_MODELID and it will be assigned a new valid id.

Returns: A pointer to a new DgnModel for the new model, or NULL if the model could not be created. See error for error details.

Remarks: This function calls DgnFile::AddRootModel.

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

Create a new model in the specified file and make it a root.

The model is assigned the next available ModelId.

Parameters

[out]	error	if not NULL, error is set to a non-zero error status if the return value is NULL. Possible values include: DGNMODEL_STATUS_InvalidModelName if name is NULL or cannot be used as a model name DGNMODEL_STATUS_DuplicateModelName if an existing model in this file already uses the specified name DGNMODEL_STATUS_NotFound if seedModel is NULL and if no default seed model can be found
[in]	file	The file where the new model will be created.
[in]	modelInfo	The specifications for the new model. All fields must be valid and the Model Name must be unique.
[in]	modelId	id for new model. Leave as INVALID_MODELID and it will be assigned a new valid id.

Returns: A pointer to a new DgnModel for the new model, or NULL if the model could not be created. See error for error details.

Remarks: This function calls DgnFile::AddRootModel.

StatusInt DeleteElement	(	ElementRefP	elem,
		TxnElementWriteOptions const &	opts = `TxnElementWriteOptions()`
	)

Delete an element from a model.

Parameters

[in]	elem	The ElementRefP of the element to be deleted. Must be a valid existing element.
[in]	opts	options

Returns: SUCCESS if the element was deleted.

StatusInt DeleteModel ( DgnModelR dgnModel )

Delete a model.

Functions that look up models such as DgnFile::FindModelIdByName and model collections such as ModelIndex will not return a deleted model.

Parameters

[in] dgnModel The DgnModel holding the model to be deleted.

Remarks: This function does not actually remove the model from the physical file. Call DgnFile::ProcessChanges to remove deleted models from a file.; Deleting a model causes all DgnAttachments that currently point to the model to drop their pointers to it. This does not, however, cause the attachments themselves to be deleted.; Invokes TxnMonitor::_OnModelChange

StatusInt DeleteXAttribute	(	XAttributeHandleR	xAttr,
		TxnXAttributeWriteOptions const &	opts = `TxnXAttributeWriteOptions()`
	)

Delete an existing XAttribute from an element.

Parameters

[in]	xAttr	An XAttributeHandle that refernces the XAttribute to delete.
[in]	opts	options

Returns: SUCCESS if xAttr is valid and the XAttribute was deleted from the element. DGNMODEL_STATUS_InvalidXattribute if xAttr was not valid. Remarks Implementation must use DependencyMgrXAttributeChangeTracker

StatusInt ModifyXAttributeData	(	XAttributeHandleCR	xAttr,
		void const *	data,
		UInt32	start,
		UInt32	length,
		TxnXAttributeWriteOptions const &	opts = `TxnXAttributeWriteOptions()`
	)

Modify all or part of an existing XAttribute.

The size of the XAttribute cannot be changed.

Parameters

[in]	xAttr	An XAttributeHandle that refernces the XAttribute to modify.
[in]	data	The new data to save in the XAttribute.
[in]	start	The starting byte number to replace with data.
[in]	length	The number of bytes to replace with data.
[in]	opts	options

Returns: SUCCESS if the data in xAttr was modified. DGNMODEL_STATUS_InvalidXattribute if xAttr was not valid. ERROR if attempting to write more data than exists in xAttr. Remarks Implementation must use DependencyMgrXAttributeChangeTracker

StatusInt ReplaceElement	(	EditElementHandleR	el,
		ElementRefP	in,
		TxnElementWriteOptions const &	opts = `TxnElementWriteOptions()`
	)

Replace an existing element in a model with a different one.

Parameters

[in,out]	el	The element to be replaced.
[in]	in	The ElementRefP of the element to be replaced. Must be a valid existing element.
[in]	opts	options

Returns: SUCCESS if the element was replaced and out is non-NULL.

StatusInt ReplaceXAttributeData	(	XAttributeHandleCR	xAttr,
		void const *	data,
		UInt32	newSize = `0`,
		TxnXAttributeWriteOptions const &	opts = `TxnXAttributeWriteOptions()`
	)

Replace an existing XAttribute with a new value.

The size of the XAttribute can change with this method.

Parameters

[in]	xAttr	An XAttributeHandle that refernces the XAttribute to replace.
[in]	data	The new data to save in the XAttribute.
[in]	newSize	The number of bytes in data.
[in]	opts	options

Returns: SUCCESS if the data in xAttr was replaced. DGNMODEL_STATUS_InvalidXattribute if xAttr was not valid. Remarks Implementation must use DependencyMgrXAttributeChangeTracker

void SaveCustomEntryInUndo	(	byte const *	data,
		size_t	numBytes,
		DeserializeCustomItemFunc	func
	)

Append a custom entry to the undo buffer.

Parameters

[in]	data	The data at this address will be stored in the undo buffer.
[in]	numBytes	The number of bytes to be stored.
[in]	func	When the custom entry is affected by an undo or redo event, this function will be called. The function's job is to create an object that will then be notified about the event.

StatusInt SaveModelProperties	(	DgnModelR	model,
		bool	bSaveSettings = `false`,
		bool	forceSave = `false`
	)

Update the model's properties.

Parameters

[in]	model	The model whose properties are to be saved.
[in]	bSaveSettings	If true, the non-undoable attributes of the model are also saved and journaled in undo. This is rarely needed. Normally, non-undoable attributes are not saved until the user does save settings and are not saved in the undo buffer.
[in]	forceSave	If true, the equality comparison is skipped and model properties are saved even if no changes are found. This is needed when model is recreated and OnModelChange event have to be triggered.

Remarks: To change a model's properties you must make a copy of the model's ModelInfo. Modify the copy then apply the changes back to the model by calling DgnFile::ProcessChanges in order to make persistable changes actually persistent.; Invokes DgnModel::SaveModelInfo, TxnMonitor::_OnModelChange

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

ITxnManager.h

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Member Function Documentation