GDAL
Public Member Functions | List of all members
VSIVirtualHandle Class Referenceabstract

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

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 ( )
inlinevirtual

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 ( )
inlinevirtual

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 
)
inlinevirtual

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
nOffsetoffset of the start of the extent.
nLengthextent 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
pBufferthe buffer into which the data should be read (at least nCount * nSize bytes in size.
nSizesize of objects to read in bytes.
nCountnumber 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
nRangesnumber of ranges to read.
ppDataarray of nRanges buffer into which the data should be read (ppData[i] must be at list panSizes[i] bytes).
panOffsetsarray of nRanges offsets at which the data should be read.
panSizesarray 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
nOffsetoffset in bytes.
nWhenceone 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
nNewSizenew 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
pBufferthe buffer from which the data should be written (at least nCount * nSize bytes in size.
nSizesize of objects to read in bytes.
nCountnumber of objects to read.
Returns
number of objects successfully written.

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

Generated for GDAL by doxygen 1.8.8.