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