Line data Source code
1 : /******************************************************************************
2 : *
3 : * Project: GDAL Core
4 : * Purpose: Base class for objects with metadata, etc.
5 : * Author: Frank Warmerdam, warmerdam@pobox.com
6 : *
7 : ******************************************************************************
8 : * Copyright (c) 2000, Frank Warmerdam
9 : * Copyright (c) 2009-2013, Even Rouault <even dot rouault at spatialys.com>
10 : *
11 : * Permission is hereby granted, free of charge, to any person obtaining a
12 : * copy of this software and associated documentation files (the "Software"),
13 : * to deal in the Software without restriction, including without limitation
14 : * the rights to use, copy, modify, merge, publish, distribute, sublicense,
15 : * and/or sell copies of the Software, and to permit persons to whom the
16 : * Software is furnished to do so, subject to the following conditions:
17 : *
18 : * The above copyright notice and this permission notice shall be included
19 : * in all copies or substantial portions of the Software.
20 : *
21 : * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
22 : * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 : * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
24 : * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 : * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26 : * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27 : * DEALINGS IN THE SOFTWARE.
28 : ****************************************************************************/
29 :
30 : #include "cpl_port.h"
31 : #include "gdal_priv.h"
32 :
33 : #include <cstdarg>
34 : #include <cstddef>
35 :
36 : #include "cpl_error.h"
37 : #include "cpl_string.h"
38 : #include "gdal.h"
39 :
40 : /************************************************************************/
41 : /* GDALMajorObject() */
42 : /************************************************************************/
43 :
44 1510270 : GDALMajorObject::GDALMajorObject() : nFlags(GMO_VALID)
45 : {
46 1510220 : }
47 :
48 : /************************************************************************/
49 : /* ~GDALMajorObject() */
50 : /************************************************************************/
51 :
52 1423950 : GDALMajorObject::~GDALMajorObject()
53 :
54 : {
55 1423950 : if ((nFlags & GMO_VALID) == 0)
56 0 : CPLDebug("GDAL", "In ~GDALMajorObject on invalid object");
57 :
58 1423950 : nFlags &= ~GMO_VALID;
59 1423950 : }
60 :
61 : /************************************************************************/
62 : /* GetDescription() */
63 : /************************************************************************/
64 :
65 : /**
66 : * \brief Fetch object description.
67 : *
68 : * The semantics of the returned description are specific to the derived
69 : * type. For GDALDatasets it is the dataset name. For GDALRasterBands
70 : * it is actually a description (if supported) or "".
71 : *
72 : * This method is the same as the C function GDALGetDescription().
73 : *
74 : * @return non-null pointer to internal description string.
75 : */
76 :
77 5763400 : const char *GDALMajorObject::GetDescription() const
78 :
79 : {
80 5763400 : return sDescription.c_str();
81 : }
82 :
83 : /************************************************************************/
84 : /* GDALGetDescription() */
85 : /************************************************************************/
86 :
87 : /**
88 : * \brief Fetch object description.
89 : *
90 : * @see GDALMajorObject::GetDescription()
91 : */
92 :
93 23737 : const char *CPL_STDCALL GDALGetDescription(GDALMajorObjectH hObject)
94 :
95 : {
96 23737 : VALIDATE_POINTER1(hObject, "GDALGetDescription", nullptr);
97 :
98 23737 : return GDALMajorObject::FromHandle(hObject)->GetDescription();
99 : }
100 :
101 : /************************************************************************/
102 : /* SetDescription() */
103 : /************************************************************************/
104 :
105 : /**
106 : * \brief Set object description.
107 : *
108 : * The semantics of the description are specific to the derived
109 : * type. For GDALDatasets it is the dataset name. For GDALRasterBands
110 : * it is actually a description (if supported) or "".
111 : *
112 : * Normally application code should not set the "description" for
113 : * GDALDatasets. It is handled internally.
114 : *
115 : * This method is the same as the C function GDALSetDescription().
116 : */
117 :
118 438050 : void GDALMajorObject::SetDescription(const char *pszNewDesc)
119 :
120 : {
121 438050 : sDescription = pszNewDesc;
122 438042 : }
123 :
124 : /************************************************************************/
125 : /* GDALSetDescription() */
126 : /************************************************************************/
127 :
128 : /**
129 : * \brief Set object description.
130 : *
131 : * @see GDALMajorObject::SetDescription()
132 : */
133 :
134 209 : void CPL_STDCALL GDALSetDescription(GDALMajorObjectH hObject,
135 : const char *pszNewDesc)
136 :
137 : {
138 209 : VALIDATE_POINTER0(hObject, "GDALSetDescription");
139 :
140 209 : GDALMajorObject::FromHandle(hObject)->SetDescription(pszNewDesc);
141 : }
142 :
143 : /************************************************************************/
144 : /* GetMetadataDomainList() */
145 : /************************************************************************/
146 :
147 : /**
148 : * \brief Fetch list of metadata domains.
149 : *
150 : * The returned string list is the list of (non-empty) metadata domains.
151 : *
152 : * This method does the same thing as the C function
153 : * GDALGetMetadataDomainList().
154 : *
155 : * @return NULL or a string list. Must be freed with CSLDestroy()
156 : *
157 : * @since GDAL 1.11
158 : */
159 :
160 973 : char **GDALMajorObject::GetMetadataDomainList()
161 : {
162 973 : return CSLDuplicate(oMDMD.GetDomainList());
163 : }
164 :
165 : /************************************************************************/
166 : /* BuildMetadataDomainList() */
167 : /************************************************************************/
168 :
169 : /**
170 : * \brief Helper function for custom implementations of GetMetadataDomainList()
171 : *
172 : *
173 : * @param papszList initial list of domains. May be NULL. Will become invalid
174 : * after function call (use return value)
175 : * @param bCheckNonEmpty if TRUE, each candidate domain will be tested to be non
176 : * empty
177 : * @param ... NULL terminated variadic list of candidate domains.
178 : *
179 : * @return NULL or a string list. Must be freed with CSLDestroy()
180 : *
181 : * @since GDAL 1.11
182 : */
183 :
184 105 : char **GDALMajorObject::BuildMetadataDomainList(char **papszList,
185 : int bCheckNonEmpty, ...)
186 : {
187 : va_list args;
188 105 : const char *pszDomain = nullptr;
189 105 : va_start(args, bCheckNonEmpty);
190 :
191 454 : while ((pszDomain = va_arg(args, const char *)) != nullptr)
192 : {
193 635 : if (CSLFindString(papszList, pszDomain) < 0 &&
194 286 : (!bCheckNonEmpty || GetMetadata(pszDomain) != nullptr))
195 : {
196 14 : papszList = CSLAddString(papszList, pszDomain);
197 : }
198 : }
199 :
200 105 : va_end(args);
201 :
202 105 : return papszList;
203 : }
204 :
205 : /************************************************************************/
206 : /* GDALGetMetadataDomainList() */
207 : /************************************************************************/
208 :
209 : /**
210 : * \brief Fetch list of metadata domains.
211 : *
212 : * @see GDALMajorObject::GetMetadataDomainList()
213 : *
214 : * @since GDAL 1.11
215 : */
216 :
217 149 : char **CPL_STDCALL GDALGetMetadataDomainList(GDALMajorObjectH hObject)
218 :
219 : {
220 149 : VALIDATE_POINTER1(hObject, "GetMetadataDomainList", nullptr);
221 :
222 149 : return GDALMajorObject::FromHandle(hObject)->GetMetadataDomainList();
223 : }
224 :
225 : /************************************************************************/
226 : /* GetMetadata() */
227 : /************************************************************************/
228 :
229 : /**
230 : * \brief Fetch metadata.
231 : *
232 : * The returned string list is owned by the object, and may change at
233 : * any time. It is formatted as a "Name=value" list with the last pointer
234 : * value being NULL. Use the CPL StringList functions such as
235 : * CSLFetchNameValue() to manipulate it.
236 : *
237 : * Note that relatively few formats return any metadata at this time.
238 : *
239 : * This method does the same thing as the C function GDALGetMetadata().
240 : *
241 : * @param pszDomain the domain of interest. Use "" or NULL for the default
242 : * domain.
243 : *
244 : * @return NULL or a string list.
245 : */
246 :
247 92305 : char **GDALMajorObject::GetMetadata(const char *pszDomain)
248 :
249 : {
250 92305 : return oMDMD.GetMetadata(pszDomain);
251 : }
252 :
253 : /************************************************************************/
254 : /* GDALGetMetadata() */
255 : /************************************************************************/
256 :
257 : /**
258 : * \brief Fetch metadata.
259 : *
260 : * @see GDALMajorObject::GetMetadata()
261 : */
262 :
263 15339 : char **CPL_STDCALL GDALGetMetadata(GDALMajorObjectH hObject,
264 : const char *pszDomain)
265 :
266 : {
267 15339 : VALIDATE_POINTER1(hObject, "GDALGetMetadata", nullptr);
268 :
269 15339 : return GDALMajorObject::FromHandle(hObject)->GetMetadata(pszDomain);
270 : }
271 :
272 : /************************************************************************/
273 : /* SetMetadata() */
274 : /************************************************************************/
275 :
276 : /**
277 : * \brief Set metadata.
278 : *
279 : * The C function GDALSetMetadata() does the same thing as this method.
280 : *
281 : * @param papszMetadataIn the metadata in name=value string list format to
282 : * apply.
283 : * @param pszDomain the domain of interest. Use "" or NULL for the default
284 : * domain.
285 : * @return CE_None on success, CE_Failure on failure and CE_Warning if the
286 : * metadata has been accepted, but is likely not maintained persistently
287 : * by the underlying object between sessions.
288 : */
289 :
290 11527 : CPLErr GDALMajorObject::SetMetadata(char **papszMetadataIn,
291 : const char *pszDomain)
292 :
293 : {
294 11527 : nFlags |= GMO_MD_DIRTY;
295 11527 : return oMDMD.SetMetadata(papszMetadataIn, pszDomain);
296 : }
297 :
298 : /************************************************************************/
299 : /* GDALSetMetadata() */
300 : /************************************************************************/
301 :
302 : /**
303 : * \brief Set metadata.
304 : *
305 : * CAUTION: when using this function on a GDALDatasetH or GDALRasterBandH,
306 : * depending on the format, older values of the updated information might
307 : * still be found in the file in a "ghost" state, even if no longer accessible
308 : * through the GDAL API. This is for example the case of the GTiff format (this
309 : * is not a exhaustive list)
310 : *
311 : * @see GDALMajorObject::SetMetadata(), GDALDataset::SetMetadata(),
312 : * GDALRasterBand::SetMetadata()
313 : */
314 :
315 907 : CPLErr CPL_STDCALL GDALSetMetadata(GDALMajorObjectH hObject,
316 : CSLConstList papszMD, const char *pszDomain)
317 :
318 : {
319 907 : VALIDATE_POINTER1(hObject, "GDALSetMetadata", CE_Failure);
320 :
321 1814 : return GDALMajorObject::FromHandle(hObject)->SetMetadata(
322 907 : const_cast<char **>(papszMD), pszDomain);
323 : }
324 :
325 : /************************************************************************/
326 : /* GetMetadataItem() */
327 : /************************************************************************/
328 :
329 : /**
330 : * \brief Fetch single metadata item.
331 : *
332 : * The C function GDALGetMetadataItem() does the same thing as this method.
333 : *
334 : * @param pszName the key for the metadata item to fetch.
335 : * @param pszDomain the domain to fetch for, use NULL for the default domain.
336 : *
337 : * @return NULL on failure to find the key, or a pointer to an internal
338 : * copy of the value string on success.
339 : */
340 :
341 10345900 : const char *GDALMajorObject::GetMetadataItem(const char *pszName,
342 : const char *pszDomain)
343 :
344 : {
345 10345900 : return oMDMD.GetMetadataItem(pszName, pszDomain);
346 : }
347 :
348 : /************************************************************************/
349 : /* GDALGetMetadataItem() */
350 : /************************************************************************/
351 :
352 : /**
353 : * \brief Fetch single metadata item.
354 : *
355 : * @see GDALMajorObject::GetMetadataItem()
356 : */
357 :
358 1161500 : const char *CPL_STDCALL GDALGetMetadataItem(GDALMajorObjectH hObject,
359 : const char *pszName,
360 : const char *pszDomain)
361 :
362 : {
363 1161500 : VALIDATE_POINTER1(hObject, "GDALGetMetadataItem", nullptr);
364 :
365 2322990 : return GDALMajorObject::FromHandle(hObject)->GetMetadataItem(pszName,
366 1161500 : pszDomain);
367 : }
368 :
369 : /************************************************************************/
370 : /* SetMetadataItem() */
371 : /************************************************************************/
372 :
373 : /**
374 : * \brief Set single metadata item.
375 : *
376 : * The C function GDALSetMetadataItem() does the same thing as this method.
377 : *
378 : * @param pszName the key for the metadata item to fetch.
379 : * @param pszValue the value to assign to the key.
380 : * @param pszDomain the domain to set within, use NULL for the default domain.
381 : *
382 : * @return CE_None on success, or an error code on failure.
383 : */
384 :
385 3260080 : CPLErr GDALMajorObject::SetMetadataItem(const char *pszName,
386 : const char *pszValue,
387 : const char *pszDomain)
388 :
389 : {
390 3260080 : nFlags |= GMO_MD_DIRTY;
391 3260080 : return oMDMD.SetMetadataItem(pszName, pszValue, pszDomain);
392 : }
393 :
394 : /************************************************************************/
395 : /* GDALSetMetadataItem() */
396 : /************************************************************************/
397 :
398 : /**
399 : * \brief Set single metadata item.
400 : *
401 : * CAUTION: when using this function on a GDALDatasetH or GDALRasterBandH,
402 : * depending on the format, older values of the updated information might
403 : * still be found in the file in a "ghost" state, even if no longer accessible
404 : * through the GDAL API. This is for example the case of the GTiff format (this
405 : * is not a exhaustive list)
406 : *
407 : * @see GDALMajorObject::SetMetadataItem(), GDALDataset::SetMetadataItem(),
408 : * GDALRasterBand::SetMetadataItem()
409 : */
410 :
411 842 : CPLErr CPL_STDCALL GDALSetMetadataItem(GDALMajorObjectH hObject,
412 : const char *pszName,
413 : const char *pszValue,
414 : const char *pszDomain)
415 :
416 : {
417 842 : VALIDATE_POINTER1(hObject, "GDALSetMetadataItem", CE_Failure);
418 :
419 1684 : return GDALMajorObject::FromHandle(hObject)->SetMetadataItem(
420 842 : pszName, pszValue, pszDomain);
421 : }
422 :
423 : /************************************************************************/
424 : /* GetMOFlags() */
425 : /************************************************************************/
426 :
427 : /** Returns the GMO_ flags.
428 : * @return flags
429 : */
430 2063320 : int GDALMajorObject::GetMOFlags() const
431 :
432 : {
433 2063320 : return nFlags;
434 : }
435 :
436 : /************************************************************************/
437 : /* SetMOFlags() */
438 : /************************************************************************/
439 :
440 : /** Assign GMO_flags.
441 : * @param nNewFlags new flags.
442 : */
443 1111420 : void GDALMajorObject::SetMOFlags(int nNewFlags)
444 :
445 : {
446 1111420 : nFlags = nNewFlags;
447 1111420 : }
|
