Changes between Initial Version and Version 1 of rfc10_ogropen

Timestamp:

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

Author:

warmerdam

Comment:

Ported from doxygen.

rfc10_ogropen

@@ +1 @@
+= RFC 10: OGR Open Parameters =
+
+Author: Andrey Kiselev[[BR]]
+Contact: dron@ak4719.spb.edu[[BR]]
+Status: Development
+
+== Summary ==
+
+It is proposed that OGRSFDriver::Open() and OGRSFDriverRegistrar::Open() calls
+should be changed to accept additional parameter containing arbitrary
+additional parameters supplied by caller. OGROpenEx() function will be
+introduced to map this new functionality into C interface. In addition
+it is proposed to add an "update" flag to OGRSFDriverRegistrar::Open()
+call to avoid using OGRSFDriverRegistrar::OpenShared() method.
+
+== Open parameters ==
+
+Sometimes it is needed to pass additional information to OGR driver along with
+the name of the dataset to be opened. It can be, for example, the style table
+name (some drivers allow to choose from the various style tables) or any other
+additional data. The old method for doing this was to encode the extra info in
+the dataset name string. It was inconvenient approach, so it proposed to use
+separate parameter in OGRSFDriver::Open() and OGRSFDriverRegistrar::Open()
+calls representing open options, just like it is implemented in
+OGRDataSource::CreateLayer() call.
+
+It is supposed that open options will be supplied in form of NAME=VALUE pairs
+forming the string list.
+
+In addition to options parameter the special "shared" flag will be added to
+OGRSFDriverRegistrar::Open() call, so there will be no need in separate
+OGRSFDriverRegistrar::OpenShared() method.
+
+== Implementation ==
+
+All Open() functions will be changed in the following way:
+
+{{{
+static OGRDataSource *
+OGRSFDriverRegistrar::Open( const char * pszName, int bUpdate,
+                            OGRSFDriver ** ppoDriver,
+                            int bShared = FALSE,
+                            char **papszOptions = NULL );
+
+
+}}}
+
+{{{
+OGRDataSource *
+OGRSFDriverRegistrar::OpenShared( const char * pszName, int bUpdate,
+                                  OGRSFDriver ** ppoDriver )
+        { return Open( pszName, bUpdate, ppoDriver, TRUE, NULL ); }
+}}}
+
+{{{
+virtual OGRDataSource
+OGRSFDriver::*Open( const char *pszName, int bUpdate=FALSE,
+                    char **papszOptions = NULL ) = 0;
+}}}
+
+The last change needs to be propagated in all OGR drivers. The change itself
+is pretty simple: one additional parameter should be added to function
+definition. But it has impact on third-party OGR drivers: they are not
+source compatible anymore and should be changed too.
+
+Also appropriate C functions will be added:
+
+{{{
+OGRDataSourceH OGROpenEx( const char *pszName, int bUpdate,
+                          OGRSFDriverH *pahDriverList,
+                          int bShared, char **papszOptions );
+}}}
+
+{{{
+OGRDataSourceH OGR_Dr_OpenEx( OGRSFDriverH hDriver, const char *pszName, 
+                              int bUpdate, char **papszOptions );
+}}}  
+
+== New Options for OGR Utilities ==
+
+Proposed functionality will be available in OGR utilities ogr2ogr and ogrinfo
+via the '-doo NAME=VALUE' ("Datasource Open Option") format specific parameter.
+
+== Backward Compatibility ==
+
+Proposed additions will not have any impact on C binary compatibility.
+C++ binary interface will be broken, source level compatibility will be
+broken for third-party OGR drivers only. There will be no impact
+for high-level applications on source level.
+
+== Responsibility and Timeline ==
+
+Andrey Kiselev is responsible to implement this proposal. New API will
+be available in GDAL 1.5.0.