Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MOpenFile
Inherited By:
TRecoverableMappedFile
Purpose:
Allows a file to be mapped into memory, for access via ordinary pointers.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
Do not derive from this class.
Concurrency:
Not multithread safe. This is a handle class.
Resource Use:
No special requirements.
Member Function: TMappedFile::Flush
virtual void Flush ()
Interface Category:
API.
Purpose:
Writes changes to disk.
Calling Context:
Do not call this function.
Parameters:
Return Value:
None.
Exceptions:
Throws TFileSystemObjectInvalid if the entity is uninitialized.
Throws TFileSystemAccessDenied if the caller is not privileged to write to the file.
Throws TFileSystemVolumeAccessError if the volume is full or a media error.
Concurrency:
Not multithread safe. This is a handle class.
Other Considerations:
None.
Member Function: TMappedFile::GetEndOfFile
FileSystemEntitySize GetEndOfFile () const
Interface Category:
API.
Purpose:
Obtains the size of the file.
Calling Context:
Do not call this function.
Parameters:
Return Value:
The size of the file, in bytes.
Exceptions:
Throws TFileSystemObjectInvalid if the entity is uninitialized.
Concurrency:
Not multithread safe. This is a handle class.
Other Considerations:
None.
Member Function: TMappedFile::SetEndOfFile
void SetEndOfFile (FileSystemEntitySize endOfFile)
Interface Category:
API.
Purpose:
Changes the size of the file.
Calling Context:
Do not call this function.
Parameters:
- FileSystemEntitySize endOfFile -The new size of the file.
Return Value:
None.
Exceptions:
Throws TFileSystemObjectInvalid if the entity is uninitialized.
Throws TFileSystemAccessDenied if the caller is not privileged to write to the file.
Throws TFileSystemVolumeAccessError if there is insufficient room to expand the file.
Throws TFileSystemMappedFileError if attempting to move the end-of-file to within the currently mapped range.
Concurrency:
Not multithread safe. This is a handle class.
Other Considerations:
None.
Member Function: TMappedFile::InitializeMap
void InitializeMap (const TFile & file, MOpenFile :: EPermissionsForMe forMe, MOpenFile :: EPermissionsForOthers forOthers, const TFileRange & mappedRange, EModificationVisibility modVisibility, EAddressPlacement mappingConstraints)
Interface Category:
API.
Purpose:
Initializes a TMappedFile and maps in the requested range.
Calling Context:
Called by derived classes.
Parameters:
- const TFile & file -The file to be opened.
- MOpenFile :: EPermissionsForMe forMe -Access permissions for the caller.
- MOpenFile :: EPermissionsForOthers forOthers -Access permissions for subsequent attempts to open the file.
- const TFileRange & mappedRange -The range to be mapped.
- EModificationVisibility modVisibility -kPrivateModifications if changes are to be neither persistent nor publicly visible, or kPublicModifications if changes are to be both persistent and publicly visible.
- EAddressPlacement mappingConstraints -kMapAtSameAddress if other instances of TMappedFile for this file are to map it at a common virtual address, or kMapAnywhere to allow the system to choose the virtual address.
Return Value:
None.
Exceptions:
Throws TFileSystemEntityNotAvailable if the entity cannot be found.
Throws TFileSystemAccessDenied if the caller is not privileged to open the file with the requested permissions.
Throws TFileSystemMappedFileError if the desired range cannot be mapped.
Concurrency:
Not multithread safe. This is a handle class.
Other Considerations:
TFileSystemMappedFileError might or might not be thrown under otherwise identical circumstances on different hosts, depending on the host's inherent mapped file capabilities. For example, on some hosts it might not be possible to simultaneously map overlapping but non-identical ranges of a file.
Member Function: TMappedFile::GetRange
virtual void GetRange (TFileRange & theRange) const
Interface Category:
API.
Purpose:
Returns the currently mapped range of the file.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe. This is a handle class.
Other Considerations:
None.
Member Function: TMappedFile::SetRange
virtual void SetRange (const TFileRange & newRange, TMemorySurrogate & newMapRange)
Interface Category:
API.
Purpose:
Changes the currently mapped range.
Calling Context:
Call this function directly.
Parameters:
- const TFileRange & newRange -The range to be mapped.
- TMemorySurrogate & newMapRange -The memory surrogate to be filled in with the address of the newly mapped range.
Return Value:
None.
Exceptions:
Throws TFileSystemObjectInvalid if the entity is uninitialized.
Throws TFileSystemMappedFileError if the desired range cannot be mapped.
Throws TFileSystemVolumeAccessError if the old range must be flushed and the volume is full, or a media error.
Throws TFileSystemAccessDenied if the old range must be flushed and the caller is not privileged to write to the file.
Concurrency:
Not multithread safe. This is a handle class.
Other Considerations:
TFileSystemMappedFileError might or might not be thrown under otherwise identical circumstances on different hosts, depending on the host's inherent mapped file capabilities. For example, on some hosts it might not be possible to simultaneously map overlapping but non-identical ranges of a file.
Member Function: TMappedFile::GetMemorySurrogate
virtual void GetMemorySurrogate (TMemorySurrogate & mapRange) const
Interface Category:
API.
Purpose:
Fill in the argument with memory surrogate representing the address of the currently mapped range.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe. This is a handle class.
Other Considerations:
None.
virtual ~ TMappedFile ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe. This is a handle class.
Other Considerations:
None.
- TMappedFile (const TFile & file, MOpenFile :: EPermissionsForMe forMe
- MOpenFile :: kReadWrite, MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowNone, const TFileRange & rangeToMap =TFileRange :: kEntireFile, EModificationVisibility modVisibility =kPublicModifications, EAddressPlacement mappingConstraints =kMapAnywhere)
- TMappedFile ()
Interface Category:
API.
Purpose:
- Constructs a fully initialized TMappedFile.
- Default constructor allowing delayed initialization.
Calling Context:
- Call this function directly.
- Called by the stream-in operators.
Parameters:
- const TFile & file -The file to be mapped.
- MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kReadWrite -Access permissions for the caller.
- MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowNone -Access permissions for subsequent attempts to open the rangeToMap =TFileRange :: kEntireFile.
- const TFileRange & rangeToMap =TFileRange :: kEntireFile -The range to be mapped.
- EModificationVisibility modVisibility =kPublicModifications -kPrivateModifications if changes are to be neither persistent nor publicly visible, or kPublicModifications if changes are to be both persistent and publicly visible.
- EAddressPlacement mappingConstraints =kMapAnywhere -kMapAtSameAddress if other instances of TMappedFile for this file are to map it at a common virtual address, or kMapAnywhere to allow the system to choose the virtual address.
- Takes no parameters.
Return Value:
None.
Exceptions:
Throws TFileSystemEntityNotAvailable if the entity cannot be found.
Throws TFileSystemAccessDenied if the caller is not privileged to open the file with the requested permissions.
Throws TFileSystemMappedFileError if the desired range cannot be mapped.
Concurrency:
Not multithread safe. This is a handle class.
Other Considerations:
TFileSystemMappedFileError might or might not be thrown under otherwise identical circumstances on different hosts, depending on the host's inherent mapped file capabilities. For example, on some hosts it might not be possible to simultaneously map overlapping but non-identical ranges of a file.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.