Common Portability Library C++ API

cpl_odbc.h

ODBC Abstraction Layer (C++).

class CPLODBCDriverInstaller

#include <cpl_odbc.h>

A class providing functions to install or remove ODBC driver.

Public Functions

CPLODBCDriverInstaller()

int InstallDriver(const char *pszDriver, const char *pszPathIn, WORD fRequest = ODBC_INSTALL_COMPLETE)

Installs ODBC driver or updates definition of already installed driver.

Interanally, it calls ODBC's SQLInstallDriverEx function.

パラメータ:

• pszDriver -- - The driver definition as a list of keyword-value pairs describing the driver (See ODBC API Reference).

• pszPathIn -- - Full path of the target directory of the installation, or a null pointer (for unixODBC, NULL is passed).

• fRequest -- - The fRequest argument must contain one of the following values: ODBC_INSTALL_COMPLETE - (default) complete the installation request ODBC_INSTALL_INQUIRY - inquire about where a driver can be installed

戻り値:

TRUE indicates success, FALSE if it fails.

int RemoveDriver(const char *pszDriverName, int fRemoveDSN = FALSE)

Removes or changes information about the driver from the Odbcinst.ini entry in the system information.

パラメータ:

• pszDriverName -- - The name of the driver as registered in the Odbcinst.ini key of the system information.

• fRemoveDSN -- - TRUE: Remove DSNs associated with the driver specified in lpszDriver. FALSE: Do not remove DSNs associated with the driver specified in lpszDriver.

戻り値:

The function returns TRUE if it is successful, FALSE if it fails. If no entry exists in the system information when this function is called, the function returns FALSE. In order to obtain usage count value, call GetUsageCount().

inline int GetUsageCount() const

The usage count of the driver after this function has been called.

inline const char *GetPathOut() const

Path of the target directory where the driver should be installed.

For details, see ODBC API Reference and lpszPathOut parameter of SQLInstallDriverEx

inline const char *GetLastError() const

If InstallDriver returns FALSE, then GetLastError then error message can be obtained by calling this function.

Internally, it calls ODBC's SQLInstallerError function.

inline DWORD GetLastErrorCode() const

If InstallDriver returns FALSE, then GetLastErrorCode then error code can be obtained by calling this function.

Internally, it calls ODBC's SQLInstallerError function. See ODBC API Reference for possible error flags.

Public Static Functions

static void InstallMdbToolsDriver()

Attempts to install the MDB Tools driver for Microsoft Access databases.

This is only supported on non-Windows platforms.

Since

GDAL 3.4

Private Members

char m_szPathOut[ODBC_FILENAME_MAX]

char m_szError[SQL_MAX_MESSAGE_LENGTH]

DWORD m_nErrorCode

DWORD m_nUsageCount

Private Static Functions

static bool FindMdbToolsDriverLib(CPLString &osDriverFile)

static bool LibraryExists(const char *pszLibPath)

class CPLODBCSession

#include <cpl_odbc.h>

A class representing an ODBC database session.

Includes error collection services.

Public Functions

CPLODBCSession()

Constructor.

~CPLODBCSession()

Destructor.

int EstablishSession(const char *pszDSN, const char *pszUserid, const char *pszPassword)

Connect to database and logon.

パラメータ:

• pszDSN -- The name of the DSN being used to connect. This is not optional.

• pszUserid -- the userid to logon as, may be NULL if not not required, or provided by the DSN.

• pszPassword -- the password to logon with. May be NULL if not required or provided by the DSN.

戻り値:

TRUE on success or FALSE on failure. Call GetLastError() to get details on failure.

const char *GetLastError()

Returns the last ODBC error message.

戻り値:

pointer to an internal buffer with the error message in it. Do not free or alter. Will be an empty (but not NULL) string if there is no pending error info.

int ClearTransaction()

Clear transaction.

int BeginTransaction()

Begin transaction.

int CommitTransaction()

Commit transaction.

int RollbackTransaction()

Rollback transaction.

inline int IsInTransaction()

Returns whether a transaction is active.

int CloseSession()

Close session.

int Failed(int, HSTMT = nullptr)

Test if a return code indicates failure, return TRUE if that is the case.

Also update error text.

ODBC error messages are reported in the following format: [SQLState]ErrorMessage(NativeErrorCode)

Multiple error messages are delimited by ",".

inline HDBC GetConnection()

Return connection handle.

inline HENV GetEnvironment()

Return GetEnvironment handle.

bool ConnectToMsAccess(const char *pszName, const char *pszDSNStringTemplate)

Connects to a Microsoft Access database.

Since

GDAL 3.2

パラメータ:

• pszName -- The file name of the Access database to connect to. This is not optional.

• pszDSNStringTemplate -- optional DSN string template for Microsoft Access ODBC Driver. If not specified, then a set of known driver templates will be used automatically as a fallback. If specified, it is the caller's responsibility to ensure that the template is correctly formatted.

戻り値:

TRUE on success or FALSE on failure. Errors will automatically be reported via CPLError.

class CPLODBCStatement

#include <cpl_odbc.h>

Abstraction for statement, and resultset.

Includes methods for executing an SQL statement, and for accessing the resultset from that statement. Also provides for executing other ODBC requests that produce results sets such as SQLColumns() and SQLTables() requests.

Public Types

enum Flag

Flags which control ODBC statement behavior.

Values:

enumerator RetrieveNumericColumnsAsDouble

Numeric column values should be retrieved as doubles, using either the SQL_C_DOUBLE or SQL_C_FLOAT types.

By default numeric column values are retrieved as characters. Retrieving as character is the safest behavior, but can risk loss of precision.

If set, GetColDataAsDouble should be used for numeric columns instead of GetColData.

Warning: this flag can expose issues in particular ODBC drivers on different platforms. Use with caution.

Public Functions

explicit CPLODBCStatement(CPLODBCSession*, int flags = 0)

Constructor.

The optional flags argument can be used to specify flags which control the behavior of the statement.

~CPLODBCStatement()

Destructor.

inline HSTMT GetStatement()

Return statement handle.

inline int Flags() const

Returns statement flags.

void Clear()

Clear internal command text and result set definitions.

void AppendEscaped(const char*)

Append text to internal command.

The passed text is appended to the internal SQL command text after escaping any special characters so it can be used as a character string in an SQL statement.

パラメータ:

pszText -- text to append.

void Append(const char*)

Append text to internal command.

The passed text is appended to the internal SQL command text.

パラメータ:

pszText -- text to append.

void Append(const std::string&)

Append text to internal command.

The passed text is appended to the internal SQL command text.

パラメータ:

s -- text to append.

void Append(int)

Append to internal command.

The passed value is formatted and appended to the internal SQL command text.

パラメータ:

nValue -- value to append to the command.

void Append(double)

Append to internal command.

The passed value is formatted and appended to the internal SQL command text.

パラメータ:

dfValue -- value to append to the command.

int Appendf(const char*, ...)

Append to internal command.

The passed format is used to format other arguments and the result is appended to the internal command text. Long results may not be formatted properly, and should be appended with the direct Append() methods.

パラメータ:

pszFormat -- printf() style format string.

戻り値:

FALSE if formatting fails due to result being too large.

inline const char *GetCommand()

Return statement string.

int ExecuteSQL(const char* = nullptr)

Execute an SQL statement.

This method will execute the passed (or stored) SQL statement, and initialize information about the resultset if there is one. If a NULL statement is passed, the internal stored statement that has been previously set via Append() or Appendf() calls will be used.

パラメータ:

pszStatement -- the SQL statement to execute, or NULL if the internally saved one should be used.

戻り値:

TRUE on success or FALSE if there is an error. Error details can be fetched with OGRODBCSession::GetLastError().

int Fetch(int nOrientation = SQL_FETCH_NEXT, int nOffset = 0)

Fetch a new record.

Requests the next row in the current resultset using the SQLFetchScroll() call. Note that many ODBC drivers only support the default forward fetching one record at a time. Only SQL_FETCH_NEXT (the default) should be considered reliable on all drivers.

Currently it isn't clear how to determine whether an error or a normal out of data condition has occurred if Fetch() fails.

パラメータ:

• nOrientation -- One of SQL_FETCH_NEXT, SQL_FETCH_LAST, SQL_FETCH_PRIOR, SQL_FETCH_ABSOLUTE, or SQL_FETCH_RELATIVE (default is SQL_FETCH_NEXT).

• nOffset -- the offset (number of records), ignored for some orientations.

戻り値:

TRUE if a new row is successfully fetched, or FALSE if not.

void ClearColumnData()

ClearColumnData.

int GetColCount()

Fetch the resultset column count.

戻り値:

the column count, or zero if there is no resultset.

const char *GetColName(int)

Fetch a column name.

パラメータ:

iCol -- the zero based column index.

戻り値:

NULL on failure (out of bounds column), or a pointer to an internal copy of the column name.

short GetColType(int)

Fetch a column data type.

The return type code is a an ODBC SQL_ code, one of SQL_UNKNOWN_TYPE, SQL_CHAR, SQL_NUMERIC, SQL_DECIMAL, SQL_INTEGER, SQL_SMALLINT, SQL_FLOAT, SQL_REAL, SQL_DOUBLE, SQL_DATETIME, SQL_VARCHAR, SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMPT.

パラメータ:

iCol -- the zero based column index.

戻り値:

type code or -1 if the column is illegal.

const char *GetColTypeName(int)

Fetch a column data type name.

Returns data source-dependent data type name; for example, "CHAR", "VARCHAR", "MONEY", "LONG VARBINAR", or "CHAR ( ) FOR BIT DATA".

パラメータ:

iCol -- the zero based column index.

戻り値:

NULL on failure (out of bounds column), or a pointer to an internal copy of the column dat type name.

short GetColSize(int)

Fetch the column width.

パラメータ:

iCol -- the zero based column index.

戻り値:

column width, zero for unknown width columns.

short GetColPrecision(int)

Fetch the column precision.

パラメータ:

iCol -- the zero based column index.

戻り値:

column precision, may be zero or the same as column size for columns to which it does not apply.

short GetColNullable(int)

Fetch the column nullability.

パラメータ:

iCol -- the zero based column index.

戻り値:

TRUE if the column may contains or FALSE otherwise.

const char *GetColColumnDef(int)

Fetch a column default value.

Returns the default value of a column.

パラメータ:

iCol -- the zero based column index.

戻り値:

NULL if the default value is not dpecified or the internal copy of the default value.

int GetColId(const char*) const

Fetch column index.

Gets the column index corresponding with the passed name. The name comparisons are case insensitive.

パラメータ:

pszColName -- the name to search for.

戻り値:

the column index, or -1 if not found.

const char *GetColData(int, const char* = nullptr)

Fetch column data.

Fetches the data contents of the requested column for the currently loaded row. The result is returned as a string regardless of the column type. NULL is returned if an illegal column is given, or if the actual column is "NULL".

パラメータ:

• iCol -- the zero based column to fetch.

• pszDefault -- the value to return if the column does not exist, or is NULL. Defaults to NULL.

戻り値:

pointer to internal column data or NULL on failure.

const char *GetColData(const char*, const char* = nullptr)

Fetch column data.

Fetches the data contents of the requested column for the currently loaded row. The result is returned as a string regardless of the column type. NULL is returned if an illegal column is given, or if the actual column is "NULL".

パラメータ:

• pszColName -- the name of the column requested.

• pszDefault -- the value to return if the column does not exist, or is NULL. Defaults to NULL.

戻り値:

pointer to internal column data or NULL on failure.

int GetColDataLength(int)

GetColDataLength.

double GetColDataAsDouble(int) const

Fetch column data as a double value.

Fetches the data contents of the requested column for the currently loaded row as a double value.

Returns NaN if a non-numeric column is requested or the actual column value is "NULL".

警告

this method can only be used if the Flag::RetrieveNumericColumnsAsDouble flag was set for the CPLODBCStatement.

パラメータ:

iCol -- the zero based column to fetch.

戻り値:

numeric column value or NaN on failure.

double GetColDataAsDouble(const char*) const

Fetch column data as a double value.

Fetches the data contents of the requested column for the currently loaded row as a double value.

Returns NaN if a non-numeric column is requested or the actual column value is "NULL".

警告

this method can only be used if the Flag::RetrieveNumericColumnsAsDouble flag was set for the CPLODBCStatement.

パラメータ:

pszColName -- the name of the column requested.

戻り値:

numeric column value or NaN on failure.

int GetRowCountAffected()

GetRowCountAffected.

int GetColumns(const char *pszTable, const char *pszCatalog = nullptr, const char *pszSchema = nullptr)

Fetch column definitions for a table.

The SQLColumn() method is used to fetch the definitions for the columns of a table (or other queryable object such as a view). The column definitions are digested and used to populate the CPLODBCStatement column definitions essentially as if a "SELECT * FROM tablename" had been done; however, no resultset will be available.

パラメータ:

• pszTable -- the name of the table to query information on. This should not be empty.

• pszCatalog -- the catalog to find the table in, use NULL (the default) if no catalog is available.

• pszSchema -- the schema to find the table in, use NULL (the default) if no schema is available.

戻り値:

TRUE on success or FALSE on failure.

int GetPrimaryKeys(const char *pszTable, const char *pszCatalog = nullptr, const char *pszSchema = nullptr)

Fetch primary keys for a table.

The SQLPrimaryKeys() function is used to fetch a list of fields forming the primary key. The result is returned as a result set matching the SQLPrimaryKeys() function result set. The 4th column in the result set is the column name of the key, and if the result set contains only one record then that single field will be the complete primary key.

パラメータ:

• pszTable -- the name of the table to query information on. This should not be empty.

• pszCatalog -- the catalog to find the table in, use NULL (the default) if no catalog is available.

• pszSchema -- the schema to find the table in, use NULL (the default) if no schema is available.

戻り値:

TRUE on success or FALSE on failure.

int GetTables(const char *pszCatalog = nullptr, const char *pszSchema = nullptr)

Fetch tables in database.

The SQLTables() function is used to fetch a list tables in the database. The result is returned as a result set matching the SQLTables() function result set. The 3rd column in the result set is the table name. Only tables of type "TABLE" are returned.

パラメータ:

• pszCatalog -- the catalog to find the table in, use NULL (the default) if no catalog is available.

• pszSchema -- the schema to find the table in, use NULL (the default) if no schema is available.

戻り値:

TRUE on success or FALSE on failure.

void DumpResult(FILE *fp, int bShowSchema = FALSE)

Dump resultset to file.

The contents of the current resultset are dumped in a simply formatted form to the provided file. If requested, the schema definition will be written first.

パラメータ:

• fp -- the file to write to. stdout or stderr are acceptable.

• bShowSchema -- TRUE to force writing schema information for the rowset before the rowset data itself. Default is FALSE.

int CollectResultsInfo()

CollectResultsInfo.

Public Static Functions

static CPLString GetTypeName(int)

Get name for SQL column type.

Returns a string name for the indicated type code (as returned from CPLODBCStatement::GetColType()).

パラメータ:

nTypeCode -- the SQL_ code, such as SQL_CHAR.

戻り値:

internal string, "UNKNOWN" if code not recognised.

static SQLSMALLINT GetTypeMapping(SQLSMALLINT)

Get appropriate C data type for SQL column type.

Returns a C data type code, corresponding to the indicated SQL data type code (as returned from CPLODBCStatement::GetColType()).

パラメータ:

nTypeCode -- the SQL_ code, such as SQL_CHAR.

戻り値:

data type code. The valid code is always returned. If SQL code is not recognised, SQL_C_BINARY will be returned.

cpl_vsi_virtual.h

Typedefs

typedef std::unique_ptr<VSIVirtualHandle, VSIVirtualHandleCloser> VSIVirtualHandleUniquePtr

Unique pointer of VSIVirtualHandle that calls the Close() method.

Functions

VSIVirtualHandle *VSICreateBufferedReaderHandle(VSIVirtualHandle *poBaseHandle)

VSIVirtualHandle *VSICreateBufferedReaderHandle(VSIVirtualHandle *poBaseHandle, const GByte *pabyBeginningContent, vsi_l_offset nCheatFileSize)

VSIVirtualHandle *VSICreateCachedFile(VSIVirtualHandle *poBaseHandle, size_t nChunkSize = VSI_CACHED_DEFAULT_CHUNK_SIZE, size_t nCacheSize = 0)

Wraps a file handle in another one, which has caching for read-operations.

This takes a virtual file handle and returns a new handle that caches read-operations on the input file handle. The cache is RAM based and the content of the cache is discarded when the file handle is closed. The cache is a least-recently used lists of blocks of 32KB each.

パラメータ:

• poBaseHandle -- base handle

• nChunkSize -- chunk size, in bytes. If 0, defaults to 32 KB

• nCacheSize -- total size of the cache for the file, in bytes. If 0, defaults to the value of the VSI_CACHE_SIZE configuration option, which defaults to 25 MB.

戻り値:

a new handle

VSIVirtualHandle *VSICreateGZipWritable(VSIVirtualHandle *poBaseHandle, int nDeflateType, int bAutoCloseBaseHandle)

VSIVirtualHandle *VSICreateGZipWritable(VSIVirtualHandle *poBaseHandle, int nDeflateType, bool bAutoCloseBaseHandle, int nThreads, size_t nChunkSize, size_t nSOZIPIndexEltSize, std::vector<uint8_t> *panSOZIPIndex)

VSIVirtualHandle *VSICreateUploadOnCloseFile(VSIVirtualHandleUniquePtr &&poWritableHandle, VSIVirtualHandleUniquePtr &&poTmpFile, const std::string &osTmpFilename)

Variables

constexpr int VSI_CACHED_DEFAULT_CHUNK_SIZE = 32768

const int CPL_DEFLATE_TYPE_GZIP = 0

const int CPL_DEFLATE_TYPE_ZLIB = 1

const int CPL_DEFLATE_TYPE_RAW_DEFLATE = 2

struct VSIVirtualHandle

#include <cpl_vsi_virtual.h>

Virtual file handle.

Subclassed by VSISparseFileHandle, VSISubFileHandle, VSIUploadOnCloseHandle

Public Functions

virtual int Seek(vsi_l_offset nOffset, int nWhence) = 0

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.

Caution: vsi_l_offset is a unsigned type, so SEEK_CUR can only be used for positive seek. If negative seek is needed, use handle->Seek( handle->Tell() + negative_offset, SEEK_SET ).

パラメータ:

• nOffset -- offset in bytes.

• nWhence -- one of SEEK_SET, SEEK_CUR or SEEK_END.

戻り値:

0 on success or -1 one failure.

virtual vsi_l_offset Tell() = 0

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.

戻り値:

file offset in bytes.

virtual size_t Read(void *pBuffer, size_t nSize, size_t nCount) = 0

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.

パラメータ:

• 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.

戻り値:

number of objects successfully read. If that number is less than nCount, VSIFEofL() or VSIFErrorL() can be used to determine the reason for the short read.

virtual int ReadMultiRange(int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes)

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/.

Since

GDAL 1.9.0

パラメータ:

• 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).

戻り値:

0 in case of success, -1 otherwise.

inline virtual void AdviseRead(int nRanges, const vsi_l_offset *panOffsets, const size_t *panSizes)

This method is called when code plans to access soon one or several ranges in a file.

Some file systems may be able to use this hint to for example asynchronously start such requests.

Offsets may be given in a non-increasing order, and may potentially overlap.

Since

GDAL 3.7

パラメータ:

• nRanges -- Size of the panOffsets and panSizes arrays.

• panOffsets -- Array containing the start offset of each range.

• panSizes -- Array containing the size (in bytes) of each range.

inline virtual size_t GetAdviseReadTotalBytesLimit() const

Return the total maximum number of bytes that AdviseRead() can handle at once.

Some AdviseRead() implementations may give up if the sum of the values in the panSizes[] array provided to AdviseRead() exceeds a limit.

Callers might use that threshold to optimize the efficiency of AdviseRead().

A returned value of 0 indicates a unknown limit.

Since

GDAL 3.9

virtual size_t Write(const void *pBuffer, size_t nSize, size_t nCount) = 0

Write bytes to file.

Writes 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.

パラメータ:

• pBuffer -- the buffer from which the data should be written (at least nCount * nSize bytes in size.

• nSize -- size of objects to write in bytes.

• nCount -- number of objects to write.

戻り値:

number of objects successfully written.

int Printf(const char *pszFormat, ...)

Formatted write to file.

Provides fprintf() style formatted output to a VSI*L file. This formats an internal buffer which is written using VSIFWriteL().

Analog of the POSIX fprintf() call.

パラメータ:

pszFormat -- the printf() style format string.

戻り値:

the number of bytes written or -1 on an error.

virtual void ClearErr() = 0

Reset the error and end-of-file indicators.

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

Analog of the POSIX clearerr() call.

Since

3.10

virtual int Eof() = 0

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, or a call to VSIFClearErrL().

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

Analog of the POSIX feof() call.

戻り値:

TRUE if at EOF, else FALSE.

virtual int Error() = 0

Test the error indicator.

Returns TRUE (non-zero) if an error condition occurred during the previous read operation. The error indicator is cleared by a call to VSIFClearErrL(). Note that a end-of-file situation, reported by VSIFEofL(), is not an error reported by VSIFErrorL().

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

Analog of the POSIX ferror() call.

Since

3.10

戻り値:

TRUE if the error indicator is set, else FALSE.

inline virtual int Flush()

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.

On Windows regular files, this method does nothing, unless the VSI_FLUSH configuration option is set to YES (and only when the file has not been opened with the WRITE_THROUGH option).

戻り値:

0 on success or -1 on error.

virtual int Close() = 0

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.

戻り値:

0 on success or -1 on failure.

virtual int Truncate(vsi_l_offset nNewSize)

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.

Since

GDAL 1.9.0

パラメータ:

nNewSize -- new size in bytes.

戻り値:

0 on success

inline virtual void *GetNativeFileDescriptor()

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.

戻り値:

the native file descriptor, or NULL.

inline virtual VSIRangeStatus GetRangeStatus(vsi_l_offset nOffset, vsi_l_offset nLength)

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 extent is filled with zeroes! It must be interpreted as "may

contain non-zero data".

Since

GDAL 2.2

パラメータ:

• nOffset -- offset of the start of the extent.

• nLength -- extent length.

戻り値:

extent status: VSI_RANGE_STATUS_UNKNOWN, VSI_RANGE_STATUS_DATA or VSI_RANGE_STATUS_HOLE

virtual bool HasPRead() const

Returns whether this file handle supports the PRead() method.

Since

GDAL 3.6

virtual size_t PRead(void *pBuffer, size_t nSize, vsi_l_offset nOffset) const

Do a parallel-compatible read operation.

This methods reads into pBuffer up to nSize bytes starting at offset nOffset in the file. The current file offset is not affected by this method.

The implementation is thread-safe: several threads can issue PRead() concurrently on the same VSIVirtualHandle object.

This method has the same semantics as pread() Linux operation. It is only available if HasPRead() returns true.

Since

GDAL 3.6

パラメータ:

• pBuffer -- output buffer (must be at least nSize bytes large).

• nSize -- number of bytes to read in the file.

• nOffset -- file offset from which to read.

戻り値:

number of bytes read.

inline virtual ~VSIVirtualHandle()

struct VSIVirtualHandleCloser

#include <cpl_vsi_virtual.h>

Helper close to use with a std:unique_ptr<VSIVirtualHandle>, such as VSIVirtualHandleUniquePtr.

Public Functions

inline void operator()(VSIVirtualHandle *poHandle)

Operator () that closes and deletes the file handle.

参考

Common Portability Library C API.