Class: TForeignFileData

Declaration: ForeignData.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TForeignData

Inherited By:

None.

Purpose:

TForeignFileData represents a file containing foreign data. It provides member functions for creating streams which can be used to read or write the data.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

In some cases it will be desirable to derive additional classes from TForeignFileData in order to add additional protocols for data access. For example, when using Macintosh file data it might be useful to have a TMacintoshFileData class which provides member functions for accessing the file's resource fork. TForeignFileData 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 TForeignFileData must use the DynamicCast macros as well.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TForeignFileData::TForeignFileData

TForeignFileData (const TFile & existingFile)
TForeignFileData (TDirectory & parentDir, const TFileSystemEntityName & newFileName)
TForeignFileData (const TForeignFileData &)
TForeignFileData ()

Interface Category:

API.

Purpose:

Creates a TForeignFileData which refers to an existing file.
Creates a new foreign data file in the specified directory and then creates a TForeignFileData object which refers to it.
Copy constructor.
Default constructor.

Calling Context:

Called to create a TForeignFileData which refers to an existing file.
Called to create a TForeignFileData which refers to a new file.
Called to copy an object.
Called by the stream-in operators.

Parameters:

const TFile & existingFile -The existing foreign data file to which this TForeignFileData object should refer.
TDirectory & parentDir -The directory in which the new foreign data file will be created.
const TFileSystemEntityName & newFileName -The name of the new foreign data file which is created.
const TForeignFileData & -The object to be copied.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TForeignFileData::operator=

TForeignFileData & operator =(const TForeignFileData & other)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TForeignFileData & 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.

Member Function: TForeignFileData::~TForeignFileData

virtual ~ TForeignFileData ()

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

virtual const TForeignDataType * GetDataType () const

Interface Category:

API.

Purpose:

Returns a pointer to a TForeignDataType object corresponding to the type of this foreign file.

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 foreign file. Clients can use TForeignDataType::operator== or the DynamicCast macros to determine whether the foreign file is appropriate for their needs. The pointer returned by this function is only valid as long as this TForeignFileData 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: TForeignFileData::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 file represented by this object.

Calling Context:

This function can be called directly.

Parameters:

TMemoryHeap * =0 -The memory heap in which the stream object 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 file. 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: TForeignFileData::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 file represented by this object. If the file does not already exist, this member function will create it. If the file does already exist it will be overwritten.

Calling Context:

This function can be called directly.

Parameters:

unsigned long initialSize =0 -The initial size of the file. 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 object 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, growable TRandomAccessStream which can be used to write to this foreign data file. 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: TForeignFileData::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 file. 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: TForeignFileData::CreateDataObjectForFile

static TForeignFileData * CreateDataObjectForFile (const TFile & existingFile, TMemoryHeap * =0)

Interface Category:

API.

Purpose:

This static member function will create the right class of TForeignFileData object for a specified file. For example, if the file is a Macintosh file with a resource fork, a TMacintoshFileData object might be returned. This function uses platform-specific heuristics to determine which class of TForeignFileData to create. When importing files, clients should use this function instead of constructing a TForeignFileData directly.

Calling Context:

This function can be called directly.

Parameters:

const TFile & existingFile -The existing foreign file for which a TForeignFileData object should be created.
TMemoryHeap * =0 -The memory heap in which the TForeignFileData object should be created. The default parameter value of 0 will cause the object to be created in the default heap.

Return Value:

A pointer to a newly-created TForeignFileData (or derived class) object which represents the specified file. The caller is responsible for deleting the returned object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TForeignFileData::operator>>=

TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

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

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream to which the 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: TForeignFileData::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.

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