#include <IXReferenceUID.h>

Inheritance diagram for IXReferenceUID:

Public Types
enum	{ kDefaultIID = IID_IXREFERENCEUID }

Public Member Functions
virtual int32	BeginXRefSession (IDataBase pSrcDB, IDataBase pDestDB)=0

virtual int32	EndXRefSession ()=0

virtual IDataBase *	GetSrcDB ()=0

virtual IDataBase *	GetDestDB ()=0

virtual UID	GetDestUID (IDataBase pSrcDB, IDataBase pDestDB, UID srcID)=0

virtual void	BindSrcAndDestUID (IDataBase pSrcDB, IDataBase pDestDB, UID srcUID, UID destUID)=0

virtual void	UnbindSrcUID (IDataBase pSrcDB, IDataBase pDestDB, UID srcUID)=0

virtual ICommand *	GetDeferredCmd (IDataBase pSrcDB, IDataBase pDestDB, UID srcID) const =0

virtual void	BindDeferredCmd (IDataBase pSrcDB, IDataBase pDestDB, UID srcID, ICommand *pCmd)=0

Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0

virtual void	AddRef () const =0

virtual void	Release () const =0

Detailed Description

IXReferenceUID is used during copy operations to keep track of the copy context.

If you have an object A that contains a UID to B, then if you are doing a copy of 

both A and B you would like for the resulting A' to reference B'. IXReferenceUID

is the class that makes this happen for you.



Here's how it works. You group your copy operations together into a copy session.

You call BeginXRefSession to start a new session. The session keeps a mapping of

source UID to destination UID for every object that has been copied via IScrapUtils,

or one of the standard copy commands. If an object has already been copied, the

UID gets fetched back from IXReferenceUID instead of creating a whole other object.

If the object has not yet been copied, a copy is made and a mapping for it added

to IXReferenceUID.



<pre>

InterfacePtr<IXReferenceUID> xRef(GetExecutionContextSession(), UseDefaultIID());

xRef->BeginXRefSession(srcDB, destinationDB);

... Your copy operations go here...

xRef->EndXRefSession();

</pre>



Calls to BeginXRefSession/EndXRefSession may be nested. If the nested context has

the same source and destination databases as the enclosing context, then the UIDs

that are added in the nested context are still accessible to the enclosing context

after the nested context has been ended (EndXRefSession called). But if the databases

don't match, then the nested context supercedes the enclosing context until the

EndXRefSession is called, at which point the UIDs added in the nested context are

popped off and the enclosing context is restored.

See Also: IScrapUtils

Member Function Documentation

virtual int32 IXReferenceUID::BeginXRefSession	(	IDataBase *	pSrcDB,
		IDataBase *	pDestDB
	)

pure virtual

Start a new copy context.

Parameters

pSrcDB	source database
pDestDB	destination database

Returns: previous nesting level (first returns zero)

virtual void IXReferenceUID::BindDeferredCmd	(	IDataBase *	pSrcDB,
		IDataBase *	pDestDB,
		UID	srcID,
		ICommand *	pCmd
	)

pure virtual

Associate a command with the current context, to be processed when the context is ended. This is NOT a recommended way to solve problems, it is inherently fragile.

Parameters

pSrcDB	source database
pDestDB	destination database
srcID	source UID
pCmd	the command to defer

virtual void IXReferenceUID::BindSrcAndDestUID	(	IDataBase *	pSrcDB,
		IDataBase *	pDestDB,
		UID	srcUID,
		UID	destUID
	)

pure virtual

Add a new <sourceUID, destinationUID> mapping to the current context.

Parameters

pSrcDB	source database
pDestDB	destination database
srcID	source UID
destUID	destination UID

virtual int32 IXReferenceUID::EndXRefSession ( )

pure virtual

End a copy context.

Returns: returns current nesting level (last returns zero)

virtual ICommand* IXReferenceUID::GetDeferredCmd	(	IDataBase *	pSrcDB,
		IDataBase *	pDestDB,
		UID	srcID
	)		const

pure virtual

A copy sesion may have commands associated with it that are waiting for a safe time to be processed. If there are deferred commands associated with the current context they will be processed when EndXRefSession is called for the context.

Parameters

pSrcDB	source database
pDestDB	destination database
srcID	source UID

virtual IDataBase* IXReferenceUID::GetDestDB ( )

pure virtual

Return the destination database of the current context, or nil if there's no context.

virtual UID IXReferenceUID::GetDestUID	(	IDataBase *	pSrcDB,
		IDataBase *	pDestDB,
		UID	srcID
	)

pure virtual

Get the destination UID that matches the source UID, if there is one.

Parameters

pSrcDB	source database
pDestDB	destination database
srcID	source UID

Returns: destination UID the corresponds to the source, or kInvalidUID if there is none.

virtual IDataBase* IXReferenceUID::GetSrcDB ( )

pure virtual

Return the source database of the current context, or nil if there's no context.

Public Types

Public Member Functions

Detailed Description

Member Function Documentation