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