#ifndef DOXYGEN_SKIP
/* $Id: RFC7_VSILAPI.dox 10208 2006-11-02 16:23:39Z fwarmerdam $ */
#endif /* DOXYGEN_SKIP */
/*!
\page rfc7_vsilapi RFC 7: Use VSILFILE for VSI*L Functions
Author: Eric Dönges
Contact: Eric.Doenges@gmx.net
Status: Proposed
\section rfc7_purpose Purpose
To change the API for the VSI*L family of functions to use a new data-type
VSILFILE instead of the current FILE.
\section rfc7_background 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.
\section rfc7_proposal 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.
\section rfc7_compatibility 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 VSILFILEwith 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. */