Class: TForeignDataTranslator

Declaration: ForeignData.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

This is the abstract base class from which all foreign data translators must inherit. It provides the protocol for performing export and import translations to and from TForeignData objects. Deriving classes are responsible for implementing the protocol.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

To write a new foreign data translator you create a new derived class of TForeignDataTranslator and override the ExportData and CreateScrapItem member functions.

Concurrency:

Multithread safe, with the exception of the constructors, assignment, and stream-in operators. Once a translator has been fully constructed and streamed in, it can be used by multiple threads.

Resource Use:

No special requirements.

Member Function: TForeignDataTranslator::~TForeignDataTranslator

virtual ~ TForeignDataTranslator ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignDataTranslator::CreateScrapItem

virtual TScrapItem * CreateScrapItem (const TForeignData & inputData, const TTypeDescription & desiredType, TMemoryHeap * heap =0) const

Interface Category:

API.

Purpose:

This pure virtual member function provides the interface for translating data from a foreign format into a Taligent scrap item. Derived classes must override this member function.

Calling Context:

Called automatically by TImportForeignDataQuery::CreateScrapItem. This function can also be called directly.

Parameters:

const TForeignData & inputData -The foreign data to be imported
const TTypeDescription & desiredType -The type of scrap item desired by the caller.
TMemoryHeap * heap =0 -The memory heap in which the scrap item and all of its owned objects should be created. The default parameter value of 0 will cause the objects to be created in the default heap.

Return Value:

A newly-created TScrapItem of the requested type that contains the imported data. The caller is responsible for deleting the scrap item.

Exceptions:

Passes all exceptions through. Throws TForeignDataException(kInvalidTranslator) if this translator cannot perform the requested translation. This is usually a programming error.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TForeignDataTranslator::ExportData

virtual void ExportData (const TTypeDescription & inputType, const TScrapItem & input, const TForeignDataType & desiredType, TForeignData & destination) const

Interface Category:

API.

Purpose:

This pure virtual member function provides the interface for translating data from a Taligent scrap item into a foreign format. Derived classes must override this member function.

Calling Context:

Called automatically by TExportDocumentQuery::DoTranslation and TExportScrapItemsQuery::DoTranslation. This function can also be called directly.

Parameters:

const TTypeDescription & inputType -The type of the scrap item which is to be exported. If the scrap item is a TModelScrapItem, inputType will be the type description of the model contained in the scrap item and not the scrap item itself.
const TScrapItem & input -The scrap item to be exported.
const TForeignDataType & desiredType -The type of foreign data desired by the caller.
TForeignData & destination -The foreign data sink to which the data should be written.

Return Value:

None.

Exceptions:

Passes all exceptions through. Throws TForeignDataException(kInvalidTranslator) if this translator cannot perform the requested translation. This is usually a programming error.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TForeignDataTranslator::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream to which this object's data is written.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TForeignDataTranslator::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -Stream from which the object's data is read.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Passes all exceptions through. Throws TInvalidVersionError if the data on the stream is an unrecognized version.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignDataTranslator::CreateModelScrapItem

static TScrapItem * CreateModelScrapItem (TModel * adoptModel, TMemoryHeap * heap =0)

Interface Category:

API.

Purpose:

This is a utility function for use by derived classes that need to return a TScrapItem containing a TModel for use in a compound document. It simply packages the model inside a TModelScrapItem and returns it. A derived class could do this itself almost as easily; this function just enables a bit of code sharing.

Calling Context:

This function can be called directly. It is mainly intended to be called by derived class implementations of the CreateScrapItem member function.

Parameters:

TModel * adoptModel -The model which will be adopted into the TModelScrapItem created by this function.
TMemoryHeap * heap =0 -The memory heap in which the returned scrap item will be created. The default parameter value of 0 will cause the objects to be created in the default heap.

Return Value:

Returns newly-created TModelScrapItem which contains the specified model. The caller is responsible for deleting the scrap item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TForeignDataTranslator::CreateEmbedderScrapItem

static TScrapItem * CreateEmbedderScrapItem (TModel * adoptModel, TModelPresenterState * adoptState, TMemoryHeap * heap =0)

Interface Category:

API.

Purpose:

This is a utility function which derived classes can use when they need need to return an entire embeddable document component. CreateEmbedderScrapItem packages up a model and a presenter state inside a document component, puts that inside a TEmbedderModel, and then puts that inside a TModelScrapItem. A derived class could do this itself almost as easily; this function just allows a bit of code sharing.

Calling Context:

This function can be called directly. It is mainly intended to be called by derived class implementations of the CreateScrapItem member function.

Parameters:

TModel * adoptModel -The model which will be adopted into the document component returned by this function.
TModelPresenterState * adoptState -The presenter state which will be adopted into the document component returned by this function.
TMemoryHeap * heap =0 -The memory heap in which the returned scrap item and its model and document component will be created. The default parameter value of 0 will cause the objects to be created in the default heap.

Return Value:

Returns newly-created TModelScrapItem which contains a TEmbedderModel which in turn contains a TDocumentComponent constructed from the specified model and presenter state. The caller is responsible for deleting the scrap item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignDataTranslator::TForeignDataTranslator

TForeignDataTranslator ()
TForeignDataTranslator (const TForeignDataTranslator &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and by derived class constructors.
Called to copy an object.

Parameters:

Takes no parameters.
const TForeignDataTranslator & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignDataTranslator::operator=

TForeignDataTranslator & operator =(const TForeignDataTranslator &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TForeignDataTranslator & -The TForeignDataTranslator to be copied.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.