831 lines
33 KiB
C
831 lines
33 KiB
C
/******************************************************************************
|
|
* $Id$
|
|
*
|
|
* Project: CPL - Common Portability Library
|
|
* Author: Frank Warmerdam, warmerdam@pobox.com
|
|
* Purpose: Include file defining Virtual File System (VSI) functions, a
|
|
* layer over POSIX file and other system services.
|
|
*
|
|
******************************************************************************
|
|
* Copyright (c) 1998, Frank Warmerdam
|
|
* Copyright (c) 2008-2014, Even Rouault <even dot rouault at spatialys.com>
|
|
*
|
|
* SPDX-License-Identifier: MIT
|
|
****************************************************************************/
|
|
|
|
#ifndef CPL_VSI_H_INCLUDED
|
|
#define CPL_VSI_H_INCLUDED
|
|
|
|
#include "cpl_port.h"
|
|
#include "cpl_progress.h"
|
|
|
|
#include <stdbool.h>
|
|
|
|
/**
|
|
* \file cpl_vsi.h
|
|
*
|
|
* Standard C Covers
|
|
*
|
|
* The VSI functions are intended to be hookable aliases for Standard C
|
|
* I/O, memory allocation and other system functions. They are intended
|
|
* to allow virtualization of disk I/O so that non file data sources
|
|
* can be made to appear as files, and so that additional error trapping
|
|
* and reporting can be interested. The memory access API is aliased
|
|
* so that special application memory management services can be used.
|
|
*
|
|
* It is intended that each of these functions retains exactly the same
|
|
* calling pattern as the original Standard C functions they relate to.
|
|
* This means we don't have to provide custom documentation, and also means
|
|
* that the default implementation is very simple.
|
|
*/
|
|
|
|
/* -------------------------------------------------------------------- */
|
|
/* We need access to ``struct stat''. */
|
|
/* -------------------------------------------------------------------- */
|
|
|
|
/* Unix */
|
|
#if !defined(_WIN32)
|
|
#include <unistd.h>
|
|
#endif
|
|
|
|
/* Windows */
|
|
#include <sys/stat.h>
|
|
|
|
CPL_C_START
|
|
|
|
/*! @cond Doxygen_Suppress */
|
|
#ifdef ENABLE_EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
|
|
#define EXPERIMENTAL_CPL_WARN_UNUSED_RESULT CPL_WARN_UNUSED_RESULT
|
|
#else
|
|
#define EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
|
|
#endif
|
|
/*! @endcond */
|
|
|
|
/* ==================================================================== */
|
|
/* stdio file access functions. These do not support large */
|
|
/* files, and do not go through the virtualization API. */
|
|
/* ==================================================================== */
|
|
|
|
/*! @cond Doxygen_Suppress */
|
|
|
|
FILE CPL_DLL *VSIFOpen(const char *, const char *) CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFClose(FILE *);
|
|
int CPL_DLL VSIFSeek(FILE *, long, int) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
long CPL_DLL VSIFTell(FILE *) CPL_WARN_UNUSED_RESULT;
|
|
void CPL_DLL VSIRewind(FILE *);
|
|
void CPL_DLL VSIFFlush(FILE *);
|
|
|
|
size_t CPL_DLL VSIFRead(void *, size_t, size_t,
|
|
FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
size_t CPL_DLL VSIFWrite(const void *, size_t, size_t,
|
|
FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
char CPL_DLL *VSIFGets(char *, int, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFPuts(const char *, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFPrintf(FILE *, CPL_FORMAT_STRING(const char *),
|
|
...) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
|
|
CPL_PRINT_FUNC_FORMAT(2, 3);
|
|
|
|
int CPL_DLL VSIFGetc(FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFPutc(int, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIUngetc(int, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFEof(FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
|
|
/*! @endcond */
|
|
|
|
/* ==================================================================== */
|
|
/* VSIStat() related. */
|
|
/* ==================================================================== */
|
|
|
|
/*! @cond Doxygen_Suppress */
|
|
typedef struct stat VSIStatBuf;
|
|
int CPL_DLL VSIStat(const char *, VSIStatBuf *) CPL_WARN_UNUSED_RESULT;
|
|
/*! @endcond */
|
|
|
|
#ifdef _WIN32
|
|
#define VSI_ISLNK(x) (0) /* N/A on Windows */
|
|
#define VSI_ISREG(x) ((x)&S_IFREG)
|
|
#define VSI_ISDIR(x) ((x)&S_IFDIR)
|
|
#define VSI_ISCHR(x) ((x)&S_IFCHR)
|
|
#define VSI_ISBLK(x) (0) /* N/A on Windows */
|
|
#else
|
|
/** Test if the file is a symbolic link */
|
|
#define VSI_ISLNK(x) S_ISLNK(x)
|
|
/** Test if the file is a regular file */
|
|
#define VSI_ISREG(x) S_ISREG(x)
|
|
/** Test if the file is a directory */
|
|
#define VSI_ISDIR(x) S_ISDIR(x)
|
|
/*! @cond Doxygen_Suppress */
|
|
#define VSI_ISCHR(x) S_ISCHR(x)
|
|
#define VSI_ISBLK(x) S_ISBLK(x)
|
|
/*! @endcond */
|
|
#endif
|
|
|
|
/* ==================================================================== */
|
|
/* 64bit stdio file access functions. If we have a big size */
|
|
/* defined, then provide prototypes for the large file API, */
|
|
/* otherwise redefine to use the regular api. */
|
|
/* ==================================================================== */
|
|
|
|
/** Type for a file offset */
|
|
typedef GUIntBig vsi_l_offset;
|
|
/** Maximum value for a file offset */
|
|
#define VSI_L_OFFSET_MAX GUINTBIG_MAX
|
|
|
|
/** Opaque type for a FILE that implements the VSIVirtualHandle API */
|
|
typedef struct VSIVirtualHandle VSILFILE;
|
|
|
|
VSILFILE CPL_DLL *VSIFOpenL(const char *, const char *) CPL_WARN_UNUSED_RESULT;
|
|
VSILFILE CPL_DLL *VSIFOpenExL(const char *, const char *,
|
|
int) CPL_WARN_UNUSED_RESULT;
|
|
VSILFILE CPL_DLL *VSIFOpenEx2L(const char *, const char *, int,
|
|
CSLConstList) CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFCloseL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFSeekL(VSILFILE *, vsi_l_offset,
|
|
int) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
vsi_l_offset CPL_DLL VSIFTellL(VSILFILE *) CPL_WARN_UNUSED_RESULT;
|
|
void CPL_DLL VSIRewindL(VSILFILE *);
|
|
size_t CPL_DLL VSIFReadL(void *, size_t, size_t,
|
|
VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFReadMultiRangeL(int nRanges, void **ppData,
|
|
const vsi_l_offset *panOffsets,
|
|
const size_t *panSizes,
|
|
VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
size_t CPL_DLL VSIFWriteL(const void *, size_t, size_t,
|
|
VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
void CPL_DLL VSIFClearErrL(VSILFILE *);
|
|
int CPL_DLL VSIFErrorL(VSILFILE *) CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFEofL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFTruncateL(VSILFILE *,
|
|
vsi_l_offset) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFFlushL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
int CPL_DLL VSIFPrintfL(VSILFILE *, CPL_FORMAT_STRING(const char *),
|
|
...) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
|
|
CPL_PRINT_FUNC_FORMAT(2, 3);
|
|
int CPL_DLL VSIFPutcL(int, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
|
|
|
|
/** Range status */
|
|
typedef enum
|
|
{
|
|
VSI_RANGE_STATUS_UNKNOWN, /**< Unknown */
|
|
VSI_RANGE_STATUS_DATA, /**< Data present */
|
|
VSI_RANGE_STATUS_HOLE /**< Hole */
|
|
} VSIRangeStatus;
|
|
|
|
VSIRangeStatus CPL_DLL VSIFGetRangeStatusL(VSILFILE *fp, vsi_l_offset nStart,
|
|
vsi_l_offset nLength);
|
|
|
|
int CPL_DLL VSIIngestFile(VSILFILE *fp, const char *pszFilename,
|
|
GByte **ppabyRet, vsi_l_offset *pnSize,
|
|
GIntBig nMaxSize) CPL_WARN_UNUSED_RESULT;
|
|
|
|
int CPL_DLL VSIOverwriteFile(VSILFILE *fpTarget, const char *pszSourceFilename)
|
|
CPL_WARN_UNUSED_RESULT;
|
|
|
|
#if defined(VSI_STAT64_T)
|
|
/** Type for VSIStatL() */
|
|
typedef struct VSI_STAT64_T VSIStatBufL;
|
|
#else
|
|
/** Type for VSIStatL() */
|
|
#define VSIStatBufL VSIStatBuf
|
|
#endif
|
|
|
|
int CPL_DLL VSIStatL(const char *, VSIStatBufL *) CPL_WARN_UNUSED_RESULT;
|
|
|
|
/** Flag provided to VSIStatExL() to test if the file exists */
|
|
#define VSI_STAT_EXISTS_FLAG 0x1
|
|
/** Flag provided to VSIStatExL() to query the nature (file/dir) of the file */
|
|
#define VSI_STAT_NATURE_FLAG 0x2
|
|
/** Flag provided to VSIStatExL() to query the file size */
|
|
#define VSI_STAT_SIZE_FLAG 0x4
|
|
/** Flag provided to VSIStatExL() to issue a VSIError in case of failure */
|
|
#define VSI_STAT_SET_ERROR_FLAG 0x8
|
|
/** Flag provided to VSIStatExL() to only use already cached results.
|
|
* @since GDAL 3.4
|
|
*/
|
|
#define VSI_STAT_CACHE_ONLY 0x10
|
|
|
|
int CPL_DLL VSIStatExL(const char *pszFilename, VSIStatBufL *psStatBuf,
|
|
int nFlags) CPL_WARN_UNUSED_RESULT;
|
|
|
|
int CPL_DLL VSIIsCaseSensitiveFS(const char *pszFilename);
|
|
|
|
int CPL_DLL VSISupportsSparseFiles(const char *pszPath);
|
|
|
|
bool CPL_DLL VSIIsLocal(const char *pszPath);
|
|
|
|
char CPL_DLL *VSIGetCanonicalFilename(const char *pszPath);
|
|
|
|
bool CPL_DLL VSISupportsSequentialWrite(const char *pszPath,
|
|
bool bAllowLocalTempFile);
|
|
|
|
bool CPL_DLL VSISupportsRandomWrite(const char *pszPath,
|
|
bool bAllowLocalTempFile);
|
|
|
|
int CPL_DLL VSIHasOptimizedReadMultiRange(const char *pszPath);
|
|
|
|
const char CPL_DLL *VSIGetActualURL(const char *pszFilename);
|
|
|
|
char CPL_DLL *VSIGetSignedURL(const char *pszFilename,
|
|
CSLConstList papszOptions);
|
|
|
|
const char CPL_DLL *VSIGetFileSystemOptions(const char *pszFilename);
|
|
|
|
char CPL_DLL **VSIGetFileSystemsPrefixes(void);
|
|
|
|
void CPL_DLL *VSIFGetNativeFileDescriptorL(VSILFILE *);
|
|
|
|
char CPL_DLL **
|
|
VSIGetFileMetadata(const char *pszFilename, const char *pszDomain,
|
|
CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
|
|
|
|
int CPL_DLL VSISetFileMetadata(const char *pszFilename,
|
|
CSLConstList papszMetadata,
|
|
const char *pszDomain,
|
|
CSLConstList papszOptions);
|
|
|
|
void CPL_DLL VSISetPathSpecificOption(const char *pszPathPrefix,
|
|
const char *pszKey, const char *pszValue);
|
|
void CPL_DLL VSIClearPathSpecificOptions(const char *pszPathPrefix);
|
|
const char CPL_DLL *VSIGetPathSpecificOption(const char *pszPath,
|
|
const char *pszKey,
|
|
const char *pszDefault);
|
|
|
|
void CPL_DLL VSISetCredential(const char *pszPathPrefix, const char *pszKey,
|
|
const char *pszValue)
|
|
/*! @cond Doxygen_Suppress */
|
|
CPL_WARN_DEPRECATED("Use VSISetPathSpecificOption instead")
|
|
/*! @endcond */
|
|
;
|
|
void CPL_DLL VSIClearCredentials(const char *pszPathPrefix)
|
|
/*! @cond Doxygen_Suppress */
|
|
CPL_WARN_DEPRECATED("Use VSIClearPathSpecificOptions instead")
|
|
/*! @endcond */
|
|
;
|
|
const char CPL_DLL *VSIGetCredential(const char *pszPath, const char *pszKey,
|
|
const char *pszDefault)
|
|
/*! @cond Doxygen_Suppress */
|
|
CPL_WARN_DEPRECATED("Use VSIGetPathSpecificOption instead")
|
|
/*! @endcond */
|
|
;
|
|
|
|
/* ==================================================================== */
|
|
/* Memory allocation */
|
|
/* ==================================================================== */
|
|
|
|
void CPL_DLL *VSICalloc(size_t, size_t) CPL_WARN_UNUSED_RESULT;
|
|
void CPL_DLL *VSIMalloc(size_t) CPL_WARN_UNUSED_RESULT;
|
|
void CPL_DLL VSIFree(void *);
|
|
void CPL_DLL *VSIRealloc(void *, size_t) CPL_WARN_UNUSED_RESULT;
|
|
char CPL_DLL *VSIStrdup(const char *) CPL_WARN_UNUSED_RESULT;
|
|
|
|
#if defined(__cplusplus) && defined(GDAL_COMPILATION)
|
|
extern "C++"
|
|
{
|
|
/*! @cond Doxygen_Suppress */
|
|
struct CPL_DLL VSIFreeReleaser
|
|
{
|
|
void operator()(void *p) const
|
|
{
|
|
VSIFree(p);
|
|
}
|
|
};
|
|
|
|
/*! @endcond */
|
|
}
|
|
#endif
|
|
|
|
void CPL_DLL *VSIMallocAligned(size_t nAlignment,
|
|
size_t nSize) CPL_WARN_UNUSED_RESULT;
|
|
void CPL_DLL *VSIMallocAlignedAuto(size_t nSize) CPL_WARN_UNUSED_RESULT;
|
|
void CPL_DLL VSIFreeAligned(void *ptr);
|
|
|
|
void CPL_DLL *VSIMallocAlignedAutoVerbose(size_t nSize, const char *pszFile,
|
|
int nLine) CPL_WARN_UNUSED_RESULT;
|
|
/** VSIMallocAlignedAutoVerbose() with FILE and LINE reporting */
|
|
#define VSI_MALLOC_ALIGNED_AUTO_VERBOSE(size) \
|
|
VSIMallocAlignedAutoVerbose(size, __FILE__, __LINE__)
|
|
|
|
/**
|
|
VSIMalloc2 allocates (nSize1 * nSize2) bytes.
|
|
In case of overflow of the multiplication, or if memory allocation fails, a
|
|
NULL pointer is returned and a CE_Failure error is raised with CPLError().
|
|
If nSize1 == 0 || nSize2 == 0, a NULL pointer will also be returned.
|
|
CPLFree() or VSIFree() can be used to free memory allocated by this function.
|
|
*/
|
|
void CPL_DLL *VSIMalloc2(size_t nSize1, size_t nSize2) CPL_WARN_UNUSED_RESULT;
|
|
|
|
/**
|
|
VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes.
|
|
In case of overflow of the multiplication, or if memory allocation fails, a
|
|
NULL pointer is returned and a CE_Failure error is raised with CPLError().
|
|
If nSize1 == 0 || nSize2 == 0 || nSize3 == 0, a NULL pointer will also be
|
|
returned. CPLFree() or VSIFree() can be used to free memory allocated by this
|
|
function.
|
|
*/
|
|
void CPL_DLL *VSIMalloc3(size_t nSize1, size_t nSize2,
|
|
size_t nSize3) CPL_WARN_UNUSED_RESULT;
|
|
|
|
/** VSIMallocVerbose */
|
|
void CPL_DLL *VSIMallocVerbose(size_t nSize, const char *pszFile,
|
|
int nLine) CPL_WARN_UNUSED_RESULT;
|
|
/** VSI_MALLOC_VERBOSE */
|
|
#define VSI_MALLOC_VERBOSE(size) VSIMallocVerbose(size, __FILE__, __LINE__)
|
|
|
|
/** VSIMalloc2Verbose */
|
|
void CPL_DLL *VSIMalloc2Verbose(size_t nSize1, size_t nSize2,
|
|
const char *pszFile,
|
|
int nLine) CPL_WARN_UNUSED_RESULT;
|
|
/** VSI_MALLOC2_VERBOSE */
|
|
#define VSI_MALLOC2_VERBOSE(nSize1, nSize2) \
|
|
VSIMalloc2Verbose(nSize1, nSize2, __FILE__, __LINE__)
|
|
|
|
/** VSIMalloc3Verbose */
|
|
void CPL_DLL *VSIMalloc3Verbose(size_t nSize1, size_t nSize2, size_t nSize3,
|
|
const char *pszFile,
|
|
int nLine) CPL_WARN_UNUSED_RESULT;
|
|
/** VSI_MALLOC3_VERBOSE */
|
|
#define VSI_MALLOC3_VERBOSE(nSize1, nSize2, nSize3) \
|
|
VSIMalloc3Verbose(nSize1, nSize2, nSize3, __FILE__, __LINE__)
|
|
|
|
/** VSICallocVerbose */
|
|
void CPL_DLL *VSICallocVerbose(size_t nCount, size_t nSize, const char *pszFile,
|
|
int nLine) CPL_WARN_UNUSED_RESULT;
|
|
/** VSI_CALLOC_VERBOSE */
|
|
#define VSI_CALLOC_VERBOSE(nCount, nSize) \
|
|
VSICallocVerbose(nCount, nSize, __FILE__, __LINE__)
|
|
|
|
/** VSIReallocVerbose */
|
|
void CPL_DLL *VSIReallocVerbose(void *pOldPtr, size_t nNewSize,
|
|
const char *pszFile,
|
|
int nLine) CPL_WARN_UNUSED_RESULT;
|
|
/** VSI_REALLOC_VERBOSE */
|
|
#define VSI_REALLOC_VERBOSE(pOldPtr, nNewSize) \
|
|
VSIReallocVerbose(pOldPtr, nNewSize, __FILE__, __LINE__)
|
|
|
|
/** VSIStrdupVerbose */
|
|
char CPL_DLL *VSIStrdupVerbose(const char *pszStr, const char *pszFile,
|
|
int nLine) CPL_WARN_UNUSED_RESULT;
|
|
/** VSI_STRDUP_VERBOSE */
|
|
#define VSI_STRDUP_VERBOSE(pszStr) VSIStrdupVerbose(pszStr, __FILE__, __LINE__)
|
|
|
|
GIntBig CPL_DLL CPLGetPhysicalRAM(void);
|
|
GIntBig CPL_DLL CPLGetUsablePhysicalRAM(void);
|
|
|
|
/* ==================================================================== */
|
|
/* Other... */
|
|
/* ==================================================================== */
|
|
|
|
/** Alias of VSIReadDir() */
|
|
#define CPLReadDir VSIReadDir
|
|
char CPL_DLL **VSIReadDir(const char *);
|
|
char CPL_DLL **VSIReadDirRecursive(const char *pszPath);
|
|
char CPL_DLL **VSIReadDirEx(const char *pszPath, int nMaxFiles);
|
|
char CPL_DLL **VSISiblingFiles(const char *pszPath);
|
|
|
|
const char CPL_DLL *VSIGetDirectorySeparator(const char *pszPath);
|
|
|
|
/** Opaque type for a directory iterator */
|
|
typedef struct VSIDIR VSIDIR;
|
|
|
|
VSIDIR CPL_DLL *VSIOpenDir(const char *pszPath, int nRecurseDepth,
|
|
const char *const *papszOptions);
|
|
|
|
/*! @cond Doxygen_Suppress */
|
|
typedef struct VSIDIREntry VSIDIREntry;
|
|
|
|
/*! @endcond */
|
|
|
|
/** Directory entry. */
|
|
struct VSIDIREntry
|
|
{
|
|
/** Filename */
|
|
char *pszName;
|
|
/** File mode. See VSI_ISREG() / VSI_ISDIR() */
|
|
int nMode;
|
|
/** File size */
|
|
vsi_l_offset nSize;
|
|
/** Last modification time (seconds since 1970/01/01) */
|
|
GIntBig nMTime;
|
|
/** Whether nMode is known: 0 = unknown, 1 = known. */
|
|
char bModeKnown;
|
|
/** Whether nSize is known: 0 = unknown, 1 = known. */
|
|
char bSizeKnown;
|
|
/** Whether nMTime is known: 0 = unknown, 1 = known. */
|
|
char bMTimeKnown;
|
|
/** NULL-terminated list of extra properties. */
|
|
char **papszExtra;
|
|
|
|
#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
|
|
/*! @cond Doxygen_Suppress */
|
|
VSIDIREntry();
|
|
~VSIDIREntry();
|
|
VSIDIREntry(const VSIDIREntry &);
|
|
VSIDIREntry &operator=(VSIDIREntry &) = delete;
|
|
/*! @endcond */
|
|
#endif
|
|
};
|
|
|
|
const VSIDIREntry CPL_DLL *VSIGetNextDirEntry(VSIDIR *dir);
|
|
void CPL_DLL VSICloseDir(VSIDIR *dir);
|
|
|
|
int CPL_DLL VSIMkdir(const char *pszPathname, long mode);
|
|
int CPL_DLL VSIMkdirRecursive(const char *pszPathname, long mode);
|
|
int CPL_DLL VSIRmdir(const char *pszDirname);
|
|
int CPL_DLL VSIRmdirRecursive(const char *pszDirname);
|
|
int CPL_DLL VSIUnlink(const char *pszFilename);
|
|
int CPL_DLL *VSIUnlinkBatch(CSLConstList papszFiles);
|
|
int CPL_DLL VSIRename(const char *oldpath, const char *newpath);
|
|
int CPL_DLL VSICopyFile(const char *pszSource, const char *pszTarget,
|
|
VSILFILE *fpSource, vsi_l_offset nSourceSize,
|
|
const char *const *papszOptions,
|
|
GDALProgressFunc pProgressFunc, void *pProgressData);
|
|
int CPL_DLL VSICopyFileRestartable(const char *pszSource, const char *pszTarget,
|
|
const char *pszInputPayload,
|
|
char **ppszOutputPayload,
|
|
const char *const *papszOptions,
|
|
GDALProgressFunc pProgressFunc,
|
|
void *pProgressData);
|
|
int CPL_DLL VSISync(const char *pszSource, const char *pszTarget,
|
|
const char *const *papszOptions,
|
|
GDALProgressFunc pProgressFunc, void *pProgressData,
|
|
char ***ppapszOutputs);
|
|
|
|
int CPL_DLL VSIMultipartUploadGetCapabilities(
|
|
const char *pszFilename, int *pbNonSequentialUploadSupported,
|
|
int *pbParallelUploadSupported, int *pbAbortSupported,
|
|
size_t *pnMinPartSize, size_t *pnMaxPartSize, int *pnMaxPartCount);
|
|
|
|
char CPL_DLL *VSIMultipartUploadStart(const char *pszFilename,
|
|
CSLConstList papszOptions);
|
|
char CPL_DLL *VSIMultipartUploadAddPart(const char *pszFilename,
|
|
const char *pszUploadId,
|
|
int nPartNumber,
|
|
vsi_l_offset nFileOffset,
|
|
const void *pData, size_t nDataLength,
|
|
CSLConstList papszOptions);
|
|
int CPL_DLL VSIMultipartUploadEnd(const char *pszFilename,
|
|
const char *pszUploadId, size_t nPartIdsCount,
|
|
const char *const *apszPartIds,
|
|
vsi_l_offset nTotalSize,
|
|
CSLConstList papszOptions);
|
|
int CPL_DLL VSIMultipartUploadAbort(const char *pszFilename,
|
|
const char *pszUploadId,
|
|
CSLConstList papszOptions);
|
|
|
|
int CPL_DLL VSIAbortPendingUploads(const char *pszFilename);
|
|
|
|
char CPL_DLL *VSIStrerror(int);
|
|
GIntBig CPL_DLL VSIGetDiskFreeSpace(const char *pszDirname);
|
|
|
|
void CPL_DLL VSINetworkStatsReset(void);
|
|
char CPL_DLL *VSINetworkStatsGetAsSerializedJSON(char **papszOptions);
|
|
|
|
/* ==================================================================== */
|
|
/* Install special file access handlers. */
|
|
/* ==================================================================== */
|
|
void CPL_DLL VSIInstallMemFileHandler(void);
|
|
/*! @cond Doxygen_Suppress */
|
|
void CPL_DLL VSIInstallLargeFileHandler(void);
|
|
/*! @endcond */
|
|
void CPL_DLL VSIInstallSubFileHandler(void);
|
|
void VSIInstallCurlFileHandler(void);
|
|
void CPL_DLL VSICurlClearCache(void);
|
|
void CPL_DLL VSICurlPartialClearCache(const char *pszFilenamePrefix);
|
|
void VSIInstallCurlStreamingFileHandler(void);
|
|
void VSIInstallS3FileHandler(void);
|
|
void VSIInstallS3StreamingFileHandler(void);
|
|
void VSIInstallGSFileHandler(void);
|
|
void VSIInstallGSStreamingFileHandler(void);
|
|
void VSIInstallAzureFileHandler(void);
|
|
void VSIInstallAzureStreamingFileHandler(void);
|
|
void VSIInstallADLSFileHandler(void);
|
|
void VSIInstallOSSFileHandler(void);
|
|
void VSIInstallOSSStreamingFileHandler(void);
|
|
void VSIInstallSwiftFileHandler(void);
|
|
void VSIInstallSwiftStreamingFileHandler(void);
|
|
void VSIInstall7zFileHandler(void); /* No reason to export that */
|
|
void VSIInstallRarFileHandler(void); /* No reason to export that */
|
|
void VSIInstallGZipFileHandler(void); /* No reason to export that */
|
|
void VSIInstallZipFileHandler(void); /* No reason to export that */
|
|
void VSIInstallStdinHandler(void); /* No reason to export that */
|
|
void VSIInstallHdfsHandler(void); /* No reason to export that */
|
|
void VSIInstallWebHdfsHandler(void); /* No reason to export that */
|
|
void VSIInstallStdoutHandler(void); /* No reason to export that */
|
|
void CPL_DLL VSIInstallSparseFileHandler(void);
|
|
void VSIInstallTarFileHandler(void); /* No reason to export that */
|
|
void VSIInstallCachedFileHandler(void); /* No reason to export that */
|
|
void CPL_DLL VSIInstallCryptFileHandler(void);
|
|
void CPL_DLL VSISetCryptKey(const GByte *pabyKey, int nKeySize);
|
|
/*! @cond Doxygen_Suppress */
|
|
void CPL_DLL VSICleanupFileManager(void);
|
|
/*! @endcond */
|
|
|
|
bool CPL_DLL VSIDuplicateFileSystemHandler(const char *pszSourceFSName,
|
|
const char *pszNewFSName);
|
|
|
|
VSILFILE CPL_DLL *
|
|
VSIFileFromMemBuffer(const char *pszFilename, GByte *pabyData,
|
|
vsi_l_offset nDataLength,
|
|
int bTakeOwnership) CPL_WARN_UNUSED_RESULT;
|
|
GByte CPL_DLL *VSIGetMemFileBuffer(const char *pszFilename,
|
|
vsi_l_offset *pnDataLength,
|
|
int bUnlinkAndSeize);
|
|
|
|
const char CPL_DLL *VSIMemGenerateHiddenFilename(const char *pszFilename);
|
|
|
|
/** Callback used by VSIStdoutSetRedirection() */
|
|
typedef size_t (*VSIWriteFunction)(const void *ptr, size_t size, size_t nmemb,
|
|
FILE *stream);
|
|
void CPL_DLL VSIStdoutSetRedirection(VSIWriteFunction pFct, FILE *stream);
|
|
|
|
/**
|
|
* Return information about a handle. Optional (driver dependent)
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginStatCallback)(void *pUserData,
|
|
const char *pszFilename,
|
|
VSIStatBufL *pStatBuf,
|
|
int nFlags);
|
|
/**
|
|
* Remove handle by name. Optional
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginUnlinkCallback)(void *pUserData,
|
|
const char *pszFilename);
|
|
/**
|
|
* Rename handle. Optional
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginRenameCallback)(void *pUserData,
|
|
const char *oldpath,
|
|
const char *newpath);
|
|
/**
|
|
* Create Directory. Optional
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginMkdirCallback)(void *pUserData,
|
|
const char *pszDirname,
|
|
long nMode);
|
|
/**
|
|
* Delete Directory. Optional
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginRmdirCallback)(void *pUserData,
|
|
const char *pszDirname);
|
|
/**
|
|
* List directory content. Optional
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef char **(*VSIFilesystemPluginReadDirCallback)(void *pUserData,
|
|
const char *pszDirname,
|
|
int nMaxFiles);
|
|
/**
|
|
* List related files. Must return NULL if unknown, or a list of relative
|
|
* filenames that can be opened along the main file. If no other file than
|
|
* pszFilename needs to be opened, return static_cast<char**>
|
|
* (CPLCalloc(1,sizeof(char*)));
|
|
*
|
|
* Optional
|
|
* @since GDAL 3.2
|
|
*/
|
|
typedef char **(*VSIFilesystemPluginSiblingFilesCallback)(
|
|
void *pUserData, const char *pszDirname);
|
|
/**
|
|
* Open a handle. Mandatory. Returns an opaque pointer that will be used in
|
|
* subsequent file I/O calls. Should return null and/or set errno if the handle
|
|
* does not exist or the access mode is incorrect.
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef void *(*VSIFilesystemPluginOpenCallback)(void *pUserData,
|
|
const char *pszFilename,
|
|
const char *pszAccess);
|
|
/**
|
|
* Return current position in handle. Mandatory
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef vsi_l_offset (*VSIFilesystemPluginTellCallback)(void *pFile);
|
|
/**
|
|
* Seek to position in handle. Mandatory except for write only handles
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginSeekCallback)(void *pFile,
|
|
vsi_l_offset nOffset,
|
|
int nWhence);
|
|
/**
|
|
* Read data from current position, returns the number of blocks correctly read.
|
|
* Mandatory except for write only handles
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef size_t (*VSIFilesystemPluginReadCallback)(void *pFile, void *pBuffer,
|
|
size_t nSize, size_t nCount);
|
|
/**
|
|
* Read from multiple offsets. Optional, will be replaced by multiple calls to
|
|
* Read() if not provided
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginReadMultiRangeCallback)(
|
|
void *pFile, int nRanges, void **ppData, const vsi_l_offset *panOffsets,
|
|
const size_t *panSizes);
|
|
/**
|
|
* Get empty ranges. Optional
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef VSIRangeStatus (*VSIFilesystemPluginGetRangeStatusCallback)(
|
|
void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength);
|
|
/**
|
|
* Has end of file been reached. Mandatory? for read handles.
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginEofCallback)(void *pFile);
|
|
/**
|
|
* Write bytes at current offset. Mandatory for writable handles
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef size_t (*VSIFilesystemPluginWriteCallback)(void *pFile,
|
|
const void *pBuffer,
|
|
size_t nSize, size_t nCount);
|
|
/**
|
|
* Sync written bytes. Optional
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginFlushCallback)(void *pFile);
|
|
/**
|
|
* Truncate handle. Mandatory (driver dependent?) for write handles
|
|
*/
|
|
typedef int (*VSIFilesystemPluginTruncateCallback)(void *pFile,
|
|
vsi_l_offset nNewSize);
|
|
/**
|
|
* Close file handle. Optional
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef int (*VSIFilesystemPluginCloseCallback)(void *pFile);
|
|
|
|
/**
|
|
* This optional 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.
|
|
*
|
|
* @param pFile File handle.
|
|
* @param nRanges Size of the panOffsets and panSizes arrays.
|
|
* @param panOffsets Array containing the start offset of each range.
|
|
* @param panSizes Array containing the size (in bytes) of each range.
|
|
* @since GDAL 3.7
|
|
*/
|
|
typedef void (*VSIFilesystemPluginAdviseReadCallback)(
|
|
void *pFile, int nRanges, const vsi_l_offset *panOffsets,
|
|
const size_t *panSizes);
|
|
|
|
/**
|
|
* Has a read error (non end-of-file related) has occurred?
|
|
* @since GDAL 3.10
|
|
*/
|
|
typedef int (*VSIFilesystemPluginErrorCallback)(void *pFile);
|
|
|
|
/**
|
|
* Clear error and end-of-file flags.
|
|
* @since GDAL 3.10
|
|
*/
|
|
typedef void (*VSIFilesystemPluginClearErrCallback)(void *pFile);
|
|
|
|
/**
|
|
* struct containing callbacks to used by the handler.
|
|
* (rw), (r), (w) or () at the end indicate whether the given callback is
|
|
* mandatory for reading and or writing handlers. A (?) indicates that the
|
|
* callback might be mandatory for certain drivers only.
|
|
* @since GDAL 3.0
|
|
*/
|
|
typedef struct
|
|
{
|
|
/**
|
|
* Optional opaque pointer passed back to filemanager callbacks (e.g. open,
|
|
* stat, rmdir)
|
|
*/
|
|
void *pUserData;
|
|
VSIFilesystemPluginStatCallback stat; /**< stat handle by name (rw)*/
|
|
VSIFilesystemPluginUnlinkCallback unlink; /**< unlink handle by name ()*/
|
|
VSIFilesystemPluginRenameCallback rename; /**< rename handle ()*/
|
|
VSIFilesystemPluginMkdirCallback mkdir; /**< make directory ()*/
|
|
VSIFilesystemPluginRmdirCallback rmdir; /**< remove directory ()*/
|
|
VSIFilesystemPluginReadDirCallback
|
|
read_dir; /**< list directory content (r?)*/
|
|
VSIFilesystemPluginOpenCallback open; /**< open handle by name (rw) */
|
|
VSIFilesystemPluginTellCallback
|
|
tell; /**< get current position of handle (rw) */
|
|
VSIFilesystemPluginSeekCallback
|
|
seek; /**< set current position of handle (rw) */
|
|
VSIFilesystemPluginReadCallback read; /**< read from current position (r) */
|
|
VSIFilesystemPluginReadMultiRangeCallback
|
|
read_multi_range; /**< read multiple blocks ()*/
|
|
VSIFilesystemPluginGetRangeStatusCallback
|
|
get_range_status; /**< get range status () */
|
|
VSIFilesystemPluginEofCallback
|
|
eof; /**< has end of file been reached (r?) */
|
|
VSIFilesystemPluginWriteCallback
|
|
write; /**< write bytes to current position (w) */
|
|
VSIFilesystemPluginFlushCallback flush; /**< sync bytes (w) */
|
|
VSIFilesystemPluginTruncateCallback truncate; /**< truncate handle (w?) */
|
|
VSIFilesystemPluginCloseCallback close; /**< close handle (rw) */
|
|
size_t nBufferSize; /**< buffer small reads (makes handler read only) */
|
|
size_t nCacheSize; /**< max mem to use per file when buffering */
|
|
VSIFilesystemPluginSiblingFilesCallback
|
|
sibling_files; /**< list related files*/
|
|
|
|
/** The following optional member has been added in GDAL 3.7: */
|
|
VSIFilesystemPluginAdviseReadCallback advise_read; /**< AdviseRead() */
|
|
|
|
VSIFilesystemPluginErrorCallback error; /**< has read error occurred (r) */
|
|
VSIFilesystemPluginClearErrCallback clear_err; /**< clear error flags(r) */
|
|
/*
|
|
Callbacks are defined as a struct allocated by a call to
|
|
VSIAllocFilesystemPluginCallbacksStruct in order to try to maintain ABI
|
|
stability when eventually adding a new member. Any callbacks added to
|
|
this struct SHOULD be added to the END of this struct
|
|
*/
|
|
} VSIFilesystemPluginCallbacksStruct;
|
|
|
|
/**
|
|
* return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with
|
|
* handler callbacks
|
|
* @since GDAL 3.0
|
|
*/
|
|
VSIFilesystemPluginCallbacksStruct CPL_DLL *
|
|
VSIAllocFilesystemPluginCallbacksStruct(void);
|
|
|
|
/**
|
|
* free resources allocated by VSIAllocFilesystemPluginCallbacksStruct
|
|
* @since GDAL 3.0
|
|
*/
|
|
void CPL_DLL VSIFreeFilesystemPluginCallbacksStruct(
|
|
VSIFilesystemPluginCallbacksStruct *poCb);
|
|
|
|
/**
|
|
* register a handler on the given prefix. All IO on datasets opened with the
|
|
* filename /prefix/xxxxxx will go through these callbacks. pszPrefix must begin
|
|
* and end with a '/'
|
|
* @since GDAL 3.0
|
|
*/
|
|
int CPL_DLL VSIInstallPluginHandler(
|
|
const char *pszPrefix, const VSIFilesystemPluginCallbacksStruct *poCb);
|
|
|
|
/**
|
|
* Unregister a handler previously installed with VSIInstallPluginHandler() on
|
|
* the given prefix.
|
|
* Note: it is generally unsafe to remove a handler while there are still file
|
|
* handles opened that are managed by that handler. It is the responsibility of
|
|
* the caller to ensure that it calls this function in a situation where it is
|
|
* safe to do so.
|
|
* @since GDAL 3.9
|
|
*/
|
|
int CPL_DLL VSIRemovePluginHandler(const char *pszPrefix);
|
|
|
|
/* ==================================================================== */
|
|
/* Time querying. */
|
|
/* ==================================================================== */
|
|
|
|
/*! @cond Doxygen_Suppress */
|
|
unsigned long CPL_DLL VSITime(unsigned long *);
|
|
const char CPL_DLL *VSICTime(unsigned long);
|
|
struct tm CPL_DLL *VSIGMTime(const time_t *pnTime, struct tm *poBrokenTime);
|
|
struct tm CPL_DLL *VSILocalTime(const time_t *pnTime, struct tm *poBrokenTime);
|
|
/*! @endcond */
|
|
|
|
/*! @cond Doxygen_Suppress */
|
|
/* -------------------------------------------------------------------- */
|
|
/* the following can be turned on for detailed logging of */
|
|
/* almost all IO calls. */
|
|
/* -------------------------------------------------------------------- */
|
|
#ifdef VSI_DEBUG
|
|
|
|
#ifndef DEBUG
|
|
#define DEBUG
|
|
#endif
|
|
|
|
#include "cpl_error.h"
|
|
|
|
#define VSIDebug4(f, a1, a2, a3, a4) CPLDebug("VSI", f, a1, a2, a3, a4);
|
|
#define VSIDebug3(f, a1, a2, a3) CPLDebug("VSI", f, a1, a2, a3);
|
|
#define VSIDebug2(f, a1, a2) CPLDebug("VSI", f, a1, a2);
|
|
#define VSIDebug1(f, a1) CPLDebug("VSI", f, a1);
|
|
#else
|
|
#define VSIDebug4(f, a1, a2, a3, a4) \
|
|
{ \
|
|
}
|
|
#define VSIDebug3(f, a1, a2, a3) \
|
|
{ \
|
|
}
|
|
#define VSIDebug2(f, a1, a2) \
|
|
{ \
|
|
}
|
|
#define VSIDebug1(f, a1) \
|
|
{ \
|
|
}
|
|
#endif
|
|
/*! @endcond */
|
|
|
|
CPL_C_END
|
|
|
|
#endif /* ndef CPL_VSI_H_INCLUDED */
|