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

[Eric Dönges]

Hi list,


in response to my gripe about VSIOpenL claiming to return a FILE*  
when it's not,
Frank said I should submit an RFC, so here it is.

--- 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.

Implementation Details

While it would seem natural to declare VSILFILE* as a typedef of a  
void pointer
similar to the way GDAL defines the data-type handles for the C API,  
this has
the disadvantage that the compiler will not be able to warn about  
improper
pointer conversions since any type of pointer can be converted to a void
pointer. Instead, it is proposed to declare VSIFILE with the help of  
an empty
forward declaration, i.e. "typedef struct VSILFILE VSILFILE", with  
the struct
VSILFILE left undefined.

--- snip ---

The necessary changes should be very simple, if a lot of busywork. As  
as I said in my
initial post, I volunteer to do the required work. (However, I can  
only test on
MacOS or Linux).

With kind regards,
Eric