Changes between Initial Version and Version 1 of rfc43_getmetadatadomainlist

Timestamp:

Oct 19, 2013, 11:38:05 AM (11 years ago)

Author:

Even Rouault

Comment:

rfc 43

rfc43_getmetadatadomainlist

@@ +1 @@
+= RFC 43: GDALMajorObject::GetMetadataDomainList() =
+
+Author: Even Rouault[[BR]]
+Contact: even dot rouault at mines-paris dot org [[BR]]
+
+== Summary ==
+
+This (mini)RFC proposes a new virtual method, GetMetadataDomainList(), in the GDALMajorObject class (and a C API) to return the list of all available metadata domains.
+
+== Background ==
+
+GDALMajorObject currently offers the GetMetadata() and GetMetadataItem() methods that both accept a metadata domain argument. But there is no way to auto-discover which metadata domains are valid for a given GDALMajorObject (i.e. a dataset or raster band). This make it impossible to have generic code that can exhaustively discover all metadata in a dataset/raster band.
+
+== Implementation ==
+
+The base implementation in GDALMajorObject just calls GetDomainList() on the internal oMDMD member.
+
+{{{
+/************************************************************************/
+/*                      GetMetadataDomainList()                         */
+/************************************************************************/
+
+/**
+ * \brief Fetch list of metadata domains.
+ *
+ * The returned string list is the list of (non-empty) metadata domains.
+ *
+ * This method does the same thing as the C function GDALGetMetadataDomainList().
+ * 
+ * @return NULL or a string list. Must be freed with CSLDestroy()
+ *
+ * @since GDAL 2.0
+ */
+
+char **GDALMajorObject::GetMetadataDomainList()
+{
+    return CSLDuplicate(oMDMD.GetDomainList());
+}
+}}}
+
+This method is also available in the C API ( char ** CPL_STDCALL GDALGetMetadataDomainList( GDALMajorObjectH hObject) ) and Swig bindings.
+
+== Impacted drivers ==
+
+Drivers that have custom implementations of GetMetadata() and/or GetMetadataItem() will generally have to also implement GetMetadataDomainList(), when they don't modify the oMDMD member.
+
+To make it easy to implement the specialized GetMetadataDomainList(), GDALMajorObject will offer a protected BuildMetadataDomainList() method that can be used like the following :
+
+{{{
+/************************************************************************/
+/*                      GetMetadataDomainList()                         */
+/************************************************************************/
+
+char **GTiffDataset::GetMetadataDomainList()
+{
+    return BuildMetadataDomainList(GDALPamDataset::GetMetadataDomainList(),
+                                   TRUE,
+                                   "", "ProxyOverviewRequest", "RPC", "IMD", "SUBDATASETS", "EXIF",
+                                   "xml:XMP", "COLOR_PROFILE", NULL);
+}
+}}}
+
+The TRUE parameter means that the list of domains that follows are potential domains, and thus BuildMetadataDomainList() will check for each one that GetMetadata() returns a non-NULL value.
+
+An exhaustive search in GDAL drivers has been made and all drivers that needed to be updated to implement GetMetadataDomainList() have been updated: ADRG, CEOS2, DIMAP, ECW, ENVISAT, ERS, GeoRaster (cannot check myself that it compiles), GIF, GTiff, HDF4, HDF5, JPEG, MBTILES, netCDF, NITF, OGDI, PCIDSK, PDF, PNG, PostgisRaster, RasterLite, RS2, VRT, WCS, WebP, WMS.
+
+A few caveats :
+  * For MBTiles, WMS and VRT, GetMetadataDomainList(), at the band level, will return "LocationInfo" as a valid metadata domain (used by the gdallocationinfo utility), even if GetMetadata("LocationInfo") itself does not return metadata : you have to call GetMetadataItem("Pixel_someX_someY", "LocationInfo") or GetMetadataItem("GeoPixel_someX_someY", "LocationInfo").
+  * For CEOS2 and ENVISAT, the list of metadata domains cannot be established easily. GetMetadataDomainList() will return the pattern of accepted domain names.
+
+
+== Backward Compatibility ==
+
+This change has no impact on backward compatibility at the C API/ABI and C++ API levels. But it impacts C++ ABI, so it requires a full rebuild of all GDAL drivers.
+
+== Testing ==
+
+The Python autotest suite will be extended to test the new API in a few drivers. 
+
+== Ticket ==
+
+Ticket #5275 has been opened to track the progress of this RFC. 
+
+The implementation is available in [http://trac.osgeo.org/gdal/attachment/ticket/5275/getmetadatadomainlist.patch an attachment to ticket 5275].