1.. _rfc-7:
2
3=======================================================================================
4RFC 7: Use VSILFILE for VSI*L Functions
5=======================================================================================
6
7Author: Even Rouault (Eric Doenges is original author)
8
9Contact: even dot rouault at spatialys.com, Eric.Doenges@gmx.net
10
11Status: Adopted
12
13Purpose
14-------
15
16To change the API for the VSI*L family of functions to use a new
17data-type VSILFILE instead of the current FILE.
18
19Background, Rationale
20---------------------
21
22Currently, GDAL offers two APIs to abstract file access functions
23(referred to as VSI\* and VSI\ *L in this document). Both APIs claim to
24operate on FILE pointers; however, the VSI*\ L functions can only
25operate on FILE pointers created by the VSIFOpenL function. This is
26because VSIFOpenL returns a pointer to an internal C++ class typecast to
27a FILE pointer, not an actual FILE pointer. This makes it impossible for
28the compiler to warn when the VSI\* and VSI*L functions are
29inappropriately mixed.
30
31Proposed Fix
32------------
33
34A new opaque data-type VSILFILE shall be declared. All VSI\ *L functions
35shall be changed to use this new type instead of FILE. Additionally, any
36GDAL code that uses the VSI*\ L functions must be changed to use this
37data-type as well.
38
39RawRasterBand changes
40---------------------
41
42-  The 2 constructors are changed to accept a void\* fpRaw instead of a
43   FILE\*
44-  A new member VSILFILE\* fpRawL is added. The existing member FILE\*
45   fpRaw is kept. The constructors will set the adequate member
46   according to the value of the bIsVSIL parameter.
47-  A new method VSILFILE\* GetFPL() is added.
48-  The old FILE\* GetFP() is adapted to have same behavior as before
49   (can return a standard FILE handle or a VSI*L handle depending on the
50   handle that was passed to the constructor)
51
52Those changes are meant to minimize the need for casting when using
53RawRasterBand. Backward API compatibility is preserved.
54
55Compatibility Issues, Transition timeline
56-----------------------------------------
57
58In order to allow the compiler to detect inappropriate parameters passed
59to any of the VSI*L functions, VSILFILE will be declared with the help
60of an empty forward declaration, i.e.
61
62::
63
64   typedef struct _VSILFILE VSILFILE
65
66with the struct \_VSILFILE itself left undefined.
67
68However, this would break source compatibility for any existing code
69using the VSI*L API. Therefore, for now, VSILFILE is defined to be an
70alias of FILE, unless the VSIL_STRICT_ENFORCE macro is defined.
71
72::
73
74   #ifdef VSIL_STRICT_ENFORCE
75   typedef struct _VSILFILE VSILFILE;
76   #else
77   typedef FILE VSILFILE;
78   #endif
79
80In a future release (GDAL 2.0 ?), the behavior will be changed to
81enforce the new strong typing.
82
83Any future development done since the adoption of this RFC should use
84VSILFILE when dealing with the VSIF*L API.
85
86Questions
87---------
88
89-  Should we define VSIL_STRICT_ENFORCE by default when DEBUG is defined
90   ?
91
92This would make life easier for GDAL developers to use the appropriate
93typing, but not affect API/ABI when using release mode.
94
95Implementation
96--------------
97
98The whole source tree ( port, gcore, frmts, ogr, swig/include ) will be
99altered adequatly so that the compilation works in VSIL_STRICT_ENFORCE
100mode. Ticket #3799 contains a patch with the implementation. The
101compilation doesn't add any new warning. The autotest suite still works
102after this change.
103
104The GeoRaster and JPIPKAK drivers have been modified during the
105conversion process, but I'm not in position to compile them. Testing
106appreciated. All other drivers that have been altered in the conversion
107process have been compiled.
108
109In the conversion process, a misuse of POSIX FILE API with a large file
110handler was discovered in the ceos2 driver, but the function happened to
111be unusued.
112
113Voting History
114--------------
115
116::
117
118   * Frank Warmerdam +1
119   * Tamas Szekeres +1
120   * Daniel Morissette +1
121   * Howard Butler +1
122   * Even Rouault +1
123
124