Line | Count | Source (jump to first uncovered line) |
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 (Virtual System Interface) functions are intended to be hookable |
29 | | * aliases for Standard C I/O, memory allocation and other system functions. |
30 | | * They are intended to allow virtualization of disk I/O so that non file data |
31 | | * sources 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 | 0 | #define VSI_ISLNK(x) S_ISLNK(x) |
112 | | /** Test if the file is a regular file */ |
113 | 25.1k | #define VSI_ISREG(x) S_ISREG(x) |
114 | | /** Test if the file is a directory */ |
115 | 37.2k | #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 | 5.38M | #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 | 623k | #define VSI_STAT_EXISTS_FLAG 0x1 |
195 | | /** Flag provided to VSIStatExL() to query the nature (file/dir) of the file */ |
196 | 524k | #define VSI_STAT_NATURE_FLAG 0x2 |
197 | | /** Flag provided to VSIStatExL() to query the file size */ |
198 | 270k | #define VSI_STAT_SIZE_FLAG 0x4 |
199 | | /** Flag provided to VSIStatExL() to issue a VSIError in case of failure */ |
200 | 3.75k | #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 | 4.69k | #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 | | void operator()(void *p) const |
287 | 0 | { |
288 | 0 | VSIFree(p); |
289 | 0 | } |
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 | 5.61M | 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 | 1.95M | #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 | 310k | 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 | 31.5k | 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 | 2.44M | 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 | 2.01M | 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 | 7.27M | #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 | 2 | #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 VSIMove(const char *oldpath, const char *newpath, |
440 | | const char *const *papszOptions, |
441 | | GDALProgressFunc pProgressFunc, void *pProgressData); |
442 | | int CPL_DLL VSICopyFile(const char *pszSource, const char *pszTarget, |
443 | | VSILFILE *fpSource, vsi_l_offset nSourceSize, |
444 | | const char *const *papszOptions, |
445 | | GDALProgressFunc pProgressFunc, void *pProgressData); |
446 | | int CPL_DLL VSICopyFileRestartable(const char *pszSource, const char *pszTarget, |
447 | | const char *pszInputPayload, |
448 | | char **ppszOutputPayload, |
449 | | const char *const *papszOptions, |
450 | | GDALProgressFunc pProgressFunc, |
451 | | void *pProgressData); |
452 | | int CPL_DLL VSISync(const char *pszSource, const char *pszTarget, |
453 | | const char *const *papszOptions, |
454 | | GDALProgressFunc pProgressFunc, void *pProgressData, |
455 | | char ***ppapszOutputs); |
456 | | |
457 | | int CPL_DLL VSIMultipartUploadGetCapabilities( |
458 | | const char *pszFilename, int *pbNonSequentialUploadSupported, |
459 | | int *pbParallelUploadSupported, int *pbAbortSupported, |
460 | | size_t *pnMinPartSize, size_t *pnMaxPartSize, int *pnMaxPartCount); |
461 | | |
462 | | char CPL_DLL *VSIMultipartUploadStart(const char *pszFilename, |
463 | | CSLConstList papszOptions); |
464 | | char CPL_DLL *VSIMultipartUploadAddPart(const char *pszFilename, |
465 | | const char *pszUploadId, |
466 | | int nPartNumber, |
467 | | vsi_l_offset nFileOffset, |
468 | | const void *pData, size_t nDataLength, |
469 | | CSLConstList papszOptions); |
470 | | int CPL_DLL VSIMultipartUploadEnd(const char *pszFilename, |
471 | | const char *pszUploadId, size_t nPartIdsCount, |
472 | | const char *const *apszPartIds, |
473 | | vsi_l_offset nTotalSize, |
474 | | CSLConstList papszOptions); |
475 | | int CPL_DLL VSIMultipartUploadAbort(const char *pszFilename, |
476 | | const char *pszUploadId, |
477 | | CSLConstList papszOptions); |
478 | | |
479 | | int CPL_DLL VSIAbortPendingUploads(const char *pszFilename); |
480 | | |
481 | | char CPL_DLL *VSIStrerror(int); |
482 | | GIntBig CPL_DLL VSIGetDiskFreeSpace(const char *pszDirname); |
483 | | |
484 | | void CPL_DLL VSINetworkStatsReset(void); |
485 | | char CPL_DLL *VSINetworkStatsGetAsSerializedJSON(char **papszOptions); |
486 | | |
487 | | /* ==================================================================== */ |
488 | | /* Install special file access handlers. */ |
489 | | /* ==================================================================== */ |
490 | | void CPL_DLL VSIInstallMemFileHandler(void); |
491 | | /*! @cond Doxygen_Suppress */ |
492 | | void CPL_DLL VSIInstallLargeFileHandler(void); |
493 | | /*! @endcond */ |
494 | | void CPL_DLL VSIInstallSubFileHandler(void); |
495 | | void VSIInstallCurlFileHandler(void); |
496 | | void CPL_DLL VSICurlClearCache(void); |
497 | | void CPL_DLL VSICurlPartialClearCache(const char *pszFilenamePrefix); |
498 | | void VSIInstallCurlStreamingFileHandler(void); |
499 | | void VSIInstallS3FileHandler(void); |
500 | | void VSIInstallS3StreamingFileHandler(void); |
501 | | void VSIInstallGSFileHandler(void); |
502 | | void VSIInstallGSStreamingFileHandler(void); |
503 | | void VSIInstallAzureFileHandler(void); |
504 | | void VSIInstallAzureStreamingFileHandler(void); |
505 | | void VSIInstallADLSFileHandler(void); |
506 | | void VSIInstallOSSFileHandler(void); |
507 | | void VSIInstallOSSStreamingFileHandler(void); |
508 | | void VSIInstallSwiftFileHandler(void); |
509 | | void VSIInstallSwiftStreamingFileHandler(void); |
510 | | void VSIInstall7zFileHandler(void); /* No reason to export that */ |
511 | | void VSIInstallRarFileHandler(void); /* No reason to export that */ |
512 | | void VSIInstallGZipFileHandler(void); /* No reason to export that */ |
513 | | void VSIInstallZipFileHandler(void); /* No reason to export that */ |
514 | | void VSIInstallStdinHandler(void); /* No reason to export that */ |
515 | | void VSIInstallHdfsHandler(void); /* No reason to export that */ |
516 | | void VSIInstallWebHdfsHandler(void); /* No reason to export that */ |
517 | | void VSIInstallStdoutHandler(void); /* No reason to export that */ |
518 | | void CPL_DLL VSIInstallSparseFileHandler(void); |
519 | | void VSIInstallTarFileHandler(void); /* No reason to export that */ |
520 | | void VSIInstallCachedFileHandler(void); /* No reason to export that */ |
521 | | void CPL_DLL VSIInstallCryptFileHandler(void); |
522 | | void CPL_DLL VSISetCryptKey(const GByte *pabyKey, int nKeySize); |
523 | | /*! @cond Doxygen_Suppress */ |
524 | | void CPL_DLL VSICleanupFileManager(void); |
525 | | /*! @endcond */ |
526 | | |
527 | | bool CPL_DLL VSIDuplicateFileSystemHandler(const char *pszSourceFSName, |
528 | | const char *pszNewFSName); |
529 | | |
530 | | VSILFILE CPL_DLL * |
531 | | VSIFileFromMemBuffer(const char *pszFilename, GByte *pabyData, |
532 | | vsi_l_offset nDataLength, |
533 | | int bTakeOwnership) CPL_WARN_UNUSED_RESULT; |
534 | | GByte CPL_DLL *VSIGetMemFileBuffer(const char *pszFilename, |
535 | | vsi_l_offset *pnDataLength, |
536 | | int bUnlinkAndSeize); |
537 | | |
538 | | const char CPL_DLL *VSIMemGenerateHiddenFilename(const char *pszFilename); |
539 | | |
540 | | /** Callback used by VSIStdoutSetRedirection() */ |
541 | | typedef size_t (*VSIWriteFunction)(const void *ptr, size_t size, size_t nmemb, |
542 | | FILE *stream); |
543 | | void CPL_DLL VSIStdoutSetRedirection(VSIWriteFunction pFct, FILE *stream); |
544 | | |
545 | | /** |
546 | | * Return information about a handle. Optional (driver dependent) |
547 | | * @since GDAL 3.0 |
548 | | */ |
549 | | typedef int (*VSIFilesystemPluginStatCallback)(void *pUserData, |
550 | | const char *pszFilename, |
551 | | VSIStatBufL *pStatBuf, |
552 | | int nFlags); |
553 | | /** |
554 | | * Remove handle by name. Optional |
555 | | * @since GDAL 3.0 |
556 | | */ |
557 | | typedef int (*VSIFilesystemPluginUnlinkCallback)(void *pUserData, |
558 | | const char *pszFilename); |
559 | | /** |
560 | | * Rename handle. Optional |
561 | | * @since GDAL 3.0 |
562 | | */ |
563 | | typedef int (*VSIFilesystemPluginRenameCallback)(void *pUserData, |
564 | | const char *oldpath, |
565 | | const char *newpath); |
566 | | /** |
567 | | * Create Directory. Optional |
568 | | * @since GDAL 3.0 |
569 | | */ |
570 | | typedef int (*VSIFilesystemPluginMkdirCallback)(void *pUserData, |
571 | | const char *pszDirname, |
572 | | long nMode); |
573 | | /** |
574 | | * Delete Directory. Optional |
575 | | * @since GDAL 3.0 |
576 | | */ |
577 | | typedef int (*VSIFilesystemPluginRmdirCallback)(void *pUserData, |
578 | | const char *pszDirname); |
579 | | /** |
580 | | * List directory content. Optional |
581 | | * @since GDAL 3.0 |
582 | | */ |
583 | | typedef char **(*VSIFilesystemPluginReadDirCallback)(void *pUserData, |
584 | | const char *pszDirname, |
585 | | int nMaxFiles); |
586 | | /** |
587 | | * List related files. Must return NULL if unknown, or a list of relative |
588 | | * filenames that can be opened along the main file. If no other file than |
589 | | * pszFilename needs to be opened, return static_cast<char**> |
590 | | * (CPLCalloc(1,sizeof(char*))); |
591 | | * |
592 | | * Optional |
593 | | * @since GDAL 3.2 |
594 | | */ |
595 | | typedef char **(*VSIFilesystemPluginSiblingFilesCallback)( |
596 | | void *pUserData, const char *pszDirname); |
597 | | /** |
598 | | * Open a handle. Mandatory. Returns an opaque pointer that will be used in |
599 | | * subsequent file I/O calls. Should return null and/or set errno if the handle |
600 | | * does not exist or the access mode is incorrect. |
601 | | * @since GDAL 3.0 |
602 | | */ |
603 | | typedef void *(*VSIFilesystemPluginOpenCallback)(void *pUserData, |
604 | | const char *pszFilename, |
605 | | const char *pszAccess); |
606 | | /** |
607 | | * Return current position in handle. Mandatory |
608 | | * @since GDAL 3.0 |
609 | | */ |
610 | | typedef vsi_l_offset (*VSIFilesystemPluginTellCallback)(void *pFile); |
611 | | /** |
612 | | * Seek to position in handle. Mandatory except for write only handles |
613 | | * @since GDAL 3.0 |
614 | | */ |
615 | | typedef int (*VSIFilesystemPluginSeekCallback)(void *pFile, |
616 | | vsi_l_offset nOffset, |
617 | | int nWhence); |
618 | | /** |
619 | | * Read data from current position, returns the number of blocks correctly read. |
620 | | * Mandatory except for write only handles |
621 | | * @since GDAL 3.0 |
622 | | */ |
623 | | typedef size_t (*VSIFilesystemPluginReadCallback)(void *pFile, void *pBuffer, |
624 | | size_t nSize, size_t nCount); |
625 | | /** |
626 | | * Read from multiple offsets. Optional, will be replaced by multiple calls to |
627 | | * Read() if not provided |
628 | | * @since GDAL 3.0 |
629 | | */ |
630 | | typedef int (*VSIFilesystemPluginReadMultiRangeCallback)( |
631 | | void *pFile, int nRanges, void **ppData, const vsi_l_offset *panOffsets, |
632 | | const size_t *panSizes); |
633 | | /** |
634 | | * Get empty ranges. Optional |
635 | | * @since GDAL 3.0 |
636 | | */ |
637 | | typedef VSIRangeStatus (*VSIFilesystemPluginGetRangeStatusCallback)( |
638 | | void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength); |
639 | | /** |
640 | | * Has end of file been reached. Mandatory? for read handles. |
641 | | * @since GDAL 3.0 |
642 | | */ |
643 | | typedef int (*VSIFilesystemPluginEofCallback)(void *pFile); |
644 | | /** |
645 | | * Write bytes at current offset. Mandatory for writable handles |
646 | | * @since GDAL 3.0 |
647 | | */ |
648 | | typedef size_t (*VSIFilesystemPluginWriteCallback)(void *pFile, |
649 | | const void *pBuffer, |
650 | | size_t nSize, size_t nCount); |
651 | | /** |
652 | | * Sync written bytes. Optional |
653 | | * @since GDAL 3.0 |
654 | | */ |
655 | | typedef int (*VSIFilesystemPluginFlushCallback)(void *pFile); |
656 | | /** |
657 | | * Truncate handle. Mandatory (driver dependent?) for write handles |
658 | | */ |
659 | | typedef int (*VSIFilesystemPluginTruncateCallback)(void *pFile, |
660 | | vsi_l_offset nNewSize); |
661 | | /** |
662 | | * Close file handle. Optional |
663 | | * @since GDAL 3.0 |
664 | | */ |
665 | | typedef int (*VSIFilesystemPluginCloseCallback)(void *pFile); |
666 | | |
667 | | /** |
668 | | * This optional method is called when code plans to access soon one or several |
669 | | * ranges in a file. Some file systems may be able to use this hint to |
670 | | * for example asynchronously start such requests. |
671 | | * |
672 | | * Offsets may be given in a non-increasing order, and may potentially |
673 | | * overlap. |
674 | | * |
675 | | * @param pFile File handle. |
676 | | * @param nRanges Size of the panOffsets and panSizes arrays. |
677 | | * @param panOffsets Array containing the start offset of each range. |
678 | | * @param panSizes Array containing the size (in bytes) of each range. |
679 | | * @since GDAL 3.7 |
680 | | */ |
681 | | typedef void (*VSIFilesystemPluginAdviseReadCallback)( |
682 | | void *pFile, int nRanges, const vsi_l_offset *panOffsets, |
683 | | const size_t *panSizes); |
684 | | |
685 | | /** |
686 | | * Has a read error (non end-of-file related) has occurred? |
687 | | * @since GDAL 3.10 |
688 | | */ |
689 | | typedef int (*VSIFilesystemPluginErrorCallback)(void *pFile); |
690 | | |
691 | | /** |
692 | | * Clear error and end-of-file flags. |
693 | | * @since GDAL 3.10 |
694 | | */ |
695 | | typedef void (*VSIFilesystemPluginClearErrCallback)(void *pFile); |
696 | | |
697 | | /** |
698 | | * struct containing callbacks to used by the handler. |
699 | | * (rw), (r), (w) or () at the end indicate whether the given callback is |
700 | | * mandatory for reading and or writing handlers. A (?) indicates that the |
701 | | * callback might be mandatory for certain drivers only. |
702 | | * @since GDAL 3.0 |
703 | | */ |
704 | | typedef struct |
705 | | { |
706 | | /** |
707 | | * Optional opaque pointer passed back to filemanager callbacks (e.g. open, |
708 | | * stat, rmdir) |
709 | | */ |
710 | | void *pUserData; |
711 | | VSIFilesystemPluginStatCallback stat; /**< stat handle by name (rw)*/ |
712 | | VSIFilesystemPluginUnlinkCallback unlink; /**< unlink handle by name ()*/ |
713 | | VSIFilesystemPluginRenameCallback rename; /**< rename handle ()*/ |
714 | | VSIFilesystemPluginMkdirCallback mkdir; /**< make directory ()*/ |
715 | | VSIFilesystemPluginRmdirCallback rmdir; /**< remove directory ()*/ |
716 | | VSIFilesystemPluginReadDirCallback |
717 | | read_dir; /**< list directory content (r?)*/ |
718 | | VSIFilesystemPluginOpenCallback open; /**< open handle by name (rw) */ |
719 | | VSIFilesystemPluginTellCallback |
720 | | tell; /**< get current position of handle (rw) */ |
721 | | VSIFilesystemPluginSeekCallback |
722 | | seek; /**< set current position of handle (rw) */ |
723 | | VSIFilesystemPluginReadCallback read; /**< read from current position (r) */ |
724 | | VSIFilesystemPluginReadMultiRangeCallback |
725 | | read_multi_range; /**< read multiple blocks ()*/ |
726 | | VSIFilesystemPluginGetRangeStatusCallback |
727 | | get_range_status; /**< get range status () */ |
728 | | VSIFilesystemPluginEofCallback |
729 | | eof; /**< has end of file been reached (r?) */ |
730 | | VSIFilesystemPluginWriteCallback |
731 | | write; /**< write bytes to current position (w) */ |
732 | | VSIFilesystemPluginFlushCallback flush; /**< sync bytes (w) */ |
733 | | VSIFilesystemPluginTruncateCallback truncate; /**< truncate handle (w?) */ |
734 | | VSIFilesystemPluginCloseCallback close; /**< close handle (rw) */ |
735 | | size_t nBufferSize; /**< buffer small reads (makes handler read only) */ |
736 | | size_t nCacheSize; /**< max mem to use per file when buffering */ |
737 | | VSIFilesystemPluginSiblingFilesCallback |
738 | | sibling_files; /**< list related files*/ |
739 | | |
740 | | /** The following optional member has been added in GDAL 3.7: */ |
741 | | VSIFilesystemPluginAdviseReadCallback advise_read; /**< AdviseRead() */ |
742 | | |
743 | | VSIFilesystemPluginErrorCallback error; /**< has read error occurred (r) */ |
744 | | VSIFilesystemPluginClearErrCallback clear_err; /**< clear error flags(r) */ |
745 | | /* |
746 | | Callbacks are defined as a struct allocated by a call to |
747 | | VSIAllocFilesystemPluginCallbacksStruct in order to try to maintain ABI |
748 | | stability when eventually adding a new member. Any callbacks added to |
749 | | this struct SHOULD be added to the END of this struct |
750 | | */ |
751 | | } VSIFilesystemPluginCallbacksStruct; |
752 | | |
753 | | /** |
754 | | * return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with |
755 | | * handler callbacks |
756 | | * @since GDAL 3.0 |
757 | | */ |
758 | | VSIFilesystemPluginCallbacksStruct CPL_DLL * |
759 | | VSIAllocFilesystemPluginCallbacksStruct(void); |
760 | | |
761 | | /** |
762 | | * free resources allocated by VSIAllocFilesystemPluginCallbacksStruct |
763 | | * @since GDAL 3.0 |
764 | | */ |
765 | | void CPL_DLL VSIFreeFilesystemPluginCallbacksStruct( |
766 | | VSIFilesystemPluginCallbacksStruct *poCb); |
767 | | |
768 | | /** |
769 | | * register a handler on the given prefix. All IO on datasets opened with the |
770 | | * filename /prefix/xxxxxx will go through these callbacks. pszPrefix must begin |
771 | | * and end with a '/' |
772 | | * @since GDAL 3.0 |
773 | | */ |
774 | | int CPL_DLL VSIInstallPluginHandler( |
775 | | const char *pszPrefix, const VSIFilesystemPluginCallbacksStruct *poCb); |
776 | | |
777 | | /** |
778 | | * Unregister a handler previously installed with VSIInstallPluginHandler() on |
779 | | * the given prefix. |
780 | | * Note: it is generally unsafe to remove a handler while there are still file |
781 | | * handles opened that are managed by that handler. It is the responsibility of |
782 | | * the caller to ensure that it calls this function in a situation where it is |
783 | | * safe to do so. |
784 | | * @since GDAL 3.9 |
785 | | */ |
786 | | int CPL_DLL VSIRemovePluginHandler(const char *pszPrefix); |
787 | | |
788 | | /* ==================================================================== */ |
789 | | /* Time querying. */ |
790 | | /* ==================================================================== */ |
791 | | |
792 | | /*! @cond Doxygen_Suppress */ |
793 | | unsigned long CPL_DLL VSITime(unsigned long *); |
794 | | const char CPL_DLL *VSICTime(unsigned long); |
795 | | struct tm CPL_DLL *VSIGMTime(const time_t *pnTime, struct tm *poBrokenTime); |
796 | | struct tm CPL_DLL *VSILocalTime(const time_t *pnTime, struct tm *poBrokenTime); |
797 | | /*! @endcond */ |
798 | | |
799 | | /*! @cond Doxygen_Suppress */ |
800 | | /* -------------------------------------------------------------------- */ |
801 | | /* the following can be turned on for detailed logging of */ |
802 | | /* almost all IO calls. */ |
803 | | /* -------------------------------------------------------------------- */ |
804 | | #ifdef VSI_DEBUG |
805 | | |
806 | | #ifndef DEBUG |
807 | | #define DEBUG |
808 | | #endif |
809 | | |
810 | | #include "cpl_error.h" |
811 | | |
812 | | #define VSIDebug4(f, a1, a2, a3, a4) CPLDebug("VSI", f, a1, a2, a3, a4); |
813 | | #define VSIDebug3(f, a1, a2, a3) CPLDebug("VSI", f, a1, a2, a3); |
814 | | #define VSIDebug2(f, a1, a2) CPLDebug("VSI", f, a1, a2); |
815 | | #define VSIDebug1(f, a1) CPLDebug("VSI", f, a1); |
816 | | #else |
817 | | #define VSIDebug4(f, a1, a2, a3, a4) \ |
818 | 879k | { \ |
819 | 879k | } |
820 | | #define VSIDebug3(f, a1, a2, a3) \ |
821 | 213k | { \ |
822 | 213k | } |
823 | | #define VSIDebug2(f, a1, a2) \ |
824 | | { \ |
825 | | } |
826 | | #define VSIDebug1(f, a1) \ |
827 | 96.9k | { \ |
828 | 96.9k | } |
829 | | #endif |
830 | | /*! @endcond */ |
831 | | |
832 | | CPL_C_END |
833 | | |
834 | | #endif /* ndef CPL_VSI_H_INCLUDED */ |