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