1.. _rfc-10: 2 3================================================================================ 4RFC 10: OGR Open Parameters (not implemented) 5================================================================================ 6 7Author: Andrey Kiselev 8 9Contact: dron@ak4719.spb.edu 10 11Status: Development, *not* implemented 12 13Summary 14------- 15 16It is proposed that OGRSFDriver::Open() and OGRSFDriverRegistrar::Open() 17calls should be changed to accept additional parameter containing 18arbitrary additional parameters supplied by caller. OGROpenEx() function 19will be introduced to map this new functionality into C interface. In 20addition it is proposed to add an "update" flag to 21OGRSFDriverRegistrar::Open() call to avoid using 22OGRSFDriverRegistrar::OpenShared() method. 23 24Open parameters 25--------------- 26 27Sometimes it is needed to pass additional information to OGR driver 28along with the name of the dataset to be opened. It can be, for example, 29the style table name (some drivers allow to choose from the various 30style tables) or any other additional data. The old method for doing 31this was to encode the extra info in the dataset name string. It was 32inconvenient approach, so it proposed to use separate parameter in 33OGRSFDriver::Open() and OGRSFDriverRegistrar::Open() calls representing 34open options, just like it is implemented in 35OGRDataSource::CreateLayer() call. 36 37It is supposed that open options will be supplied in form of NAME=VALUE 38pairs forming the string list. 39 40In addition to options parameter the special "shared" flag will be added 41to OGRSFDriverRegistrar::Open() call, so there will be no need in 42separate OGRSFDriverRegistrar::OpenShared() method. 43 44Implementation 45-------------- 46 47All Open() functions will be changed in the following way: 48 49:: 50 51 static OGRDataSource * 52 OGRSFDriverRegistrar::Open( const char * pszName, int bUpdate, 53 OGRSFDriver ** ppoDriver, 54 int bShared = FALSE, 55 char **papszOptions = NULL ); 56 57 58:: 59 60 OGRDataSource * 61 OGRSFDriverRegistrar::OpenShared( const char * pszName, int bUpdate, 62 OGRSFDriver ** ppoDriver ) 63 { return Open( pszName, bUpdate, ppoDriver, TRUE, NULL ); } 64 65:: 66 67 virtual OGRDataSource 68 OGRSFDriver::*Open( const char *pszName, int bUpdate=FALSE, 69 char **papszOptions = NULL ) = 0; 70 71The last change needs to be propagated in all OGR drivers. The change 72itself is pretty simple: one additional parameter should be added to 73function definition. But it has impact on third-party OGR drivers: they 74are not source compatible anymore and should be changed too. 75 76Also appropriate C functions will be added: 77 78:: 79 80 OGRDataSourceH OGROpenEx( const char *pszName, int bUpdate, 81 OGRSFDriverH *pahDriverList, 82 int bShared, char **papszOptions ); 83 84:: 85 86 OGRDataSourceH OGR_Dr_OpenEx( OGRSFDriverH hDriver, const char *pszName, 87 int bUpdate, char **papszOptions ); 88 89New Options for OGR Utilities 90----------------------------- 91 92Proposed functionality will be available in OGR utilities ogr2ogr and 93ogrinfo via the '-doo NAME=VALUE' ("Datasource Open Option") format 94specific parameter. 95 96Backward Compatibility 97---------------------- 98 99Proposed additions will not have any impact on C binary compatibility. 100C++ binary interface will be broken, source level compatibility will be 101broken for third-party OGR drivers only. There will be no impact for 102high-level applications on source level. 103 104Responsibility and Timeline 105--------------------------- 106 107Andrey Kiselev is responsible to implement this proposal. New API will 108be available in GDAL 1.5.0. 109