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