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