Changes between Initial Version and Version 1 of rfc7_vsilapi

Timestamp:

Apr 28, 2007, 12:19:25 PM (17 years ago)

Author:

warmerdam

Comment:

Ported from doxygen.

rfc7_vsilapi

@@ +1 @@
+= RFC 7: Use VSILFILE for VSI*L Functions = 
+
+Author: Eric Doenges[[BR]]
+Contact: Eric.Doenges@gmx.net[[BR]]
+Status: Proposed
+
+== Purpose ==
+
+To change the API for the VSI*L family of functions to use a new data-type
+VSILFILE instead of the current FILE.
+
+== Background, Rationale ==
+
+Currently, GDAL offers two APIs to abstract file access functions (referred to
+as VSI* and VSI*L in this document). Both APIs claim to operate on FILE
+pointers; however, the VSI*L functions can only operate on FILE pointers
+created by the VSIFOpenL function. This is because VSIFOpenL returns a pointer
+to an internal C++ class typecast to a FILE pointer, not an actual FILE pointer.
+This makes it impossible for the compiler to warn when the VSI* and VSI*L
+functions are inappropriately mixed.
+
+== Proposed Fix ==
+
+A new opaque data-type VSILFILE shall be declared. All VSI*L functions shall
+be changed to use this new type instead of FILE. Additionally, any GDAL code
+that uses the VSI*L functions must be changed to use this data-type as well.
+
+== 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
+of an empty forward declaration, i.e.
+{{{
+typedef struct VSILFILE VSILFILE
+}}}
+with the struct VSILFILE itself left undefined. However, this would break
+source compatibility for any existing code using the VSI*L API.
+
+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.
+