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