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 (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 : #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 108463 : void operator()(void *p) const
287 : {
288 108463 : VSIFree(p);
289 108463 : }
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 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 : { \
819 : }
820 : #define VSIDebug3(f, a1, a2, a3) \
821 : { \
822 : }
823 : #define VSIDebug2(f, a1, a2) \
824 : { \
825 : }
826 : #define VSIDebug1(f, a1) \
827 : { \
828 : }
829 : #endif
830 : /*! @endcond */
831 :
832 : CPL_C_END
833 :
834 : #endif /* ndef CPL_VSI_H_INCLUDED */
|
