[Gdal-dev] RFC 7: API Change for the VSIxxxL family of file functions

[Eric Dönges]

Am 31.10.2006 um 16:32 schrieb Frank Warmerdam:

> VSIFOpenL() is not an across the board replacement for VSIFOpen().
> The non-L version of the functions continue to exist because
> some drivers use stdio functions that are not implemented for in
> the "L" api, such as VSIFGets().  In some cases driver code directly
> calls stdio functions using the FILE *.

I see. After looking at what VSIVirtualHandle provides, and what the  
drivers
in frmts and ogr need, what seems to be missing is equivalent  
functionality to fgets,
fgetc, ungetc, fprintf and fscanf. The first three would be fairly  
trivial to add, but
the next two ...

> Agreed.  One approach might be to make VSILFILE* a void pointer for  
> now
> with the intention of making it something else that would trigger type
> checking failures later - perhaps when we switch to GDAL 2.0 and are
> willing to sacrifice some backwards compatibility anyways.
>
> In the meantime applications can upgrade to the new mechanisms without
> too much disruption.

I reluctantly agree. I've updated the RFC accordingly. The short-term  
solution
should be much less work to do, since initially only two files need  
to be changed
(cpl_vsil.cpp and cpl_vsi.h).

--- snip ---

RFC 7: API Change for the VSIxxxL family of file functions

Author: Eric Dönges
Contact: Eric.Doenges at gmx.net
Status: Proposed


Purpose

To change the API for the VSIxxxL 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 VSIxxx and VSIxxxL in this document). Both APIs claim to operate  
on FILE*;
however, the VSIxxxL functions can only operate on FILE* created by the
VSIOpenL function. This is because VSIOpenL returns a pointer to an  
internal
C++ class typecast to FILE*, not an actual FILE*. This makes it  
impossible
for the compiler to warn when the VSIxxx and VSIxxxL functions are
inappropriately mixed.

Proposed Fix

A new opaque data-type VSILFILE shall be declared. All VSIxxxL  
functions shall
be changed to use this new type instead of FILE. Additionally, any  
GDAL code
that uses the VSIxxxL 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 VSIxxxL 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 VSIxxxL 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 VSIxxxL functions will at least make it immediately clear that  
these
functions cannot be expected to work if passed a FILE pointer.

--- snip ---

With kind regards,
Eric