Class: TFileSystemEntity

Declaration: FileSystemInterface.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible, MPropertyStore

Inherited By:

TDirectory TFile

Purpose:

A base type for objects representing physical file system entities. Clients should not attempt to derive classes from this class.

Instantiation:

Allocate on the heap or the stack. Do not allocate in shared memory.

Deriving Classes:

All file system classes related to disk items (files, directories, volumes) descend from this class. Clients should not derive from TFileSystemEntity.

Concurrency:

Not multithread safe. This is a handle class.

Resource Use:

No special requirements.

Member Function: TFileSystemEntity::operator=

TFileSystemEntity & operator =(const TFileSystemEntity & right)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TFileSystemEntity & right -The object to assign from.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::~TFileSystemEntity

virtual ~ TFileSystemEntity ()

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. This is a handle class.

Other Considerations:

Decrements the reference count on a valid master.

Member Function: TFileSystemEntity::ReadAllPropertyIDs

virtual void ReadAllPropertyIDs (TPropertyIDSet & fillin) const

Interface Category:

API.

Purpose:

Fills in the set passed with all property IDs associated with this entity.

Calling Context:

Call this function directly.

Parameters:

TPropertyIDSet & fillin -The set to fill in with property IDs.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::ReadAllProperties

virtual void ReadAllProperties (TPropertySet & fillin) const

Interface Category:

API.

Purpose:

Fills in the set passed with all properties associated with this entity.

Calling Context:

Call this function directly.

Parameters:

TPropertySet & fillin -The set to fill in with props for this entity.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::ReadProperties

virtual bool ReadProperties (TPropertySet & fillin) const

Interface Category:

API.

Purpose:

Fills in the properties matched between the set passed in and this entity.

Calling Context:

Call this function directly.

Parameters:

TPropertySet & fillin -The set containing items to be matched and filled in.

Return Value:

Returns true if all requested properties are returned with valid values.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found. Throws TFileSystemTypeMismatch if the requested system property is not defined on that type of TFileSystemEntity.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::WriteProperties

virtual void WriteProperties (const TPropertySet & properties) const

Interface Category:

API.

Purpose:

Updates (and adds to) properties associated with this entity.

Calling Context:

Call this function directly.

Parameters:

const TPropertySet & properties -The set of properties to write to the property store for this entity.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

No exception is thrown if any properties cannot be written (for example, are immutable). This allows ReadProperties to be followed by a WriteProperties without requiring exception handling for a common case.

Member Function: TFileSystemEntity::ReadProperty

virtual bool ReadProperty (TProperty & fillin) const

Interface Category:

API.

Purpose:

Takes the property in fillin, and if it exists in this entity, fills in the value.

Calling Context:

Call this function directly.

Parameters:

TProperty & fillin -The property to be filled in.

Return Value:

Returns true if the property is filled in with a valid value.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::WriteProperty

virtual void WriteProperty (const TProperty & property) const

Interface Category:

API.

Purpose:

Writes the property passed as a parameter into the property store associated with this entity.

Calling Context:

Call this function directly.

Parameters:

const TProperty & property -The property to be filled in.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

No exception is thrown if the property cannot be written (for example, is immutable). This allows ReadProperties to be followed by a WriteProperties without requiring exception handling for a common case.

Member Function: TFileSystemEntity::DeleteProperty

virtual bool DeleteProperty (const TPropertyID & id) const

Interface Category:

API.

Purpose:

Removes this property from the property store for this entity.

Calling Context:

Call this function directly.

Parameters:

const TPropertyID & id -The ID of the property to delete.

Return Value:

Returns true.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

No exception is thrown if the property cannot be deleted (for example, is immutable). This allows ReadProperties to be followed by a DeleteProperties without requiring exception handling for a common case.

Member Function: TFileSystemEntity::DeleteProperties

virtual bool DeleteProperties (const TPropertyIDSet & set) const

Interface Category:

API.

Purpose:

Deletes several properties at a time.

Calling Context:

Call this function directly.

Parameters:

const TPropertyIDSet & set -The set of property IDs to delete from the property store for this object.

Return Value:

Returns true.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

Member Function: TFileSystemEntity::Member

virtual bool Member (const TPropertyID & id) const

Interface Category:

API.

Purpose:

Determines if a property with ID exists for this entity.

Calling Context:

Call this function directly.

Parameters:

const TPropertyID & id -The ID to check for.

Return Value:

Returns true if the property with the correct ID exists.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::SatisfiesQuery

virtual bool SatisfiesQuery (const TPropertyQuery & query) const

Interface Category:

API.

Purpose:

Determines if properties for this entity satisfy the query.

Calling Context:

Call this function directly.

Parameters:

const TPropertyQuery & query -The query to evaluate.

Return Value:

Returns true if properties for this entity satisfy the query.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::GetPropertiesCount

virtual unsigned long GetPropertiesCount () const

Interface Category:

API.

Purpose:

Returns the number of properties in the property store for this entity.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The number of properties.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::GetPropertiesSize

virtual unsigned long GetPropertiesSize () const

Interface Category:

API.

Purpose:

Returns the amount of storage occupied by the properties for this entity.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The size of the properties.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::GetName

virtual TFileSystemEntityName GetName () const

Interface Category:

API.

Purpose:

Gets the name of this file system entity.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The name of the entity.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::SetName

virtual void SetName (const TFileSystemEntityName & newName) const

Interface Category:

API.

Purpose:

Allows the entity to be renamed.

Calling Context:

Call this function directly.

Parameters:

const TFileSystemEntityName & newName -The new name for this entity.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found. Throws TFileSystemEntityAlreadyExists if an entity with the new name already exists. Throws TFileSystemAccessDenied if the caller is not privileged to change the name.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::GetModificationTime

virtual TTime GetModificationTime () const

Interface Category:

API.

Purpose:

Finds out when this entity was last modified.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a time object for when this entity was last modified.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::SetModificationTime

virtual void SetModificationTime (const TTime & modificationTime) const

Interface Category:

API.

Purpose:

Updates the last time-modified property for this entity.

Calling Context:

Call this function directly.

Parameters:

const TTime & modificationTime -The new last modification time value.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::GetFileSystemEntityKind

virtual TFileSystemEntityKind GetFileSystemEntityKind () const

Interface Category:

API.

Purpose:

Finds out what kind of file system entity this object represents (file, directory, or volume).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A kind for this entity.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::IsA

virtual bool IsA (const TFileSystemEntityKind & kind) const

Interface Category:

API.

Purpose:

Determines if this entity is a specific kind of file system entity (TFile, for example).

Calling Context:

Call this function directly.

Parameters:

const TFileSystemEntityKind & kind -The kind of entity to check for.

Return Value:

Returns true if this and kind are the same kind of file system entity. Both TFiles, for example.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::GetVolume

virtual TVolume GetVolume () const

Interface Category:

API.

Purpose:

Gets an object for the logical volume on which this entity resides.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

An entity object for the volume for this.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::HasParent

virtual bool HasParent (TDirectory & fillinParent) const

Interface Category:

API.

Purpose:

Finds out if this entity has a parent directory, and gets it if so.

Calling Context:

Call this function directly.

Parameters:

TDirectory & fillinParent -The object to fill in with the parent directory for this entity, if one exists.

Return Value:

Returns true if this entity has a parent.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Provides a hash value that can be used by Collection classes.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The long hash value

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::DeleteSelf

virtual void DeleteSelf (bool deleteChildren =false)

Interface Category:

API.

Purpose:

Deletes the item on disk represented by this object. If it is a directory, all contents are deleted recursively (if possible), then the directory is deleted. (Similarly for a volume.) If the contents cannot be deleted, an exception is thrown and DeleteSelf fails.

Calling Context:

Call this function directly.

Parameters:

bool deleteChildren =false -A flag to indicate whether to delete child entities.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found. Throws TFileSystemEntityInUse if the entity is busy.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::IsTemporary

virtual bool IsTemporary () const

Interface Category:

API.

Purpose:

Determines if the entity is temporary. A temporary entity is not guaranteed to persist across system reboots.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this entity is temporary.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::IsAPropertyStore

virtual bool IsAPropertyStore () const

Interface Category:

API.

Purpose:

Determines whether the entity is a property store.

Calling Context:

Clients should not usually call this function.

Parameters:

Takes no parameters.

Return Value:

Returns true if the entity is a property store.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

Normally, property stores are not visible as file system entities.

Member Function: TFileSystemEntity::IsConnected

bool IsConnected () const

Interface Category:

API.

Purpose:

Determines if the object is a valid file system entity, and if it represents a valid on-disk entity.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the object is a valid file system entity and represents an existing on-disk entity.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::IsValid

bool IsValid () const

Interface Category:

API.

Purpose:

Determines whether the object has been initialized.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the object is a valid file system entity.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

Call IsConnected to determine whether the object is both valid and represents an existing on-disk entity.

Member Function: TFileSystemEntity::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream the object streams itself in from.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

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. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::HasTopmostParent

virtual bool HasTopmostParent (TDirectory & fillinParent) const

Interface Category:

API.

Purpose:

Finds out if this entity has a parent directory, and gets its highest-level parent if so.

Calling Context:

Call this function directly.

Parameters:

TDirectory & fillinParent -The object to fill in with the topmost parent directory for this entity if one exists.

Return Value:

Returns true if this entity has a parent.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemEntityNotAvailable if the entity cannot be found.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

Member Function: TFileSystemEntity::operatorbool

operator bool () const

Interface Category:

API.

Purpose:

Determines whether the object has been initialized; allows expressions such as if (theEntity).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the object is a valid file system entity.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

Call IsConnected to determine whether the object is both valid and represents an existing on-disk entity.

Member Function: TFileSystemEntity::TFileSystemEntity

TFileSystemEntity ()
TFileSystemEntity (const TFileSystemEntity & copy)

Interface Category:

API.

Purpose:

Default constructor. Must be assigned to before next use.
Copy constructor.

Calling Context:

Called by the stream-in operators and anyone for fillin (for example, iterators).
Called to copy an object.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This is a handle class.

Other Considerations:

None.

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