Line data Source code
1 : /******************************************************************************
2 : * $Id$
3 : *
4 : * Project: CPL - Common Portability Library
5 : * Author: Frank Warmerdam, warmerdam@pobox.com
6 : * Purpose: Include file defining Virtual File System (VSI) functions, a
7 : * layer over POSIX file and other system services.
8 : *
9 : ******************************************************************************
10 : * Copyright (c) 1998, Frank Warmerdam
11 : * Copyright (c) 2008-2014, Even Rouault <even dot rouault at spatialys.com>
12 : *
13 : * Permission is hereby granted, free of charge, to any person obtaining a
14 : * copy of this software and associated documentation files (the "Software"),
15 : * to deal in the Software without restriction, including without limitation
16 : * the rights to use, copy, modify, merge, publish, distribute, sublicense,
17 : * and/or sell copies of the Software, and to permit persons to whom the
18 : * Software is furnished to do so, subject to the following conditions:
19 : *
20 : * The above copyright notice and this permission notice shall be included
21 : * in all copies or substantial portions of the Software.
22 : *
23 : * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
24 : * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25 : * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
26 : * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27 : * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28 : * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
29 : * DEALINGS IN THE SOFTWARE.
30 : ****************************************************************************/
31 :
32 : #ifndef CPL_VSI_H_INCLUDED
33 : #define CPL_VSI_H_INCLUDED
34 :
35 : #include "cpl_port.h"
36 : #include "cpl_progress.h"
37 :
38 : #include <stdbool.h>
39 :
40 : /**
41 : * \file cpl_vsi.h
42 : *
43 : * Standard C Covers
44 : *
45 : * The VSI functions are intended to be hookable aliases for Standard C
46 : * I/O, memory allocation and other system functions. They are intended
47 : * to allow virtualization of disk I/O so that non file data sources
48 : * can be made to appear as files, and so that additional error trapping
49 : * and reporting can be interested. The memory access API is aliased
50 : * so that special application memory management services can be used.
51 : *
52 : * It is intended that each of these functions retains exactly the same
53 : * calling pattern as the original Standard C functions they relate to.
54 : * This means we don't have to provide custom documentation, and also means
55 : * that the default implementation is very simple.
56 : */
57 :
58 : /* -------------------------------------------------------------------- */
59 : /* We need access to ``struct stat''. */
60 : /* -------------------------------------------------------------------- */
61 :
62 : /* Unix */
63 : #if !defined(_WIN32)
64 : #include <unistd.h>
65 : #endif
66 :
67 : /* Windows */
68 : #include <sys/stat.h>
69 :
70 : CPL_C_START
71 :
72 : /*! @cond Doxygen_Suppress */
73 : #ifdef ENABLE_EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
74 : #define EXPERIMENTAL_CPL_WARN_UNUSED_RESULT CPL_WARN_UNUSED_RESULT
75 : #else
76 : #define EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
77 : #endif
78 : /*! @endcond */
79 :
80 : /* ==================================================================== */
81 : /* stdio file access functions. These do not support large */
82 : /* files, and do not go through the virtualization API. */
83 : /* ==================================================================== */
84 :
85 : /*! @cond Doxygen_Suppress */
86 :
87 : FILE CPL_DLL *VSIFOpen(const char *, const char *) CPL_WARN_UNUSED_RESULT;
88 : int CPL_DLL VSIFClose(FILE *);
89 : int CPL_DLL VSIFSeek(FILE *, long, int) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
90 : long CPL_DLL VSIFTell(FILE *) CPL_WARN_UNUSED_RESULT;
91 : void CPL_DLL VSIRewind(FILE *);
92 : void CPL_DLL VSIFFlush(FILE *);
93 :
94 : size_t CPL_DLL VSIFRead(void *, size_t, size_t,
95 : FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
96 : size_t CPL_DLL VSIFWrite(const void *, size_t, size_t,
97 : FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
98 : char CPL_DLL *VSIFGets(char *, int, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
99 : int CPL_DLL VSIFPuts(const char *, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
100 : int CPL_DLL VSIFPrintf(FILE *, CPL_FORMAT_STRING(const char *),
101 : ...) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
102 : CPL_PRINT_FUNC_FORMAT(2, 3);
103 :
104 : int CPL_DLL VSIFGetc(FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
105 : int CPL_DLL VSIFPutc(int, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
106 : int CPL_DLL VSIUngetc(int, FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
107 : int CPL_DLL VSIFEof(FILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
108 :
109 : /*! @endcond */
110 :
111 : /* ==================================================================== */
112 : /* VSIStat() related. */
113 : /* ==================================================================== */
114 :
115 : /*! @cond Doxygen_Suppress */
116 : typedef struct stat VSIStatBuf;
117 : int CPL_DLL VSIStat(const char *, VSIStatBuf *) CPL_WARN_UNUSED_RESULT;
118 : /*! @endcond */
119 :
120 : #ifdef _WIN32
121 : #define VSI_ISLNK(x) (0) /* N/A on Windows */
122 : #define VSI_ISREG(x) ((x)&S_IFREG)
123 : #define VSI_ISDIR(x) ((x)&S_IFDIR)
124 : #define VSI_ISCHR(x) ((x)&S_IFCHR)
125 : #define VSI_ISBLK(x) (0) /* N/A on Windows */
126 : #else
127 : /** Test if the file is a symbolic link */
128 : #define VSI_ISLNK(x) S_ISLNK(x)
129 : /** Test if the file is a regular file */
130 : #define VSI_ISREG(x) S_ISREG(x)
131 : /** Test if the file is a directory */
132 : #define VSI_ISDIR(x) S_ISDIR(x)
133 : /*! @cond Doxygen_Suppress */
134 : #define VSI_ISCHR(x) S_ISCHR(x)
135 : #define VSI_ISBLK(x) S_ISBLK(x)
136 : /*! @endcond */
137 : #endif
138 :
139 : /* ==================================================================== */
140 : /* 64bit stdio file access functions. If we have a big size */
141 : /* defined, then provide prototypes for the large file API, */
142 : /* otherwise redefine to use the regular api. */
143 : /* ==================================================================== */
144 :
145 : /** Type for a file offset */
146 : typedef GUIntBig vsi_l_offset;
147 : /** Maximum value for a file offset */
148 : #define VSI_L_OFFSET_MAX GUINTBIG_MAX
149 :
150 : /** Opaque type for a FILE that implements the VSIVirtualHandle API */
151 : typedef struct VSIVirtualHandle VSILFILE;
152 :
153 : VSILFILE CPL_DLL *VSIFOpenL(const char *, const char *) CPL_WARN_UNUSED_RESULT;
154 : VSILFILE CPL_DLL *VSIFOpenExL(const char *, const char *,
155 : int) CPL_WARN_UNUSED_RESULT;
156 : VSILFILE CPL_DLL *VSIFOpenEx2L(const char *, const char *, int,
157 : CSLConstList) CPL_WARN_UNUSED_RESULT;
158 : int CPL_DLL VSIFCloseL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
159 : int CPL_DLL VSIFSeekL(VSILFILE *, vsi_l_offset,
160 : int) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
161 : vsi_l_offset CPL_DLL VSIFTellL(VSILFILE *) CPL_WARN_UNUSED_RESULT;
162 : void CPL_DLL VSIRewindL(VSILFILE *);
163 : size_t CPL_DLL VSIFReadL(void *, size_t, size_t,
164 : VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
165 : int CPL_DLL VSIFReadMultiRangeL(int nRanges, void **ppData,
166 : const vsi_l_offset *panOffsets,
167 : const size_t *panSizes,
168 : VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
169 : size_t CPL_DLL VSIFWriteL(const void *, size_t, size_t,
170 : VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
171 : int CPL_DLL VSIFEofL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
172 : int CPL_DLL VSIFTruncateL(VSILFILE *,
173 : vsi_l_offset) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
174 : int CPL_DLL VSIFFlushL(VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
175 : int CPL_DLL VSIFPrintfL(VSILFILE *, CPL_FORMAT_STRING(const char *),
176 : ...) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT
177 : CPL_PRINT_FUNC_FORMAT(2, 3);
178 : int CPL_DLL VSIFPutcL(int, VSILFILE *) EXPERIMENTAL_CPL_WARN_UNUSED_RESULT;
179 :
180 : /** Range status */
181 : typedef enum
182 : {
183 : VSI_RANGE_STATUS_UNKNOWN, /**< Unknown */
184 : VSI_RANGE_STATUS_DATA, /**< Data present */
185 : VSI_RANGE_STATUS_HOLE /**< Hole */
186 : } VSIRangeStatus;
187 :
188 : VSIRangeStatus CPL_DLL VSIFGetRangeStatusL(VSILFILE *fp, vsi_l_offset nStart,
189 : vsi_l_offset nLength);
190 :
191 : int CPL_DLL VSIIngestFile(VSILFILE *fp, const char *pszFilename,
192 : GByte **ppabyRet, vsi_l_offset *pnSize,
193 : GIntBig nMaxSize) CPL_WARN_UNUSED_RESULT;
194 :
195 : int CPL_DLL VSIOverwriteFile(VSILFILE *fpTarget, const char *pszSourceFilename)
196 : CPL_WARN_UNUSED_RESULT;
197 :
198 : #if defined(VSI_STAT64_T)
199 : /** Type for VSIStatL() */
200 : typedef struct VSI_STAT64_T VSIStatBufL;
201 : #else
202 : /** Type for VSIStatL() */
203 : #define VSIStatBufL VSIStatBuf
204 : #endif
205 :
206 : int CPL_DLL VSIStatL(const char *, VSIStatBufL *) CPL_WARN_UNUSED_RESULT;
207 :
208 : /** Flag provided to VSIStatExL() to test if the file exists */
209 : #define VSI_STAT_EXISTS_FLAG 0x1
210 : /** Flag provided to VSIStatExL() to query the nature (file/dir) of the file */
211 : #define VSI_STAT_NATURE_FLAG 0x2
212 : /** Flag provided to VSIStatExL() to query the file size */
213 : #define VSI_STAT_SIZE_FLAG 0x4
214 : /** Flag provided to VSIStatExL() to issue a VSIError in case of failure */
215 : #define VSI_STAT_SET_ERROR_FLAG 0x8
216 : /** Flag provided to VSIStatExL() to only use already cached results.
217 : * @since GDAL 3.4
218 : */
219 : #define VSI_STAT_CACHE_ONLY 0x10
220 :
221 : int CPL_DLL VSIStatExL(const char *pszFilename, VSIStatBufL *psStatBuf,
222 : int nFlags) CPL_WARN_UNUSED_RESULT;
223 :
224 : int CPL_DLL VSIIsCaseSensitiveFS(const char *pszFilename);
225 :
226 : int CPL_DLL VSISupportsSparseFiles(const char *pszPath);
227 :
228 : bool CPL_DLL VSIIsLocal(const char *pszPath);
229 :
230 : char CPL_DLL *VSIGetCanonicalFilename(const char *pszPath);
231 :
232 : bool CPL_DLL VSISupportsSequentialWrite(const char *pszPath,
233 : bool bAllowLocalTempFile);
234 :
235 : bool CPL_DLL VSISupportsRandomWrite(const char *pszPath,
236 : bool bAllowLocalTempFile);
237 :
238 : int CPL_DLL VSIHasOptimizedReadMultiRange(const char *pszPath);
239 :
240 : const char CPL_DLL *VSIGetActualURL(const char *pszFilename);
241 :
242 : char CPL_DLL *VSIGetSignedURL(const char *pszFilename,
243 : CSLConstList papszOptions);
244 :
245 : const char CPL_DLL *VSIGetFileSystemOptions(const char *pszFilename);
246 :
247 : char CPL_DLL **VSIGetFileSystemsPrefixes(void);
248 :
249 : void CPL_DLL *VSIFGetNativeFileDescriptorL(VSILFILE *);
250 :
251 : char CPL_DLL **
252 : VSIGetFileMetadata(const char *pszFilename, const char *pszDomain,
253 : CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
254 :
255 : int CPL_DLL VSISetFileMetadata(const char *pszFilename,
256 : CSLConstList papszMetadata,
257 : const char *pszDomain,
258 : CSLConstList papszOptions);
259 :
260 : void CPL_DLL VSISetPathSpecificOption(const char *pszPathPrefix,
261 : const char *pszKey, const char *pszValue);
262 : void CPL_DLL VSIClearPathSpecificOptions(const char *pszPathPrefix);
263 : const char CPL_DLL *VSIGetPathSpecificOption(const char *pszPath,
264 : const char *pszKey,
265 : const char *pszDefault);
266 :
267 : void CPL_DLL VSISetCredential(const char *pszPathPrefix, const char *pszKey,
268 : const char *pszValue)
269 : /*! @cond Doxygen_Suppress */
270 : CPL_WARN_DEPRECATED("Use VSISetPathSpecificOption instead")
271 : /*! @endcond */
272 : ;
273 : void CPL_DLL VSIClearCredentials(const char *pszPathPrefix)
274 : /*! @cond Doxygen_Suppress */
275 : CPL_WARN_DEPRECATED("Use VSIClearPathSpecificOptions instead")
276 : /*! @endcond */
277 : ;
278 : const char CPL_DLL *VSIGetCredential(const char *pszPath, const char *pszKey,
279 : const char *pszDefault)
280 : /*! @cond Doxygen_Suppress */
281 : CPL_WARN_DEPRECATED("Use VSIGetPathSpecificOption instead")
282 : /*! @endcond */
283 : ;
284 :
285 : /* ==================================================================== */
286 : /* Memory allocation */
287 : /* ==================================================================== */
288 :
289 : void CPL_DLL *VSICalloc(size_t, size_t) CPL_WARN_UNUSED_RESULT;
290 : void CPL_DLL *VSIMalloc(size_t) CPL_WARN_UNUSED_RESULT;
291 : void CPL_DLL VSIFree(void *);
292 : void CPL_DLL *VSIRealloc(void *, size_t) CPL_WARN_UNUSED_RESULT;
293 : char CPL_DLL *VSIStrdup(const char *) CPL_WARN_UNUSED_RESULT;
294 :
295 : #if defined(__cplusplus) && defined(GDAL_COMPILATION)
296 : extern "C++"
297 : {
298 : /*! @cond Doxygen_Suppress */
299 : struct CPL_DLL VSIFreeReleaser
300 : {
301 1429 : void operator()(void *p) const
302 : {
303 1429 : VSIFree(p);
304 1429 : }
305 : };
306 :
307 : /*! @endcond */
308 : }
309 : #endif
310 :
311 : void CPL_DLL *VSIMallocAligned(size_t nAlignment,
312 : size_t nSize) CPL_WARN_UNUSED_RESULT;
313 : void CPL_DLL *VSIMallocAlignedAuto(size_t nSize) CPL_WARN_UNUSED_RESULT;
314 : void CPL_DLL VSIFreeAligned(void *ptr);
315 :
316 : void CPL_DLL *VSIMallocAlignedAutoVerbose(size_t nSize, const char *pszFile,
317 : int nLine) CPL_WARN_UNUSED_RESULT;
318 : /** VSIMallocAlignedAutoVerbose() with FILE and LINE reporting */
319 : #define VSI_MALLOC_ALIGNED_AUTO_VERBOSE(size) \
320 : VSIMallocAlignedAutoVerbose(size, __FILE__, __LINE__)
321 :
322 : /**
323 : VSIMalloc2 allocates (nSize1 * nSize2) bytes.
324 : In case of overflow of the multiplication, or if memory allocation fails, a
325 : NULL pointer is returned and a CE_Failure error is raised with CPLError().
326 : If nSize1 == 0 || nSize2 == 0, a NULL pointer will also be returned.
327 : CPLFree() or VSIFree() can be used to free memory allocated by this function.
328 : */
329 : void CPL_DLL *VSIMalloc2(size_t nSize1, size_t nSize2) CPL_WARN_UNUSED_RESULT;
330 :
331 : /**
332 : VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes.
333 : In case of overflow of the multiplication, or if memory allocation fails, a
334 : NULL pointer is returned and a CE_Failure error is raised with CPLError().
335 : If nSize1 == 0 || nSize2 == 0 || nSize3 == 0, a NULL pointer will also be
336 : returned. CPLFree() or VSIFree() can be used to free memory allocated by this
337 : function.
338 : */
339 : void CPL_DLL *VSIMalloc3(size_t nSize1, size_t nSize2,
340 : size_t nSize3) CPL_WARN_UNUSED_RESULT;
341 :
342 : /** VSIMallocVerbose */
343 : void CPL_DLL *VSIMallocVerbose(size_t nSize, const char *pszFile,
344 : int nLine) CPL_WARN_UNUSED_RESULT;
345 : /** VSI_MALLOC_VERBOSE */
346 : #define VSI_MALLOC_VERBOSE(size) VSIMallocVerbose(size, __FILE__, __LINE__)
347 :
348 : /** VSIMalloc2Verbose */
349 : void CPL_DLL *VSIMalloc2Verbose(size_t nSize1, size_t nSize2,
350 : const char *pszFile,
351 : int nLine) CPL_WARN_UNUSED_RESULT;
352 : /** VSI_MALLOC2_VERBOSE */
353 : #define VSI_MALLOC2_VERBOSE(nSize1, nSize2) \
354 : VSIMalloc2Verbose(nSize1, nSize2, __FILE__, __LINE__)
355 :
356 : /** VSIMalloc3Verbose */
357 : void CPL_DLL *VSIMalloc3Verbose(size_t nSize1, size_t nSize2, size_t nSize3,
358 : const char *pszFile,
359 : int nLine) CPL_WARN_UNUSED_RESULT;
360 : /** VSI_MALLOC3_VERBOSE */
361 : #define VSI_MALLOC3_VERBOSE(nSize1, nSize2, nSize3) \
362 : VSIMalloc3Verbose(nSize1, nSize2, nSize3, __FILE__, __LINE__)
363 :
364 : /** VSICallocVerbose */
365 : void CPL_DLL *VSICallocVerbose(size_t nCount, size_t nSize, const char *pszFile,
366 : int nLine) CPL_WARN_UNUSED_RESULT;
367 : /** VSI_CALLOC_VERBOSE */
368 : #define VSI_CALLOC_VERBOSE(nCount, nSize) \
369 : VSICallocVerbose(nCount, nSize, __FILE__, __LINE__)
370 :
371 : /** VSIReallocVerbose */
372 : void CPL_DLL *VSIReallocVerbose(void *pOldPtr, size_t nNewSize,
373 : const char *pszFile,
374 : int nLine) CPL_WARN_UNUSED_RESULT;
375 : /** VSI_REALLOC_VERBOSE */
376 : #define VSI_REALLOC_VERBOSE(pOldPtr, nNewSize) \
377 : VSIReallocVerbose(pOldPtr, nNewSize, __FILE__, __LINE__)
378 :
379 : /** VSIStrdupVerbose */
380 : char CPL_DLL *VSIStrdupVerbose(const char *pszStr, const char *pszFile,
381 : int nLine) CPL_WARN_UNUSED_RESULT;
382 : /** VSI_STRDUP_VERBOSE */
383 : #define VSI_STRDUP_VERBOSE(pszStr) VSIStrdupVerbose(pszStr, __FILE__, __LINE__)
384 :
385 : GIntBig CPL_DLL CPLGetPhysicalRAM(void);
386 : GIntBig CPL_DLL CPLGetUsablePhysicalRAM(void);
387 :
388 : /* ==================================================================== */
389 : /* Other... */
390 : /* ==================================================================== */
391 :
392 : /** Alias of VSIReadDir() */
393 : #define CPLReadDir VSIReadDir
394 : char CPL_DLL **VSIReadDir(const char *);
395 : char CPL_DLL **VSIReadDirRecursive(const char *pszPath);
396 : char CPL_DLL **VSIReadDirEx(const char *pszPath, int nMaxFiles);
397 : char CPL_DLL **VSISiblingFiles(const char *pszPath);
398 :
399 : const char CPL_DLL *VSIGetDirectorySeparator(const char *pszPath);
400 :
401 : /** Opaque type for a directory iterator */
402 : typedef struct VSIDIR VSIDIR;
403 :
404 : VSIDIR CPL_DLL *VSIOpenDir(const char *pszPath, int nRecurseDepth,
405 : const char *const *papszOptions);
406 :
407 : /*! @cond Doxygen_Suppress */
408 : typedef struct VSIDIREntry VSIDIREntry;
409 :
410 : /*! @endcond */
411 :
412 : /** Directory entry. */
413 : struct VSIDIREntry
414 : {
415 : /** Filename */
416 : char *pszName;
417 : /** File mode. See VSI_ISREG() / VSI_ISDIR() */
418 : int nMode;
419 : /** File size */
420 : vsi_l_offset nSize;
421 : /** Last modification time (seconds since 1970/01/01) */
422 : GIntBig nMTime;
423 : /** Whether nMode is known: 0 = unknown, 1 = known. */
424 : char bModeKnown;
425 : /** Whether nSize is known: 0 = unknown, 1 = known. */
426 : char bSizeKnown;
427 : /** Whether nMTime is known: 0 = unknown, 1 = known. */
428 : char bMTimeKnown;
429 : /** NULL-terminated list of extra properties. */
430 : char **papszExtra;
431 :
432 : #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
433 : /*! @cond Doxygen_Suppress */
434 : VSIDIREntry();
435 : ~VSIDIREntry();
436 : VSIDIREntry(const VSIDIREntry &);
437 : VSIDIREntry &operator=(VSIDIREntry &) = delete;
438 : /*! @endcond */
439 : #endif
440 : };
441 :
442 : const VSIDIREntry CPL_DLL *VSIGetNextDirEntry(VSIDIR *dir);
443 : void CPL_DLL VSICloseDir(VSIDIR *dir);
444 :
445 : int CPL_DLL VSIMkdir(const char *pszPathname, long mode);
446 : int CPL_DLL VSIMkdirRecursive(const char *pszPathname, long mode);
447 : int CPL_DLL VSIRmdir(const char *pszDirname);
448 : int CPL_DLL VSIRmdirRecursive(const char *pszDirname);
449 : int CPL_DLL VSIUnlink(const char *pszFilename);
450 : int CPL_DLL *VSIUnlinkBatch(CSLConstList papszFiles);
451 : int CPL_DLL VSIRename(const char *oldpath, const char *newpath);
452 : int CPL_DLL VSICopyFile(const char *pszSource, const char *pszTarget,
453 : VSILFILE *fpSource, vsi_l_offset nSourceSize,
454 : const char *const *papszOptions,
455 : GDALProgressFunc pProgressFunc, void *pProgressData);
456 : int CPL_DLL VSISync(const char *pszSource, const char *pszTarget,
457 : const char *const *papszOptions,
458 : GDALProgressFunc pProgressFunc, void *pProgressData,
459 : char ***ppapszOutputs);
460 : int CPL_DLL VSIAbortPendingUploads(const char *pszFilename);
461 :
462 : char CPL_DLL *VSIStrerror(int);
463 : GIntBig CPL_DLL VSIGetDiskFreeSpace(const char *pszDirname);
464 :
465 : void CPL_DLL VSINetworkStatsReset(void);
466 : char CPL_DLL *VSINetworkStatsGetAsSerializedJSON(char **papszOptions);
467 :
468 : /* ==================================================================== */
469 : /* Install special file access handlers. */
470 : /* ==================================================================== */
471 : void CPL_DLL VSIInstallMemFileHandler(void);
472 : /*! @cond Doxygen_Suppress */
473 : void CPL_DLL VSIInstallLargeFileHandler(void);
474 : /*! @endcond */
475 : void CPL_DLL VSIInstallSubFileHandler(void);
476 : void VSIInstallCurlFileHandler(void);
477 : void CPL_DLL VSICurlClearCache(void);
478 : void CPL_DLL VSICurlPartialClearCache(const char *pszFilenamePrefix);
479 : void VSIInstallCurlStreamingFileHandler(void);
480 : void VSIInstallS3FileHandler(void);
481 : void VSIInstallS3StreamingFileHandler(void);
482 : void VSIInstallGSFileHandler(void);
483 : void VSIInstallGSStreamingFileHandler(void);
484 : void VSIInstallAzureFileHandler(void);
485 : void VSIInstallAzureStreamingFileHandler(void);
486 : void VSIInstallADLSFileHandler(void);
487 : void VSIInstallOSSFileHandler(void);
488 : void VSIInstallOSSStreamingFileHandler(void);
489 : void VSIInstallSwiftFileHandler(void);
490 : void VSIInstallSwiftStreamingFileHandler(void);
491 : void VSIInstall7zFileHandler(void); /* No reason to export that */
492 : void VSIInstallRarFileHandler(void); /* No reason to export that */
493 : void VSIInstallGZipFileHandler(void); /* No reason to export that */
494 : void VSIInstallZipFileHandler(void); /* No reason to export that */
495 : void VSIInstallStdinHandler(void); /* No reason to export that */
496 : void VSIInstallHdfsHandler(void); /* No reason to export that */
497 : void VSIInstallWebHdfsHandler(void); /* No reason to export that */
498 : void VSIInstallStdoutHandler(void); /* No reason to export that */
499 : void CPL_DLL VSIInstallSparseFileHandler(void);
500 : void VSIInstallTarFileHandler(void); /* No reason to export that */
501 : void VSIInstallCachedFileHandler(void); /* No reason to export that */
502 : void CPL_DLL VSIInstallCryptFileHandler(void);
503 : void CPL_DLL VSISetCryptKey(const GByte *pabyKey, int nKeySize);
504 : /*! @cond Doxygen_Suppress */
505 : void CPL_DLL VSICleanupFileManager(void);
506 : /*! @endcond */
507 :
508 : bool CPL_DLL VSIDuplicateFileSystemHandler(const char *pszSourceFSName,
509 : const char *pszNewFSName);
510 :
511 : VSILFILE CPL_DLL *
512 : VSIFileFromMemBuffer(const char *pszFilename, GByte *pabyData,
513 : vsi_l_offset nDataLength,
514 : int bTakeOwnership) CPL_WARN_UNUSED_RESULT;
515 : GByte CPL_DLL *VSIGetMemFileBuffer(const char *pszFilename,
516 : vsi_l_offset *pnDataLength,
517 : int bUnlinkAndSeize);
518 :
519 : /** Callback used by VSIStdoutSetRedirection() */
520 : typedef size_t (*VSIWriteFunction)(const void *ptr, size_t size, size_t nmemb,
521 : FILE *stream);
522 : void CPL_DLL VSIStdoutSetRedirection(VSIWriteFunction pFct, FILE *stream);
523 :
524 : /**
525 : * Return information about a handle. Optional (driver dependent)
526 : * @since GDAL 3.0
527 : */
528 : typedef int (*VSIFilesystemPluginStatCallback)(void *pUserData,
529 : const char *pszFilename,
530 : VSIStatBufL *pStatBuf,
531 : int nFlags);
532 : /**
533 : * Remove handle by name. Optional
534 : * @since GDAL 3.0
535 : */
536 : typedef int (*VSIFilesystemPluginUnlinkCallback)(void *pUserData,
537 : const char *pszFilename);
538 : /**
539 : * Rename handle. Optional
540 : * @since GDAL 3.0
541 : */
542 : typedef int (*VSIFilesystemPluginRenameCallback)(void *pUserData,
543 : const char *oldpath,
544 : const char *newpath);
545 : /**
546 : * Create Directory. Optional
547 : * @since GDAL 3.0
548 : */
549 : typedef int (*VSIFilesystemPluginMkdirCallback)(void *pUserData,
550 : const char *pszDirname,
551 : long nMode);
552 : /**
553 : * Delete Directory. Optional
554 : * @since GDAL 3.0
555 : */
556 : typedef int (*VSIFilesystemPluginRmdirCallback)(void *pUserData,
557 : const char *pszDirname);
558 : /**
559 : * List directory content. Optional
560 : * @since GDAL 3.0
561 : */
562 : typedef char **(*VSIFilesystemPluginReadDirCallback)(void *pUserData,
563 : const char *pszDirname,
564 : int nMaxFiles);
565 : /**
566 : * List related files. Must return NULL if unknown, or a list of relative
567 : * filenames that can be opened along the main file. If no other file than
568 : * pszFilename needs to be opened, return static_cast<char**>
569 : * (CPLCalloc(1,sizeof(char*)));
570 : *
571 : * Optional
572 : * @since GDAL 3.2
573 : */
574 : typedef char **(*VSIFilesystemPluginSiblingFilesCallback)(
575 : void *pUserData, const char *pszDirname);
576 : /**
577 : * Open a handle. Mandatory. Returns an opaque pointer that will be used in
578 : * subsequent file I/O calls. Should return null and/or set errno if the handle
579 : * does not exist or the access mode is incorrect.
580 : * @since GDAL 3.0
581 : */
582 : typedef void *(*VSIFilesystemPluginOpenCallback)(void *pUserData,
583 : const char *pszFilename,
584 : const char *pszAccess);
585 : /**
586 : * Return current position in handle. Mandatory
587 : * @since GDAL 3.0
588 : */
589 : typedef vsi_l_offset (*VSIFilesystemPluginTellCallback)(void *pFile);
590 : /**
591 : * Seek to position in handle. Mandatory except for write only handles
592 : * @since GDAL 3.0
593 : */
594 : typedef int (*VSIFilesystemPluginSeekCallback)(void *pFile,
595 : vsi_l_offset nOffset,
596 : int nWhence);
597 : /**
598 : * Read data from current position, returns the number of blocks correctly read.
599 : * Mandatory except for write only handles
600 : * @since GDAL 3.0
601 : */
602 : typedef size_t (*VSIFilesystemPluginReadCallback)(void *pFile, void *pBuffer,
603 : size_t nSize, size_t nCount);
604 : /**
605 : * Read from multiple offsets. Optional, will be replaced by multiple calls to
606 : * Read() if not provided
607 : * @since GDAL 3.0
608 : */
609 : typedef int (*VSIFilesystemPluginReadMultiRangeCallback)(
610 : void *pFile, int nRanges, void **ppData, const vsi_l_offset *panOffsets,
611 : const size_t *panSizes);
612 : /**
613 : * Get empty ranges. Optional
614 : * @since GDAL 3.0
615 : */
616 : typedef VSIRangeStatus (*VSIFilesystemPluginGetRangeStatusCallback)(
617 : void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength);
618 : /**
619 : * Has end of file been reached. Mandatory? for read handles.
620 : * @since GDAL 3.0
621 : */
622 : typedef int (*VSIFilesystemPluginEofCallback)(void *pFile);
623 : /**
624 : * Write bytes at current offset. Mandatory for writable handles
625 : * @since GDAL 3.0
626 : */
627 : typedef size_t (*VSIFilesystemPluginWriteCallback)(void *pFile,
628 : const void *pBuffer,
629 : size_t nSize, size_t nCount);
630 : /**
631 : * Sync written bytes. Optional
632 : * @since GDAL 3.0
633 : */
634 : typedef int (*VSIFilesystemPluginFlushCallback)(void *pFile);
635 : /**
636 : * Truncate handle. Mandatory (driver dependent?) for write handles
637 : */
638 : typedef int (*VSIFilesystemPluginTruncateCallback)(void *pFile,
639 : vsi_l_offset nNewSize);
640 : /**
641 : * Close file handle. Optional
642 : * @since GDAL 3.0
643 : */
644 : typedef int (*VSIFilesystemPluginCloseCallback)(void *pFile);
645 :
646 : /**
647 : * This optional method is called when code plans to access soon one or several
648 : * ranges in a file. Some file systems may be able to use this hint to
649 : * for example asynchronously start such requests.
650 : *
651 : * Offsets may be given in a non-increasing order, and may potentially
652 : * overlap.
653 : *
654 : * @param pFile File handle.
655 : * @param nRanges Size of the panOffsets and panSizes arrays.
656 : * @param panOffsets Array containing the start offset of each range.
657 : * @param panSizes Array containing the size (in bytes) of each range.
658 : * @since GDAL 3.7
659 : */
660 : typedef void (*VSIFilesystemPluginAdviseReadCallback)(
661 : void *pFile, int nRanges, const vsi_l_offset *panOffsets,
662 : const size_t *panSizes);
663 :
664 : /**
665 : * struct containing callbacks to used by the handler.
666 : * (rw), (r), (w) or () at the end indicate whether the given callback is
667 : * mandatory for reading and or writing handlers. A (?) indicates that the
668 : * callback might be mandatory for certain drivers only.
669 : * @since GDAL 3.0
670 : */
671 : typedef struct
672 : {
673 : /**
674 : * Optional opaque pointer passed back to filemanager callbacks (e.g. open,
675 : * stat, rmdir)
676 : */
677 : void *pUserData;
678 : VSIFilesystemPluginStatCallback stat; /**< stat handle by name (rw)*/
679 : VSIFilesystemPluginUnlinkCallback unlink; /**< unlink handle by name ()*/
680 : VSIFilesystemPluginRenameCallback rename; /**< rename handle ()*/
681 : VSIFilesystemPluginMkdirCallback mkdir; /**< make directory ()*/
682 : VSIFilesystemPluginRmdirCallback rmdir; /**< remove directory ()*/
683 : VSIFilesystemPluginReadDirCallback
684 : read_dir; /**< list directory content (r?)*/
685 : VSIFilesystemPluginOpenCallback open; /**< open handle by name (rw) */
686 : VSIFilesystemPluginTellCallback
687 : tell; /**< get current position of handle (rw) */
688 : VSIFilesystemPluginSeekCallback
689 : seek; /**< set current position of handle (rw) */
690 : VSIFilesystemPluginReadCallback read; /**< read from current position (r) */
691 : VSIFilesystemPluginReadMultiRangeCallback
692 : read_multi_range; /**< read multiple blocks ()*/
693 : VSIFilesystemPluginGetRangeStatusCallback
694 : get_range_status; /**< get range status () */
695 : VSIFilesystemPluginEofCallback
696 : eof; /**< has end of file been reached (r?) */
697 : VSIFilesystemPluginWriteCallback
698 : write; /**< write bytes to current position (w) */
699 : VSIFilesystemPluginFlushCallback flush; /**< sync bytes (w) */
700 : VSIFilesystemPluginTruncateCallback truncate; /**< truncate handle (w?) */
701 : VSIFilesystemPluginCloseCallback close; /**< close handle (rw) */
702 : size_t nBufferSize; /**< buffer small reads (makes handler read only) */
703 : size_t nCacheSize; /**< max mem to use per file when buffering */
704 : VSIFilesystemPluginSiblingFilesCallback
705 : sibling_files; /**< list related files*/
706 :
707 : /** The following optional member has been added in GDAL 3.7: */
708 : VSIFilesystemPluginAdviseReadCallback advise_read; /**< AdviseRead() */
709 : /*
710 : Callbacks are defined as a struct allocated by a call to
711 : VSIAllocFilesystemPluginCallbacksStruct in order to try to maintain ABI
712 : stability when eventually adding a new member. Any callbacks added to
713 : this struct SHOULD be added to the END of this struct
714 : */
715 : } VSIFilesystemPluginCallbacksStruct;
716 :
717 : /**
718 : * return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with
719 : * handler callbacks
720 : * @since GDAL 3.0
721 : */
722 : VSIFilesystemPluginCallbacksStruct CPL_DLL *
723 : VSIAllocFilesystemPluginCallbacksStruct(void);
724 :
725 : /**
726 : * free resources allocated by VSIAllocFilesystemPluginCallbacksStruct
727 : * @since GDAL 3.0
728 : */
729 : void CPL_DLL VSIFreeFilesystemPluginCallbacksStruct(
730 : VSIFilesystemPluginCallbacksStruct *poCb);
731 :
732 : /**
733 : * register a handler on the given prefix. All IO on datasets opened with the
734 : * filename /prefix/xxxxxx will go through these callbacks. pszPrefix must begin
735 : * and end with a '/'
736 : * @since GDAL 3.0
737 : */
738 : int CPL_DLL VSIInstallPluginHandler(
739 : const char *pszPrefix, const VSIFilesystemPluginCallbacksStruct *poCb);
740 :
741 : /**
742 : * Unregister a handler previously installed with VSIInstallPluginHandler() on
743 : * the given prefix.
744 : * Note: it is generally unsafe to remove a handler while there are still file
745 : * handles opened that are managed by that handler. It is the responsibility of
746 : * the caller to ensure that it calls this function in a situation where it is
747 : * safe to do so.
748 : * @since GDAL 3.9
749 : */
750 : int CPL_DLL VSIRemovePluginHandler(const char *pszPrefix);
751 :
752 : /* ==================================================================== */
753 : /* Time querying. */
754 : /* ==================================================================== */
755 :
756 : /*! @cond Doxygen_Suppress */
757 : unsigned long CPL_DLL VSITime(unsigned long *);
758 : const char CPL_DLL *VSICTime(unsigned long);
759 : struct tm CPL_DLL *VSIGMTime(const time_t *pnTime, struct tm *poBrokenTime);
760 : struct tm CPL_DLL *VSILocalTime(const time_t *pnTime, struct tm *poBrokenTime);
761 : /*! @endcond */
762 :
763 : /*! @cond Doxygen_Suppress */
764 : /* -------------------------------------------------------------------- */
765 : /* the following can be turned on for detailed logging of */
766 : /* almost all IO calls. */
767 : /* -------------------------------------------------------------------- */
768 : #ifdef VSI_DEBUG
769 :
770 : #ifndef DEBUG
771 : #define DEBUG
772 : #endif
773 :
774 : #include "cpl_error.h"
775 :
776 : #define VSIDebug4(f, a1, a2, a3, a4) CPLDebug("VSI", f, a1, a2, a3, a4);
777 : #define VSIDebug3(f, a1, a2, a3) CPLDebug("VSI", f, a1, a2, a3);
778 : #define VSIDebug2(f, a1, a2) CPLDebug("VSI", f, a1, a2);
779 : #define VSIDebug1(f, a1) CPLDebug("VSI", f, a1);
780 : #else
781 : #define VSIDebug4(f, a1, a2, a3, a4) \
782 : { \
783 : }
784 : #define VSIDebug3(f, a1, a2, a3) \
785 : { \
786 : }
787 : #define VSIDebug2(f, a1, a2) \
788 : { \
789 : }
790 : #define VSIDebug1(f, a1) \
791 : { \
792 : }
793 : #endif
794 : /*! @endcond */
795 :
796 : CPL_C_END
797 :
798 : #endif /* ndef CPL_VSI_H_INCLUDED */
|
