wiki:rfc43_getmetadatadomainlist

Version 1 (modified by Even Rouault, 6 years ago) (diff)

rfc 43

RFC 43: GDALMajorObject::GetMetadataDomainList?()

Author: Even Rouault
Contact: even dot rouault at mines-paris dot org

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 :

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 an attachment to ticket 5275.