Class: TArchive

Declaration: Archive.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TArchive provides persistent storage of localized objects. Any streamable object can be stored in an archive and an archive can store objects of multiple types. Each object in an archive is given a name and is associated with a specific locale. An archive will generally contain multiple localized versions of an object, each associated with a different locale. A TArchive object represents an access path to the physical archive on disk. Creating a TArchive object does not necessarily create a physical archive nor does destroying a TArchive object necessarily destroy the physical archive. Depending on the chosen access mode, more than one TArchive object may refer to the same physical archive. A TArchive object is constructed by passing in the name and directory of the physical archive on disk.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is designed to be used directly. Do not derive.

Concurrency:

Not Multithread safe.

Resource Use:

No special requirements.

Member Function: TArchive::~TArchive

virtual ~ TArchive ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::GetObjectCount

virtual unsigned long GetObjectCount () const
virtual unsigned long GetObjectCount (const TLocale & locale) const

Interface Category:

API.

Purpose:

Returns the number of objects contained by all locales in this archive.
Returns the number of objects contained by the given locale in this archive.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
const TLocale & locale -The locale in which to count the objects.

Return Value:

The number of objects contained by this archive.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::CreateArchiveIterator

virtual TArchiveIterator * CreateArchiveIterator () const
virtual TArchiveIterator * CreateArchiveIterator (const TLocale & locale, bool includeInheritedItems =false) const

Interface Category:

API.

Purpose:

Returns an iterator that iterates over all objects in this archive.
Returns an iterator that iterates over all objects in the given locale in this archive.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
const TLocale & locale -The locale to iterate over.
bool includeInheritedItems =false -Should the iterator include objects inherited from parent locales.

Return Value:

Returns a pointer to a heap allocated TArchiveIterator object for this archive. The caller owns the returned iterator object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::GetLocalesContainingObject

virtual void GetLocalesContainingObject (TCollectionOf < TLocale > &, const TText & objectName) const

Interface Category:

API.

Purpose:

Fills in the given collection with the locales that contain the specified object. The caller is responsible for the locale objects contained in the collection.

Calling Context:

Call this function directly.

Parameters:

TCollectionOf < TLocale > & -Receives the locales that contain the specified object.
const TText & objectName -The name of the object to look for.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::GetLocaleCount

virtual unsigned long GetLocaleCount () const

Interface Category:

API.

Purpose:

Returns the number of locales that contain objects in this archive.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The number of locales that contain objects in this archive.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::CreateLocaleIterator

virtual TArchiveLocaleIterator * CreateLocaleIterator () const

Interface Category:

API.

Purpose:

Returns an iterator that iterates through all the locales that contain objects in this archive.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to a heap allocated TArchiveLocaleIterator object for this archive. The caller owns the returned iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::GetFileSystemEntity

TFileSystemEntity GetFileSystemEntity ()

Interface Category:

API.

Purpose:

Return the file system entity for this TArchive's physical archive.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The file system entity that stores this archive.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::SetDestroyFileOnDelete

void SetDestroyFileOnDelete (bool doIt =false)

Interface Category:

API.

Purpose:

Set flag indicating if the physical archive should be deleted when this TArchive object is destroyed.

Calling Context:

Call this function directly.

Parameters:

bool doIt =false -Indicates if archive should be destroyed when this object is destroyed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::RemoveAllObjects

virtual void RemoveAllObjects ()
virtual void RemoveAllObjects (const TLocale & locale)

Interface Category:

API.

Purpose:

Remove all objects from the archive.
Remove all objects contained in the given locale from the archive.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
const TLocale & locale -The locale from which objects are to be removed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::RemoveObject

virtual bool RemoveObject (const TText & objectName)
virtual bool RemoveObject (const TText & objectName, const TLocale & locale)

Interface Category:

API.

Purpose:

Remove the object with the given name from all locales in this archive.
Remove the object with the given name from the given locale in this archive.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TText & objectName -Name of the object to be removed.
const TText & objectName -Name of the object to be removed.
const TLocale & locale -Locale from which object is to be removed.

Return Value:

Returns true if specified object was actually in the archive before removal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::Member

virtual bool Member (const TText & objectName, const TLocale & locale) const

Interface Category:

API.

Purpose:

Returns true if there is an object of a given name associated with the given locale in this archive.

Calling Context:

Call this function directly.

Parameters:

const TText & objectName -The name of the object in question.
const TLocale & locale -The locale where the object in question is to be found.

Return Value:

Returns true if an object of the given name is associated with the given locale in this archive. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::CopyArchiveForSharedLibrary

static TArchive * CopyArchiveForSharedLibrary ()
static TArchive * CopyArchiveForSharedLibrary (const TFile & whichLibrary)

Interface Category:

API.

Purpose:

Returns a TArchive for the archive associated with the shared library in which the calling function is defined.
Returns a TArchive for the archive associated with the given shared library.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
const TFile & whichLibrary -A TFile representing a shared library.

Return Value:

Returns a pointer to a heap allocated TArchive for the desired archive. The caller is responsible for the storage of the returned TArchive object. The returned TArchive object is opened for read only.

Exceptions:

Throws TArchiveNotFound if no archive can be found for the specified shared library. Passes other exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

Member Function: TArchive::TArchive

TArchive (const TDirectory & parentDirectory, const TFileSystemEntityName & archiveName, ECreationMode createMode =kCreateOrOpen, EAccessMode accessMode =kReadWrite)
TArchive ()

Interface Category:

API.

Purpose:

Create a TArchive object for the physical archive specified by parentDirectory and archiveName.
Default constructor.

Calling Context:

Call this function directly.
Unimplemented -do not use.

Parameters:

const TDirectory & parentDirectory -The directory in which the physical archive is located.
const TFileSystemEntityName & archiveName -The file system name for the physical archive.
ECreationMode createMode =kCreateOrOpen -If createMode is kCreate, create a new physical archive and throw an exception if it already exists. If createMode is kOpen, open an existing physical archive and throw an exception if it doesn't already exist. If createMode is kCreateOrOpen, create a new archive if it does not already exist or open the existing one if it does.
EAccessMode accessMode =kReadWrite -Open the physical archive for reading and writing or read only operations.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws TArchiveNotFound if createMode is kOpen and the specified archive is not found on disk. Throws TArchiveAlreadyExists if createMode is kCreate and the specified archive is found on disk. Passes all other exceptions through.

Concurrency:

Not Multithread safe.

Other Considerations:

None.

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