Changes between Version 1 and Version 2 of rfc7_vsilapi

Timestamp:

Oct 23, 2010, 7:31:45 AM (14 years ago)

Author:

Even Rouault

Comment:

revive RFC7

rfc7_vsilapi

@@ -1 +1 @@
 = RFC 7: Use VSILFILE for VSI*L Functions = 
 
-Author: Eric Doenges[[BR]]
-Contact: Eric.Doenges@gmx.net[[BR]]
+Author: Even Rouault (Eric Doenges is original author) [[BR]]
+Contact: even dot rouault at mines dash paris dot org, Eric.Doenges@gmx.net [[BR]]
 Status: Proposed
 
@@ -26 +26 @@
 that uses the VSI*L functions must be changed to use this data-type as well.
 
+== RawRasterBand changes ==
+
+  * The 2 constructors are changed to accept a void* fpRaw instead of a FILE*
+  * A new member VSILFILE* fpRawL is added. The existing member FILE* fpRaw is
+    kept. The constructors will set the adequate member according to the value of
+    the bIsVSIL parameter.
+  * A new method VSILFILE* GetFPL() is added.
+  * The old FILE* GetFP() is adapted to have same behaviour as before (can return
+    a standard FILE handle or a VSI*L handle depending on the handle that was passed to the constructor)
+
+Those changes are meant to minimize the need for casting when using RawRasterBand. Backward API
+compatibility is preserved.
+
 == Compatibility Issues, Transition timeline ==
 
 In order to allow the compiler to detect inappropriate parameters passed to
-any of the VSI*L functions, VSILFILE would have to be declared with the help
+any of the VSI*L functions, VSILFILE will be declared with the help
 of an empty forward declaration, i.e.
 {{{
-typedef struct VSILFILE VSILFILE
+typedef struct _VSILFILE VSILFILE
 }}}
-with the struct VSILFILE itself left undefined. However, this would break
+with the struct _VSILFILE itself left undefined.
+
+However, this would break
 source compatibility for any existing code using the VSI*L API.
+Therefore, for now, VSILFILE is defined to be an alias of FILE, unless
+the VSIL_STRICT_ENFORCE macro is defined.
 
-Therefore, VSILFILE* will be declared as a void pointer for now, and the change
-to a distinct pointer type deferred to a future release of gdal that is not
-constrained with backward compatibility issues. While this will not solve the
-primary issue (no warnings/errors from the compiler), looking at the
-declarations of the VSI*L functions will at least make it immediately clear
-that these functions cannot be expected to work if passed a FILE pointer.
- 
+{{{
+#ifdef VSIL_STRICT_ENFORCE
+typedef struct _VSILFILE VSILFILE;
+#else
+typedef FILE VSILFILE;
+#endif
+}}}
+
+In a future release (GDAL 2.0 ?), the behaviour will be changed to enforce the new strong typing.
+
+Any future development done since the adoption of this RFC should use VSILFILE when dealing with the VSIF*L API.
+
+== Questions ==
+
+* Should we define VSIL_STRICT_ENFORCE by default when DEBUG is defined ?
+
+This would make life easier for GDAL developers to use the appropriate typing, but not affect API/ABI when
+using release mode.
+
+== Implementation ==
+
+The whole source tree ( port, gcore, frmts, ogr, swig/include ) will be altered adequatly so that the
+compilation works in VSIL_STRICT_ENFORCE mode. Ticket #3799 contains a patch with the implementation.
+The compilation doesn't add any new warning. The autotest suite still works after this change.
+
+The GeoRaster driver has been modified during the conversion process, but I'm not in position to compile it.
+Testing appreciated. All other drivers that have been altered in the conversion process have been compiled.
+
+In the conversion process, a misuse of POSIX FILE API with a large file handler was discovered in the ceos2 driver,
+but the function happened to be unusued.