| 1 | = RFC 43: GDALMajorObject::GetMetadataDomainList() = |
| 2 | |
| 3 | Author: Even Rouault[[BR]] |
| 4 | Contact: even dot rouault at mines-paris dot org [[BR]] |
| 5 | |
| 6 | == Summary == |
| 7 | |
| 8 | 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. |
| 9 | |
| 10 | == Background == |
| 11 | |
| 12 | 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. |
| 13 | |
| 14 | == Implementation == |
| 15 | |
| 16 | The base implementation in GDALMajorObject just calls GetDomainList() on the internal oMDMD member. |
| 17 | |
| 18 | {{{ |
| 19 | /************************************************************************/ |
| 20 | /* GetMetadataDomainList() */ |
| 21 | /************************************************************************/ |
| 22 | |
| 23 | /** |
| 24 | * \brief Fetch list of metadata domains. |
| 25 | * |
| 26 | * The returned string list is the list of (non-empty) metadata domains. |
| 27 | * |
| 28 | * This method does the same thing as the C function GDALGetMetadataDomainList(). |
| 29 | * |
| 30 | * @return NULL or a string list. Must be freed with CSLDestroy() |
| 31 | * |
| 32 | * @since GDAL 2.0 |
| 33 | */ |
| 34 | |
| 35 | char **GDALMajorObject::GetMetadataDomainList() |
| 36 | { |
| 37 | return CSLDuplicate(oMDMD.GetDomainList()); |
| 38 | } |
| 39 | }}} |
| 40 | |
| 41 | This method is also available in the C API ( char ** CPL_STDCALL GDALGetMetadataDomainList( GDALMajorObjectH hObject) ) and Swig bindings. |
| 42 | |
| 43 | == Impacted drivers == |
| 44 | |
| 45 | 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. |
| 46 | |
| 47 | To make it easy to implement the specialized GetMetadataDomainList(), GDALMajorObject will offer a protected BuildMetadataDomainList() method that can be used like the following : |
| 48 | |
| 49 | {{{ |
| 50 | /************************************************************************/ |
| 51 | /* GetMetadataDomainList() */ |
| 52 | /************************************************************************/ |
| 53 | |
| 54 | char **GTiffDataset::GetMetadataDomainList() |
| 55 | { |
| 56 | return BuildMetadataDomainList(GDALPamDataset::GetMetadataDomainList(), |
| 57 | TRUE, |
| 58 | "", "ProxyOverviewRequest", "RPC", "IMD", "SUBDATASETS", "EXIF", |
| 59 | "xml:XMP", "COLOR_PROFILE", NULL); |
| 60 | } |
| 61 | }}} |
| 62 | |
| 63 | 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. |
| 64 | |
| 65 | 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. |
| 66 | |
| 67 | A few caveats : |
| 68 | * 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"). |
| 69 | * For CEOS2 and ENVISAT, the list of metadata domains cannot be established easily. GetMetadataDomainList() will return the pattern of accepted domain names. |
| 70 | |
| 71 | |
| 72 | == Backward Compatibility == |
| 73 | |
| 74 | 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. |
| 75 | |
| 76 | == Testing == |
| 77 | |
| 78 | The Python autotest suite will be extended to test the new API in a few drivers. |
| 79 | |
| 80 | == Ticket == |
| 81 | |
| 82 | Ticket #5275 has been opened to track the progress of this RFC. |
| 83 | |
| 84 | The implementation is available in [http://trac.osgeo.org/gdal/attachment/ticket/5275/getmetadatadomainlist.patch an attachment to ticket 5275]. |