cpl_vsi.h

Go to the documentation of this file.

/******************************************************************************
 *
 * 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>
 
#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
extern "C++"
{
#include <string>
}
#endif

 
/* -------------------------------------------------------------------- */
/*      We need access to ``struct stat''.                              */
/* -------------------------------------------------------------------- */
 
/* Unix */
#if !defined(_WIN32)
#include <unistd.h>
#endif
 
/* Windows */
#include <sys/stat.h>
 
CPL_C_START

#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
 
/* ==================================================================== */
/*      stdio file access functions.  These do not support large       */
/*      files, and do not go through the virtualization API.           */
/* ==================================================================== */

 
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;

 
/* ==================================================================== */
/*      VSIStat() related.                                              */
/* ==================================================================== */

typedef struct stat VSIStatBuf;
int CPL_DLL VSIStat(const char *, VSIStatBuf *) CPL_WARN_UNUSED_RESULT;
 
#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
#define VSI_ISLNK(x) S_ISLNK(x)
#define VSI_ISREG(x) S_ISREG(x)
#define VSI_ISDIR(x) S_ISDIR(x)
#define VSI_ISCHR(x) S_ISCHR(x)
#define VSI_ISBLK(x) S_ISBLK(x)
#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.                      */
/* ==================================================================== */

typedef GUIntBig vsi_l_offset;
#define VSI_L_OFFSET_MAX GUINTBIG_MAX

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;

typedef enum
{
    VSI_RANGE_STATUS_UNKNOWN, 
    VSI_RANGE_STATUS_DATA,    
    VSI_RANGE_STATUS_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)
typedef struct VSI_STAT64_T VSIStatBufL;
#else
#define VSIStatBufL VSIStatBuf
#endif
 
int CPL_DLL VSIStatL(const char *, VSIStatBufL *) CPL_WARN_UNUSED_RESULT;

#define VSI_STAT_EXISTS_FLAG 0x1
#define VSI_STAT_NATURE_FLAG 0x2
#define VSI_STAT_SIZE_FLAG 0x4
#define VSI_STAT_SET_ERROR_FLAG 0x8
#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)
    CPL_WARN_DEPRECATED("Use VSISetPathSpecificOption instead")
    ;
void CPL_DLL VSIClearCredentials(const char *pszPathPrefix)
    CPL_WARN_DEPRECATED("Use VSIClearPathSpecificOptions instead")
    ;
const char CPL_DLL *VSIGetCredential(const char *pszPath, const char *pszKey,
                                     const char *pszDefault)
    CPL_WARN_DEPRECATED("Use VSIGetPathSpecificOption instead")
    ;
 
/* ==================================================================== */
/*      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++"
{
    struct CPL_DLL VSIFreeReleaser
    {
        void operator()(void *p) const
        {
            VSIFree(p);
        }
    };

}
#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;
#define VSI_MALLOC_ALIGNED_AUTO_VERBOSE(size)                                  \
    VSIMallocAlignedAutoVerbose(size, __FILE__, __LINE__)

void CPL_DLL *VSIMalloc2(size_t nSize1, size_t nSize2) CPL_WARN_UNUSED_RESULT;

void CPL_DLL *VSIMalloc3(size_t nSize1, size_t nSize2,
                         size_t nSize3) CPL_WARN_UNUSED_RESULT;

void CPL_DLL *VSIMallocVerbose(size_t nSize, const char *pszFile,
                               int nLine) CPL_WARN_UNUSED_RESULT;
#define VSI_MALLOC_VERBOSE(size) VSIMallocVerbose(size, __FILE__, __LINE__)

void CPL_DLL *VSIMalloc2Verbose(size_t nSize1, size_t nSize2,
                                const char *pszFile,
                                int nLine) CPL_WARN_UNUSED_RESULT;
#define VSI_MALLOC2_VERBOSE(nSize1, nSize2)                                    \
    VSIMalloc2Verbose(nSize1, nSize2, __FILE__, __LINE__)

void CPL_DLL *VSIMalloc3Verbose(size_t nSize1, size_t nSize2, size_t nSize3,
                                const char *pszFile,
                                int nLine) CPL_WARN_UNUSED_RESULT;
#define VSI_MALLOC3_VERBOSE(nSize1, nSize2, nSize3)                            \
    VSIMalloc3Verbose(nSize1, nSize2, nSize3, __FILE__, __LINE__)

void CPL_DLL *VSICallocVerbose(size_t nCount, size_t nSize, const char *pszFile,
                               int nLine) CPL_WARN_UNUSED_RESULT;
#define VSI_CALLOC_VERBOSE(nCount, nSize)                                      \
    VSICallocVerbose(nCount, nSize, __FILE__, __LINE__)

void CPL_DLL *VSIReallocVerbose(void *pOldPtr, size_t nNewSize,
                                const char *pszFile,
                                int nLine) CPL_WARN_UNUSED_RESULT;
#define VSI_REALLOC_VERBOSE(pOldPtr, nNewSize)                                 \
    VSIReallocVerbose(pOldPtr, nNewSize, __FILE__, __LINE__)

char CPL_DLL *VSIStrdupVerbose(const char *pszStr, const char *pszFile,
                               int nLine) CPL_WARN_UNUSED_RESULT;
#define VSI_STRDUP_VERBOSE(pszStr) VSIStrdupVerbose(pszStr, __FILE__, __LINE__)
 
GIntBig CPL_DLL CPLGetPhysicalRAM(void);
GIntBig CPL_DLL CPLGetUsablePhysicalRAM(void);
 
/* ==================================================================== */
/*      Other...                                                        */
/* ==================================================================== */

#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);
char CPL_DLL **VSIGlob(const char *pszPattern, const char *const *papszOptions,
                       GDALProgressFunc pProgressFunc, void *pProgressData);
 
const char CPL_DLL *VSIGetDirectorySeparator(const char *pszPath);

typedef struct VSIDIR VSIDIR;
 
VSIDIR CPL_DLL *VSIOpenDir(const char *pszPath, int nRecurseDepth,
                           const char *const *papszOptions);

typedef struct VSIDIREntry VSIDIREntry;


struct VSIDIREntry
{
    char *pszName;
    int nMode;
    vsi_l_offset nSize;
    GIntBig nMTime;
    char bModeKnown;
    char bSizeKnown;
    char bMTimeKnown;
    char **papszExtra;
 
#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
    VSIDIREntry();
    ~VSIDIREntry();
    VSIDIREntry(const VSIDIREntry &);
    VSIDIREntry &operator=(VSIDIREntry &) = delete;
#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 VSIMove(const char *oldpath, const char *newpath,
                    const char *const *papszOptions,
                    GDALProgressFunc pProgressFunc, void *pProgressData);
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);
 
#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
extern "C++"
{
    std::string CPL_DLL VSIURIToVSIPath(const std::string &osURI);
}
#endif
 
/* ==================================================================== */
/*      Install special file access handlers.                           */
/* ==================================================================== */
void CPL_DLL VSIInstallMemFileHandler(void);
void CPL_DLL VSIInstallLargeFileHandler(void);
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);
void CPL_DLL VSICleanupFileManager(void);
 
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);

typedef size_t (*VSIWriteFunction)(const void *ptr, size_t size, size_t nmemb,
                                   FILE *stream);
void CPL_DLL VSIStdoutSetRedirection(VSIWriteFunction pFct, FILE *stream);

typedef int (*VSIFilesystemPluginStatCallback)(void *pUserData,
                                               const char *pszFilename,
                                               VSIStatBufL *pStatBuf,
                                               int nFlags);
typedef int (*VSIFilesystemPluginUnlinkCallback)(void *pUserData,
                                                 const char *pszFilename);
typedef int (*VSIFilesystemPluginRenameCallback)(void *pUserData,
                                                 const char *oldpath,
                                                 const char *newpath);
typedef int (*VSIFilesystemPluginMkdirCallback)(void *pUserData,
                                                const char *pszDirname,
                                                long nMode);
typedef int (*VSIFilesystemPluginRmdirCallback)(void *pUserData,
                                                const char *pszDirname);
typedef char **(*VSIFilesystemPluginReadDirCallback)(void *pUserData,
                                                     const char *pszDirname,
                                                     int nMaxFiles);
typedef char **(*VSIFilesystemPluginSiblingFilesCallback)(
    void *pUserData, const char *pszDirname);
typedef void *(*VSIFilesystemPluginOpenCallback)(void *pUserData,
                                                 const char *pszFilename,
                                                 const char *pszAccess);
typedef vsi_l_offset (*VSIFilesystemPluginTellCallback)(void *pFile);
typedef int (*VSIFilesystemPluginSeekCallback)(void *pFile,
                                               vsi_l_offset nOffset,
                                               int nWhence);
typedef size_t (*VSIFilesystemPluginReadCallback)(void *pFile, void *pBuffer,
                                                  size_t nSize, size_t nCount);
typedef int (*VSIFilesystemPluginReadMultiRangeCallback)(
    void *pFile, int nRanges, void **ppData, const vsi_l_offset *panOffsets,
    const size_t *panSizes);
typedef VSIRangeStatus (*VSIFilesystemPluginGetRangeStatusCallback)(
    void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength);
typedef int (*VSIFilesystemPluginEofCallback)(void *pFile);
typedef size_t (*VSIFilesystemPluginWriteCallback)(void *pFile,
                                                   const void *pBuffer,
                                                   size_t nSize, size_t nCount);
typedef int (*VSIFilesystemPluginFlushCallback)(void *pFile);
typedef int (*VSIFilesystemPluginTruncateCallback)(void *pFile,
                                                   vsi_l_offset nNewSize);
typedef int (*VSIFilesystemPluginCloseCallback)(void *pFile);

typedef void (*VSIFilesystemPluginAdviseReadCallback)(
    void *pFile, int nRanges, const vsi_l_offset *panOffsets,
    const size_t *panSizes);

typedef int (*VSIFilesystemPluginErrorCallback)(void *pFile);

typedef void (*VSIFilesystemPluginClearErrCallback)(void *pFile);

typedef struct
{
    void *pUserData;
    VSIFilesystemPluginStatCallback stat;     
    VSIFilesystemPluginUnlinkCallback unlink; 
    VSIFilesystemPluginRenameCallback rename; 
    VSIFilesystemPluginMkdirCallback mkdir;   
    VSIFilesystemPluginRmdirCallback rmdir;   
    VSIFilesystemPluginReadDirCallback
        read_dir;                         
    VSIFilesystemPluginOpenCallback open; 
    VSIFilesystemPluginTellCallback
        tell; 
    VSIFilesystemPluginSeekCallback
        seek; 
    VSIFilesystemPluginReadCallback read; 
    VSIFilesystemPluginReadMultiRangeCallback
        read_multi_range; 
    VSIFilesystemPluginGetRangeStatusCallback
        get_range_status; 
    VSIFilesystemPluginEofCallback
        eof; 
    VSIFilesystemPluginWriteCallback
        write; 
    VSIFilesystemPluginFlushCallback flush;       
    VSIFilesystemPluginTruncateCallback truncate; 
    VSIFilesystemPluginCloseCallback close;       
    size_t nBufferSize; 
    size_t nCacheSize;  
    VSIFilesystemPluginSiblingFilesCallback
        sibling_files; 

    VSIFilesystemPluginAdviseReadCallback advise_read; 
 
    VSIFilesystemPluginErrorCallback error; 
    VSIFilesystemPluginClearErrCallback clear_err; 
    /*
        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;

VSIFilesystemPluginCallbacksStruct CPL_DLL *
VSIAllocFilesystemPluginCallbacksStruct(void);

void CPL_DLL VSIFreeFilesystemPluginCallbacksStruct(
    VSIFilesystemPluginCallbacksStruct *poCb);

int CPL_DLL VSIInstallPluginHandler(
    const char *pszPrefix, const VSIFilesystemPluginCallbacksStruct *poCb);

int CPL_DLL VSIRemovePluginHandler(const char *pszPrefix);
 
/* ==================================================================== */
/*      Time querying.                                                  */
/* ==================================================================== */

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

/* -------------------------------------------------------------------- */
/*      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
 
CPL_C_END
 
#endif /* ndef CPL_VSI_H_INCLUDED */