Class: TForeignData

Declaration: ForeignData.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TForeignFileData

Purpose:

TForeignData is an abstract class which provides an interface for accessing foreign data. Deriving classes implement this interface for particular kinds of foreign data. Conceptually, TForeignData objects are only references to the foreign data and do not contain the actual data. For example, TForeignFileData stores the location of a foreign file but does not store the file's data.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

TForeignData is an abstract class that provides only the protocol for accessing foreign data. Deriving classes must override the member functions GetDataType, CreateStreamForReading, CreateStreamForWriting, and CreateDefaultTranscoder. TForeignData uses the DynamicCast macros to so that clients with special needs can determine which derived class is being used and can call custom member functions. All classes derived from TForeignData must use the DynamicCast macros as well.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TForeignData::~TForeignData

virtual ~ TForeignData ()

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: TForeignData::GetDataType

virtual const TForeignDataType * GetDataType () const

Interface Category:

API.

Purpose:

This pure virtual member function provides a way for clients to retrieve the type of the data represented by this object.

Calling Context:

This function can be called directly.

Parameters:

Takes no parameters.

Return Value:

An alias to a TForeignDataType object representing the type of this data. Clients can use TForeignDataType::operator== or the DynamicCast macros to determine whether the foreign data type is appropriate for their needs. The pointer returned by this function is only valid as long as this TForeignData objects exists, and the caller must not delete the TForeignDataType object it points to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignData::CreateStreamForReading

virtual TRandomAccessStream * CreateStreamForReading (TMemoryHeap * =0) const

Interface Category:

API.

Purpose:

Create a random-access stream which can be used to read from the foreign data source represented by this object.

Calling Context:

This function can be called directly.

Parameters:

TMemoryHeap * =0 -The memory heap in which the stream should be created. The default parameter value of 0 will cause the stream to be created in the default heap.

Return Value:

A pointer to a newly-created TRandomAccessStream object which can be used to read from this foreign data source. The caller is responsible for deleting the stream.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignData::CreateStreamForWriting

virtual TRandomAccessStream * CreateStreamForWriting (unsigned long initialSize =0, TMemoryHeap * =0)

Interface Category:

API.

Purpose:

Create a random-access stream which can be used to write to the foreign data sink represented by this object.

Calling Context:

This function can be called directly.

Parameters:

unsigned long initialSize =0 -The initial size of the stream which is created. This is an optimization only; the returned stream must be growable, and an initial size of zero is the default.
TMemoryHeap * =0 -The memory heap in which the stream should be created. The default parameter value of 0 will cause the stream to be created in the default heap.

Return Value:

A pointer to a newly-created TRandomAccessStream object which can be used to write to this foreign data location. The stream must be growable. The caller is responsible for deleting the stream.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignData::CreateDefaultTranscoder

virtual TTranscoder * CreateDefaultTranscoder (TMemoryHeap * =0) const

Interface Category:

API.

Purpose:

Create a transcoder which can be used to export and import text to and from this foreign data location. Translators which have no special knowledge of text transcoding should use this member function rather than explicitly creating an ASCII or UTF-8 transcoder.

Calling Context:

This function can be called directly.

Parameters:

TMemoryHeap * =0 -The memory heap in which the transcoder should be created. The default parameter value of 0 will cause the transcoder to be created in the default heap.

Return Value:

A pointer to a newly-created TTranscoder which can be used for importing and exporting text. The caller is responsible for deleting the transcoder.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignData::operator>>=

TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator. This operator streams out a reference to the foreign data's location. It does not stream out the actual foreign data contents.

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:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignData::operator<<=

TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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

Return Value:

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

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignData::TForeignData

TForeignData ()
TForeignData (const TForeignData &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

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

Parameters:

Takes no parameters.
const TForeignData & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignData::operator=

TForeignData & operator =(const TForeignData & other)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TForeignData & other -The object 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.