Virtual file handle. More...

#include <cpl_vsi_virtual.h>

Inherited by VSISparseFileHandle, and VSISubFileHandle.

Public Member Functions
virtual int	Seek (vsi_l_offset nOffset, int nWhence)=0
	Seek to requested offset.
virtual vsi_l_offset	Tell ()=0
	Tell current file offset.
virtual size_t	Read (void *pBuffer, size_t nSize, size_t nCount)=0
	Read bytes from file.
virtual int	ReadMultiRange (int nRanges, void *ppData, const vsi_l_offset panOffsets, const size_t *panSizes)
	Read several ranges of bytes from file.
virtual size_t	Write (const void *pBuffer, size_t nSize, size_t nCount)=0
	Write bytes to file.
virtual int	Eof ()=0
	Test for end of file.
virtual int	Flush ()
	Flush pending writes to disk.
virtual int	Close ()=0
	Close file.
virtual int	Truncate (vsi_l_offset nNewSize)
	Truncate/expand the file to the specified size.
virtual void *	GetNativeFileDescriptor ()
	Returns the "native" file descriptor for the virtual handle.
virtual VSIRangeStatus	GetRangeStatus (vsi_l_offset nOffset, vsi_l_offset nLength)
	Return if a given file range contains data or holes filled with zeroes.

Detailed Description

Virtual file handle.

Member Function Documentation

VSIVirtualHandle::Close ( ) [pure virtual]

Close file.

This function closes the indicated file.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fclose() function.

Returns:: 0 on success or -1 on failure.

VSIVirtualHandle::Eof ( ) [pure virtual]

Test for end of file.

Returns TRUE (non-zero) if an end-of-file condition occurred during the previous read operation. The end-of-file flag is cleared by a successful VSIFSeekL() call.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX feof() call.

Returns:: TRUE if at EOF else FALSE.

VSIVirtualHandle::Flush ( ) [inline, virtual]

Flush pending writes to disk.

For files in write or update mode and on filesystem types where it is applicable, all pending output on the file is flushed to the physical disk.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fflush() call.

Returns:: 0 on success or -1 on error.

VSIVirtualHandle::GetNativeFileDescriptor ( ) [inline, virtual]

Returns the "native" file descriptor for the virtual handle.

This will only return a non-NULL value for "real" files handled by the operating system (to be opposed to GDAL virtual file systems).

On POSIX systems, this will be a integer value ("fd") cast as a void*. On Windows systems, this will be the HANDLE.

Returns:: the native file descriptor, or NULL.

VSIVirtualHandle::GetRangeStatus	(	vsi_l_offset	nOffset,
		vsi_l_offset	nLength
	)		`[inline, virtual]`

Return if a given file range contains data or holes filled with zeroes.

This uses the filesystem capabilities of querying which regions of a sparse file are allocated or not. This is currently only implemented for Linux (and no other Unix derivatives) and Windows.

Note: A return of VSI_RANGE_STATUS_DATA doesn't exclude that the exte,t is filled with zeroes! It must be interpreted as "may contain non-zero data".

Parameters:

nOffset	offset of the start of the extent.
nLength	extent length.

Returns:: extent status: VSI_RANGE_STATUS_UNKNOWN, VSI_RANGE_STATUS_DATA or VSI_RANGE_STATUS_HOLE

Since:: GDAL 2.2

VSIVirtualHandle::Read	(	void *	pBuffer,
		size_t	nSize,
		size_t	nCount
	)		`[pure virtual]`

Read bytes from file.

Reads nCount objects of nSize bytes from the indicated file at the current offset into the indicated buffer.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fread() call.

Parameters:

pBuffer	the buffer into which the data should be read (at least nCount * nSize bytes in size.
nSize	size of objects to read in bytes.
nCount	number of objects to read.

Returns:: number of objects successfully read.

VSIVirtualHandle::ReadMultiRange	(	int	nRanges,
		void **	ppData,
		const vsi_l_offset *	panOffsets,
		const size_t *	panSizes
	)		`[virtual]`

Read several ranges of bytes from file.

Reads nRanges objects of panSizes[i] bytes from the indicated file at the offset panOffsets[i] into the buffer ppData[i].

Ranges must be sorted in ascending start offset, and must not overlap each other.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory or /vsicurl/.

Parameters:

nRanges	number of ranges to read.
ppData	array of nRanges buffer into which the data should be read (ppData[i] must be at list panSizes[i] bytes).
panOffsets	array of nRanges offsets at which the data should be read.
panSizes	array of nRanges sizes of objects to read (in bytes).

Returns:: 0 in case of success, -1 otherwise.

Since:: GDAL 1.9.0

int VSIVirtualHandle::Seek	(	vsi_l_offset	nOffset,
		int	nWhence
	)		`[pure virtual]`

Seek to requested offset.

Seek to the desired offset (nOffset) in the indicated file.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fseek() call.

Parameters:

nOffset	offset in bytes.
nWhence	one of SEEK_SET, SEEK_CUR or SEEK_END.

Returns:: 0 on success or -1 one failure.

VSIVirtualHandle::Tell ( ) [pure virtual]

Tell current file offset.

Returns the current file read/write offset in bytes from the beginning of the file.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX ftell() call.

Returns:: file offset in bytes.

VSIVirtualHandle::Truncate ( vsi_l_offset nNewSize ) [virtual]

Truncate/expand the file to the specified size.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX ftruncate() call.

Parameters:

nNewSize new size in bytes.

Returns:: 0 on success

Since:: GDAL 1.9.0

VSIVirtualHandle::Write	(	const void *	pBuffer,
		size_t	nSize,
		size_t	nCount
	)		`[pure virtual]`

Write bytes to file.

Writess nCount objects of nSize bytes to the indicated file at the current offset into the indicated buffer.

This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

Analog of the POSIX fwrite() call.

Parameters:

pBuffer	the buffer from which the data should be written (at least nCount * nSize bytes in size.
nSize	size of objects to read in bytes.
nCount	number of objects to read.

Returns:: number of objects successfully written.

The documentation for this class was generated from the following files:

cpl_vsi_virtual.h
cpl_vsil.cpp

Public Member Functions

Detailed Description

Member Function Documentation