1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2 * Copyright by The HDF Group. *
3 * Copyright by the Board of Trustees of the University of Illinois. *
4 * All rights reserved. *
5 * *
6 * This file is part of HDF5. The full HDF5 copyright notice, including *
7 * terms governing use, modification, and redistribution, is contained in *
8 * the COPYING file, which can be found at the root of the source code *
9 * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. *
10 * If you do not have access to either file, you may request a copy from *
11 * help@hdfgroup.org. *
12 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
13
14 #include <string>
15 #include <iostream>
16 using namespace std;
17
18 #include "H5private.h" // for HDmemset
19 #include "H5Include.h"
20 #include "H5Exception.h"
21 #include "H5IdComponent.h"
22 #include "H5DataSpace.h"
23 #include "H5PropList.h"
24 #include "H5FaccProp.h"
25 #include "H5FcreatProp.h"
26 #include "H5OcreatProp.h"
27 #include "H5DcreatProp.h"
28 #include "H5DxferProp.h"
29 #include "H5LcreatProp.h"
30 #include "H5LaccProp.h"
31 #include "H5DaccProp.h"
32 #include "H5Location.h"
33 #include "H5Object.h"
34 #include "H5DataType.h"
35 #include "H5AbstractDs.h"
36 #include "H5DataSet.h"
37 #include "H5CommonFG.h"
38 #include "H5Group.h"
39 #include "H5File.h"
40
41 namespace H5 {
42
43 #ifndef DOXYGEN_SHOULD_SKIP_THIS
44 //--------------------------------------------------------------------------
45 // Function: H5Location default constructor (protected)
46 // Programmer Binh-Minh Ribler - 2000
47 //--------------------------------------------------------------------------
H5Location()48 H5Location::H5Location() : IdComponent() {}
49
50 //--------------------------------------------------------------------------
51 // Function: H5Location overloaded constructor (protected)
52 // Purpose Creates an H5Location object using the id of an existing HDF5
53 // object.
54 // Parameters object_id - IN: Id of an existing HDF5 object
55 // Programmer Binh-Minh Ribler - 2000
56
57 // *** Deprecation warning ***
58 // This constructor is no longer appropriate because the data member "id" had
59 // been moved to the sub-classes. It will be removed in 1.10 release. If its
60 // removal does not raise any problems in 1.10, it will be removed from 1.8 in
61 // subsequent releases.
62 // Removed in 1.10.1 - Aug 2016
63 //--------------------------------------------------------------------------
64 // H5Location::H5Location(const hid_t object_id) : IdComponent() {}
65
66 //--------------------------------------------------------------------------
67 // Function: H5Location copy constructor
68 // Purpose This noop copy constructor is removed as a result of the data
69 // member "id" being moved down to sub-classes. (Mar 2015)
70 ///\param original - IN: H5Location instance to copy
71 // Programmer Binh-Minh Ribler - 2000
72 //
73 // *** Deprecation warning ***
74 // This constructor is no longer appropriate because the data member "id" had
75 // been moved to the sub-classes. It is removed from 1.8.15 because it is
76 // a noop and it can be generated by the compiler if needed.
77 //--------------------------------------------------------------------------
78 // H5Location::H5Location(const H5Location& original) : IdComponent() {}
79
80 #endif // DOXYGEN_SHOULD_SKIP_THIS
81
82 //--------------------------------------------------------------------------
83 // Function: H5Location::nameExists
84 ///\brief Checks if a link of a given name exists in a location
85 ///\param name - IN: Searched name
86 ///\param lapl - IN: Link access property list
87 ///\exception H5::LocationException
88 // Modification
89 // Renamed from exists() in 1.10.2 -BMR
90 //--------------------------------------------------------------------------
nameExists(const char * name,const LinkAccPropList & lapl) const91 bool H5Location::nameExists(const char* name, const LinkAccPropList& lapl) const
92 {
93 htri_t ret_value = H5Lexists(getId(), name, lapl.getId());
94 if (ret_value > 0)
95 return true;
96 else if (ret_value == 0)
97 return false;
98 else // Raise exception when H5Lexists returns a negative value
99 {
100 throw LocationException(inMemFunc("nameExists"), "H5Lexists failed");
101 }
102 }
103
104 //--------------------------------------------------------------------------
105 // Function: H5Location::nameExists
106 ///\brief Checks if a link of a given name exists in a location
107 ///\param name - IN: Searched name
108 ///\param lapl - IN: Link access property list
109 ///\exception H5::LocationException
110 // Modification
111 // Renamed from exists() in 1.10.2 -BMR
112 //--------------------------------------------------------------------------
nameExists(const H5std_string & name,const LinkAccPropList & lapl) const113 bool H5Location::nameExists(const H5std_string& name, const LinkAccPropList& lapl) const
114 {
115 return(nameExists(name.c_str(), lapl));
116 }
117
118 //--------------------------------------------------------------------------
119 // Function: H5Location::exists - Deprecated
120 // Purpose Checks if a link of a given name exists in a location
121 ///\brief Deprecated in favor of nameExists
122 ///\param name - IN: Searched name
123 ///\param lapl - IN: Link access property list
124 ///\exception H5::LocationException
125 // Programmer Binh-Minh Ribler - Nov, 2016
126 // Modification
127 // Renamed to nameExists() in 1.10.2 -BMR
128 //--------------------------------------------------------------------------
exists(const char * name,const LinkAccPropList & lapl) const129 bool H5Location::exists(const char* name, const LinkAccPropList& lapl) const
130 {
131 return(nameExists(name, lapl));
132 }
133
134 //--------------------------------------------------------------------------
135 // Function: H5Location::exists - Deprecated
136 // Purpose Checks if a link of a given name exists in a location
137 ///\brief Deprecated in favor of nameExists
138 ///\param name - IN: Searched name
139 ///\param lapl - IN: Link access property list
140 ///\exception H5::LocationException
141 // Programmer Binh-Minh Ribler - Dec, 2016
142 // Modification
143 // Renamed to nameExists() in 1.10.2 -BMR
144 //--------------------------------------------------------------------------
exists(const H5std_string & name,const LinkAccPropList & lapl) const145 bool H5Location::exists(const H5std_string& name, const LinkAccPropList& lapl) const
146 {
147 return(nameExists(name.c_str(), lapl));
148 }
149
150 //--------------------------------------------------------------------------
151 // Function: H5Location::flush
152 ///\brief Flushes all buffers associated with a location to disk.
153 ///\param scope - IN: Specifies the scope of the flushing action,
154 /// which can be either of these values:
155 /// \li \c H5F_SCOPE_GLOBAL - Flushes the entire virtual file
156 /// \li \c H5F_SCOPE_LOCAL - Flushes only the specified file
157 ///\exception H5::LocationException
158 ///\par Description
159 /// This location is used to identify the file to be flushed.
160 // Programmer Binh-Minh Ribler - 2012
161 // Modification
162 // Sep 2012 - BMR
163 // Moved from H5File/H5Object
164 //--------------------------------------------------------------------------
flush(H5F_scope_t scope) const165 void H5Location::flush(H5F_scope_t scope) const
166 {
167 herr_t ret_value = H5Fflush(getId(), scope);
168 if (ret_value < 0)
169 {
170 throw LocationException(inMemFunc("flush"), "H5Fflush failed");
171 }
172 }
173
174 //--------------------------------------------------------------------------
175 // Function: H5Location::getFileName
176 ///\brief Gets the name of the file, in which an HDF5 object at this
177 /// location belongs.
178 ///\return File name
179 ///\exception H5::LocationException
180 // Programmer Binh-Minh Ribler - Jul, 2004
181 //--------------------------------------------------------------------------
getFileName() const182 H5std_string H5Location::getFileName() const
183 {
184 try {
185 return(p_get_file_name());
186 }
187 catch (IdComponentException& E) {
188 throw LocationException(inMemFunc("getFileName"), E.getDetailMsg());
189 }
190 }
191
192 //--------------------------------------------------------------------------
193 // Function: H5Location::setComment
194 ///\brief Sets or resets the comment for an object specified by its name.
195 ///\param name - IN: Name of the object
196 ///\param comment - IN: New comment
197 ///\exception H5::LocationException
198 ///\par Description
199 /// If \a comment is an empty string or a null pointer, the comment
200 /// message is removed from the object.
201 /// Comments should be relatively short, null-terminated, ASCII
202 /// strings. They can be attached to any object that has an
203 /// object header, e.g., data sets, groups, named data types,
204 /// and data spaces, but not symbolic links.
205 // Programmer Binh-Minh Ribler - 2000 (moved from CommonFG, Sep 2013)
206 // Modification
207 // 2007: QAK modified to use H5O APIs; however the first parameter is
208 // no longer just file or group, this function should be moved
209 // to another class to accommodate attribute, dataset, and named
210 // datatype. - BMR
211 //--------------------------------------------------------------------------
setComment(const char * name,const char * comment) const212 void H5Location::setComment(const char* name, const char* comment) const
213 {
214 herr_t ret_value = H5Oset_comment_by_name(getId(), name, comment, H5P_DEFAULT);
215 if (ret_value < 0)
216 throw LocationException(inMemFunc("setComment"), "H5Oset_comment_by_name failed");
217 }
218
219 //--------------------------------------------------------------------------
220 // Function: H5Location::setComment
221 ///\brief This is an overloaded member function, provided for convenience.
222 /// It differs from the above function in that it takes an
223 /// \c H5std_string for \a name and \a comment.
224 // Programmer Binh-Minh Ribler - 2000 (moved from CommonFG, Sep 2013)
225 //--------------------------------------------------------------------------
setComment(const H5std_string & name,const H5std_string & comment) const226 void H5Location::setComment(const H5std_string& name, const H5std_string& comment) const
227 {
228 setComment(name.c_str(), comment.c_str());
229 }
230
231 //--------------------------------------------------------------------------
232 // Function: H5Location::setComment
233 ///\brief This is an overloaded member function, provided for convenience.
234 /// It differs from the above function in that it doesn't take
235 /// an object name.
236 // Programmer Binh-Minh Ribler - Sep 2013
237 //--------------------------------------------------------------------------
setComment(const char * comment) const238 void H5Location::setComment(const char* comment) const
239 {
240 herr_t ret_value = H5Oset_comment_by_name(getId(), ".", comment, H5P_DEFAULT);
241 if (ret_value < 0)
242 throw LocationException(inMemFunc("setComment"), "H5Oset_comment_by_name failed");
243 }
244
245 //--------------------------------------------------------------------------
246 // Function: H5Location::setComment
247 ///\brief This is an overloaded member function, provided for convenience.
248 /// It differs from the above function in that it takes an
249 /// \c H5std_string for \a comment.
250 // Programmer Binh-Minh Ribler - Sep 2013
251 //--------------------------------------------------------------------------
setComment(const H5std_string & comment) const252 void H5Location::setComment(const H5std_string& comment) const
253 {
254 setComment(comment.c_str());
255 }
256
257 //--------------------------------------------------------------------------
258 // Function: H5Location::removeComment
259 ///\brief Removes the comment from an object specified by its name.
260 ///\param name - IN: Name of the object
261 ///\exception H5::LocationException
262 // Programmer Binh-Minh Ribler - May 2005 (moved from CommonFG, Sep 2013)
263 // 2007: QAK modified to use H5O APIs; however the first parameter is
264 // no longer just file or group, this function should be moved
265 // to another class to accommodate attribute, dataset, and named
266 // datatype. - BMR
267 //--------------------------------------------------------------------------
removeComment(const char * name) const268 void H5Location::removeComment(const char* name) const
269 {
270 herr_t ret_value = H5Oset_comment_by_name(getId(), name, NULL, H5P_DEFAULT);
271 if (ret_value < 0)
272 throw LocationException(inMemFunc("removeComment"), "H5Oset_comment_by_name failed");
273 }
274
275 //--------------------------------------------------------------------------
276 // Function: H5Location::removeComment
277 ///\brief This is an overloaded member function, provided for convenience.
278 /// It differs from the above function in that it takes an
279 /// \c H5std_string for \a name.
280 // Programmer Binh-Minh Ribler - May 2005 (moved from CommonFG, Sep 2013)
281 //--------------------------------------------------------------------------
removeComment(const H5std_string & name) const282 void H5Location::removeComment(const H5std_string& name) const
283 {
284 removeComment (name.c_str());
285 }
286
287 //--------------------------------------------------------------------------
288 // Function: H5Location::getComment
289 ///\brief Retrieves the comment for this location, returning its length.
290 ///\param name - IN: Name of the object
291 ///\param buf_size - IN: Length of the comment to retrieve
292 ///\param comment - OUT: Retrieved comment
293 ///\return Actual length of the comment
294 ///\exception H5::LocationException
295 ///\par Description
296 /// This function retrieves \a buf_size characters of the comment
297 /// including the null terminator. Thus, if the actual length
298 /// of the comment is more than buf_size-1, the retrieved comment
299 /// will be truncated to accommodate the null terminator.
300 // Programmer Binh-Minh Ribler - Mar 2014
301 //--------------------------------------------------------------------------
getComment(const char * name,size_t buf_size,char * comment) const302 ssize_t H5Location::getComment(const char* name, size_t buf_size, char* comment) const
303 {
304 // H5Oget_comment_by_name will get buf_size chars of the comment including
305 // the null terminator
306 ssize_t comment_len;
307 comment_len = H5Oget_comment_by_name(getId(), name, comment, buf_size, H5P_DEFAULT);
308
309 // If H5Oget_comment_by_name returns a negative value, raise an exception
310 if (comment_len < 0)
311 {
312 throw LocationException("H5Location::getComment", "H5Oget_comment_by_name failed");
313 }
314 // If the comment is longer than the provided buffer size, the C library
315 // will not null terminate it
316 if (static_cast<size_t>(comment_len) >= buf_size)
317 comment[buf_size-1] = '\0';
318
319 // Return the actual comment length, which might be different from buf_size
320 return(comment_len);
321 }
322
323 //--------------------------------------------------------------------------
324 // Function: H5Location::getComment
325 ///\brief Returns the comment as \a string for this location,
326 /// returning its length.
327 ///\param name - IN: Name of the object
328 ///\param buf_size - IN: Length of the comment to retrieve, default to 0
329 ///\return Comment string
330 ///\exception H5::LocationException
331 // Programmer Binh-Minh Ribler - 2000 (moved from CommonFG, Sep 2013)
332 //--------------------------------------------------------------------------
getComment(const char * name,size_t buf_size) const333 H5std_string H5Location::getComment(const char* name, size_t buf_size) const
334 {
335 // Initialize string to "", so that if there is no comment, the returned
336 // string will be empty
337 H5std_string comment("");
338
339 // Preliminary call to get the comment's length
340 ssize_t comment_len = H5Oget_comment_by_name(getId(), name, NULL, (size_t)0, H5P_DEFAULT);
341
342 // If H5Oget_comment_by_name returns a negative value, raise an exception
343 if (comment_len < 0)
344 {
345 throw LocationException("H5Location::getComment", "H5Oget_comment_by_name failed");
346 }
347
348 // If comment exists, calls C routine again to get it
349 else if (comment_len > 0)
350 {
351 size_t tmp_len = buf_size;
352
353 // If buffer size is not provided, use comment length
354 if (tmp_len == 0)
355 tmp_len = comment_len;
356
357 // Temporary buffer for char* comment
358 char* comment_C = new char[tmp_len+1];
359 HDmemset(comment_C, 0, tmp_len+1); // clear buffer
360
361 // Used overloaded function
362 ssize_t temp_len = getComment(name, tmp_len+1, comment_C);
363 if (temp_len < 0)
364 {
365 delete []comment_C;
366 throw LocationException("H5Location::getComment", "H5Oget_comment_by_name failed");
367 }
368
369 // Convert the C comment to return
370 comment = comment_C;
371
372 // Clean up resource
373 delete []comment_C;
374 }
375
376 // Return the string comment
377 return(comment);
378 }
379
380 //--------------------------------------------------------------------------
381 // Function: H5Location::getComment
382 ///\brief This is an overloaded member function, provided for convenience.
383 /// It differs from the above function in that it takes an
384 /// \c H5std_string for \a name.
385 // Programmer Binh-Minh Ribler - 2000 (moved from CommonFG, Sep 2013)
386 //--------------------------------------------------------------------------
getComment(const H5std_string & name,size_t buf_size) const387 H5std_string H5Location::getComment(const H5std_string& name, size_t buf_size) const
388 {
389 return(getComment(name.c_str(), buf_size));
390 }
391 #ifndef DOXYGEN_SHOULD_SKIP_THIS
392
393 //--------------------------------------------------------------------------
394 // Function: H5Location::p_reference (protected)
395 // Purpose Creates a reference to an HDF5 object or a dataset region.
396 // Parameters
397 // name - IN: Name of the object to be referenced
398 // dataspace - IN: Dataspace with selection
399 // ref_type - IN: Type of reference; default to \c H5R_DATASET_REGION
400 // Exception H5::ReferenceException
401 // Programmer Binh-Minh Ribler - May, 2004
402 //--------------------------------------------------------------------------
p_reference(void * ref,const char * name,hid_t space_id,H5R_type_t ref_type) const403 void H5Location::p_reference(void* ref, const char* name, hid_t space_id, H5R_type_t ref_type) const
404 {
405 herr_t ret_value = H5Rcreate(ref, getId(), name, ref_type, space_id);
406 if (ret_value < 0)
407 {
408 throw ReferenceException(inMemFunc("reference"), "H5Rcreate failed");
409 }
410 }
411
412 #endif // DOXYGEN_SHOULD_SKIP_THIS
413
414 //--------------------------------------------------------------------------
415 // Function: H5Location::reference
416 ///\brief Creates a reference to an HDF5 object or a dataset region.
417 ///\param ref - IN: Reference pointer
418 ///\param name - IN: Name of the object to be referenced
419 ///\param dataspace - IN: Dataspace with selection
420 ///\param ref_type - IN: Type of reference to query, valid values are:
421 /// \li \c H5R_OBJECT - Reference is an object reference.
422 /// \li \c H5R_DATASET_REGION - Reference is a dataset region
423 /// reference. (default)
424 ///\exception H5::ReferenceException
425 ///\note This method is more suitable for a dataset region reference.
426 // Programmer Binh-Minh Ribler - May, 2004
427 //--------------------------------------------------------------------------
reference(void * ref,const char * name,const DataSpace & dataspace,H5R_type_t ref_type) const428 void H5Location::reference(void* ref, const char* name, const DataSpace& dataspace, H5R_type_t ref_type) const
429 {
430 try {
431 p_reference(ref, name, dataspace.getId(), ref_type);
432 }
433 catch (ReferenceException& E) {
434 throw ReferenceException(inMemFunc("reference"), E.getDetailMsg());
435 }
436 }
437
438 //--------------------------------------------------------------------------
439 // Function: H5Location::reference
440 ///\brief This is an overloaded member function, provided for convenience.
441 /// It differs from the above function in that it takes an
442 /// \c H5std_string for \a name.
443 ///\param ref - IN: Reference pointer
444 ///\param name - IN: Name of the object to be referenced
445 ///\param dataspace - IN: Dataspace with selection
446 ///\param ref_type - IN: Type of reference to query, valid values are:
447 /// \li \c H5R_OBJECT - Reference is an object reference.
448 /// \li \c H5R_DATASET_REGION - Reference is a dataset region
449 /// reference. (default)
450 ///\exception H5::ReferenceException
451 ///\note This method is more suitable for a dataset region reference.
452 // Programmer Binh-Minh Ribler - May, 2004
453 //--------------------------------------------------------------------------
reference(void * ref,const H5std_string & name,const DataSpace & dataspace,H5R_type_t ref_type) const454 void H5Location::reference(void* ref, const H5std_string& name, const DataSpace& dataspace, H5R_type_t ref_type) const
455 {
456 try {
457 p_reference(ref, name.c_str(), dataspace.getId(), ref_type);
458 }
459 catch (ReferenceException& E) {
460 throw ReferenceException(inMemFunc("reference"), E.getDetailMsg());
461 }
462 }
463
464 //--------------------------------------------------------------------------
465 // Function: H5Location::reference
466 ///\brief This is an overloaded function, provided for your convenience.
467 /// It differs from the above function in that it does not take
468 /// a DataSpace object and the reference type must be specified.
469 ///\param ref - IN: Reference pointer
470 ///\param name - IN: Name of the object to be referenced
471 ///\param ref_type - IN: Type of reference to query, valid values are:
472 /// \li \c H5R_OBJECT - Reference is an object reference (default)
473 /// \li \c H5R_DATASET_REGION - Reference is a dataset region
474 ///\exception H5::ReferenceException
475 ///\note This method is more suitable for an object reference.
476 // Programmer Binh-Minh Ribler - May, 2004
477 //--------------------------------------------------------------------------
reference(void * ref,const char * name,H5R_type_t ref_type) const478 void H5Location::reference(void* ref, const char* name, H5R_type_t ref_type) const
479 {
480 try {
481 p_reference(ref, name, -1, ref_type);
482 }
483 catch (ReferenceException& E) {
484 throw ReferenceException(inMemFunc("reference"), E.getDetailMsg());
485 }
486 }
487
488 //--------------------------------------------------------------------------
489 // Function: H5Location::reference
490 ///\brief This is an overloaded function, provided for your convenience.
491 /// It differs from the above function in that it takes an
492 /// \c H5std_string for the object's name.
493 ///\param ref - IN: Reference pointer
494 ///\param name - IN: Name of the object to be referenced - \c H5std_string
495 ///\param ref_type - IN: Type of reference to query, valid values are:
496 /// \li \c H5R_OBJECT - Reference is an object reference (default)
497 /// \li \c H5R_DATASET_REGION - Reference is a dataset region
498 ///\note This method is more suitable for an object reference.
499 // Programmer Binh-Minh Ribler - May, 2004
500 //--------------------------------------------------------------------------
reference(void * ref,const H5std_string & name,H5R_type_t ref_type) const501 void H5Location::reference(void* ref, const H5std_string& name, H5R_type_t ref_type) const
502 {
503 reference(ref, name.c_str(), ref_type);
504 }
505
506 #ifndef DOXYGEN_SHOULD_SKIP_THIS
507 //--------------------------------------------------------------------------
508 // Function: H5Location::p_dereference (protected)
509 // Purpose Dereference a ref into an hdf5 object.
510 // Parameters
511 // loc_id - IN: An hdf5 identifier specifying the location of the
512 // referenced object
513 // ref - IN: Reference pointer
514 // ref_type - IN: Reference type
515 // plist - IN: Property list - default to PropList::DEFAULT
516 // from_func - IN: Name of the calling function
517 // Exception H5::ReferenceException
518 // Programmer Binh-Minh Ribler - Oct, 2006
519 //--------------------------------------------------------------------------
p_dereference(hid_t loc_id,const void * ref,H5R_type_t ref_type,const PropList & plist,const char * from_func)520 hid_t H5Location::p_dereference(hid_t loc_id, const void* ref, H5R_type_t ref_type, const PropList& plist, const char* from_func)
521 {
522 hid_t plist_id;
523 if (p_valid_id(plist.getId()))
524 plist_id = plist.getId();
525 else
526 plist_id = H5P_DEFAULT;
527
528 hid_t temp_id = H5Rdereference2(loc_id, plist_id, ref_type, ref);
529 if (temp_id < 0)
530 {
531 throw ReferenceException(inMemFunc(from_func), "H5Rdereference2 failed");
532 }
533
534 return(temp_id);
535 }
536 #endif // DOXYGEN_SHOULD_SKIP_THIS
537
538 //--------------------------------------------------------------------------
539 // Function: H5Location::dereference
540 ///\brief Dereferences a reference into an HDF5 object, given an HDF5 object.
541 ///\param loc - IN: Location of the referenced object
542 ///\param ref - IN: Reference pointer
543 ///\param ref_type - IN: Reference type
544 ///\param plist - IN: Property list - default to PropList::DEFAULT
545 ///\exception H5::ReferenceException
546 // Programmer Binh-Minh Ribler - Oct, 2006
547 //--------------------------------------------------------------------------
dereference(const H5Location & loc,const void * ref,H5R_type_t ref_type,const PropList & plist)548 void H5Location::dereference(const H5Location& loc, const void* ref, H5R_type_t ref_type, const PropList& plist)
549 {
550 p_setId(p_dereference(loc.getId(), ref, ref_type, plist, "dereference"));
551 }
552
553 //--------------------------------------------------------------------------
554 // Function: H5Location::dereference
555 // brief Dereferences a reference into an HDF5 object, given an attribute.
556 // param attr - IN: Attribute specifying the location of the referenced object
557 // param ref - IN: Reference pointer
558 // param ref_type - IN: Reference type
559 // param plist - IN: Property list - default to PropList::DEFAULT
560 // exception H5::ReferenceException
561 // Programmer Binh-Minh Ribler - Oct, 2006
562 // Modification
563 // Mar, 2017
564 // Removed in 1.10.1 because H5Location is Attribute's baseclass
565 // now. -BMR
566 //--------------------------------------------------------------------------
567 /* void H5Location::dereference(const Attribute& attr, const void* ref, H5R_type_t ref_type, const PropList& plist)
568 {
569 p_setId(p_dereference(attr.getId(), ref, ref_type, plist, "dereference"));
570 }
571 */
572
573 #ifndef H5_NO_DEPRECATED_SYMBOLS
574 //--------------------------------------------------------------------------
575 // Function: H5Location::getObjType
576 ///\brief Retrieves the type of object that an object reference points to.
577 ///\param ref_type - IN: Type of reference to query, valid values are:
578 /// \li \c H5R_OBJECT - Reference is an object reference.
579 /// \li \c H5R_DATASET_REGION - Reference is a dataset region reference.
580 ///\param ref - IN: Reference to query
581 ///\return An object type, which can be one of the following:
582 /// \li \c H5G_UNKNOWN - A failure occurs. (-1)
583 /// \li \c H5G_GROUP - Object is a group.
584 /// \li \c H5G_DATASET - Object is a dataset.
585 /// \li \c H5G_TYPE Object - is a named datatype
586 /// \li \c H5G_LINK - Object is a symbolic link.
587 /// \li \c H5G_UDLINK - Object is a user-defined link.
588 ///\exception H5::ReferenceException
589 // Programmer Binh-Minh Ribler - May, 2004
590 // Modification
591 // Sep 2012: Moved up from H5File, Group, DataSet, and DataType
592 //--------------------------------------------------------------------------
getObjType(void * ref,H5R_type_t ref_type) const593 H5G_obj_t H5Location::getObjType(void *ref, H5R_type_t ref_type) const
594 {
595 try {
596 return(p_get_obj_type(ref, ref_type));
597 }
598 catch (ReferenceException& E) {
599 throw ReferenceException(inMemFunc("getObjType"), E.getDetailMsg());
600 }
601 }
602
603 #ifndef DOXYGEN_SHOULD_SKIP_THIS
604 //--------------------------------------------------------------------------
605 // Function: H5Location::p_get_obj_type (protected)
606 // Purpose Retrieves the type of object that an object reference points to.
607 // Parameters
608 // ref - IN: Reference to query
609 // ref_type - IN: Type of reference to query
610 // Return An object type, which can be one of the following:
611 // H5G_UNKNOWN \tFailure occurs (-1)
612 // H5G_GROUP \tObject is a group.
613 // H5G_DATASET \tObject is a dataset.
614 // H5G_TYPE Object \tis a named datatype.
615 // H5G_LINK \tObject is a symbolic link.
616 // H5G_UDLINK \tObject is a user-defined link.
617 // Exception H5::ReferenceException
618 // Programmer Binh-Minh Ribler - May, 2004
619 //--------------------------------------------------------------------------
p_get_obj_type(void * ref,H5R_type_t ref_type) const620 H5G_obj_t H5Location::p_get_obj_type(void *ref, H5R_type_t ref_type) const
621 {
622 H5G_obj_t obj_type = H5Rget_obj_type1(getId(), ref_type, ref);
623 if (obj_type == H5G_UNKNOWN)
624 {
625 throw ReferenceException(inMemFunc("getObjType"), "H5Rget_obj_type1 failed");
626 }
627 return(obj_type);
628 }
629 #endif // DOXYGEN_SHOULD_SKIP_THIS
630 #endif /* H5_NO_DEPRECATED_SYMBOLS */
631
632 //--------------------------------------------------------------------------
633 // Function: H5Location::getRefObjType
634 ///\brief Retrieves the type of object that an object reference points to.
635 ///\param ref - IN: Reference to query
636 ///\param ref_type - IN: Type of reference to query, valid values are:
637 /// \li \c H5R_OBJECT - Reference is an object reference.
638 /// \li \c H5R_DATASET_REGION - Reference is a dataset region reference.
639 ///\return An object type, which can be one of the following:
640 /// \li \c H5O_TYPE_UNKNOWN - Unknown object type (-1)
641 /// \li \c H5O_TYPE_GROUP - Object is a group
642 /// \li \c H5O_TYPE_DATASET - Object is a dataset
643 /// \li \c H5O_TYPE_NAMED_DATATYPE - Object is a named datatype
644 /// \li \c H5O_TYPE_NTYPES - Number of different object types
645 ///\exception H5::ReferenceException
646 // Programmer Binh-Minh Ribler - May, 2004
647 //--------------------------------------------------------------------------
getRefObjType(void * ref,H5R_type_t ref_type) const648 H5O_type_t H5Location::getRefObjType(void *ref, H5R_type_t ref_type) const
649 {
650 try {
651 return(p_get_ref_obj_type(ref, ref_type));
652 }
653 catch (ReferenceException& E) {
654 throw ReferenceException(inMemFunc("getRefObjType"), E.getDetailMsg());
655 }
656 }
657
658 #ifndef DOXYGEN_SHOULD_SKIP_THIS
659 //--------------------------------------------------------------------------
660 // Function: H5Location::p_get_ref_obj_type (protected)
661 // Purpose Retrieves the type of object that an object reference points to.
662 // Parameters
663 // ref - IN: Reference to query
664 // ref_type - IN: Type of reference to query
665 // Return An object type, which can be one of the following:
666 // H5O_TYPE_UNKNOWN - Unknown object type (-1)
667 // H5O_TYPE_GROUP - Object is a group
668 // H5O_TYPE_DATASET - Object is a dataset
669 // H5O_TYPE_NAMED_DATATYPE - Object is a named datatype
670 // H5O_TYPE_NTYPES - Number of object types
671 // Exception H5::ReferenceException
672 // Programmer Binh-Minh Ribler - May, 2004
673 //--------------------------------------------------------------------------
p_get_ref_obj_type(void * ref,H5R_type_t ref_type) const674 H5O_type_t H5Location::p_get_ref_obj_type(void *ref, H5R_type_t ref_type) const
675 {
676 H5O_type_t obj_type = H5O_TYPE_UNKNOWN;
677 herr_t ret_value = H5Rget_obj_type2(getId(), ref_type, ref, &obj_type);
678 if (ret_value < 0)
679 {
680 throw ReferenceException(inMemFunc("getRefObjType"), "H5Rget_obj_type2 failed");
681 }
682 if (obj_type == H5O_TYPE_UNKNOWN || obj_type >= H5O_TYPE_NTYPES)
683 {
684 throw ReferenceException(inMemFunc("getRefObjType"), "H5Rget_obj_type2 returned invalid type");
685 }
686 return(obj_type);
687 }
688
689
690 //--------------------------------------------------------------------------
691 // Function: H5Location::getRegion
692 ///\brief Retrieves a dataspace with the region pointed to selected.
693 ///\param ref - IN: Reference to get region of
694 ///\param ref_type - IN: Type of reference to get region of - default
695 // to H5R_DATASET_REGION
696 ///\return DataSpace object
697 ///\exception H5::ReferenceException
698 // Programmer Binh-Minh Ribler - May, 2004
699 // Modification
700 // Mar 29, 2015
701 // Used friend function to set id for DataSpace instead of the
702 // existing id constructor or the setId method to avoid incrementing
703 // ref count, as a work-around for a problem described in the JIRA
704 // issue HDFFV-7947. -BMR
705 //--------------------------------------------------------------------------
getRegion(void * ref,H5R_type_t ref_type) const706 DataSpace H5Location::getRegion(void *ref, H5R_type_t ref_type) const
707 {
708 hid_t space_id = H5Rget_region(getId(), ref_type, ref);
709 if (space_id < 0)
710 {
711 throw ReferenceException(inMemFunc("getRegion"), "H5Rget_region failed");
712 }
713 try {
714 DataSpace dataspace;
715 f_DataSpace_setId(&dataspace, space_id);
716 return(dataspace);
717 }
718 catch (DataSpaceIException& E) {
719 throw ReferenceException(inMemFunc("getRegion"), E.getDetailMsg());
720 }
721 }
722
723
724 // From H5CommonFG.cpp
725 // Notes with "***Updated" are new and for Group.cpp
726 // Original notes are from December 2000
727 //
728 // There are a few comments that are common to most of the functions
729 // defined in this file so they are listed here.
730 // - getLocId is called by all functions, that call a C API, to get
731 // the location id, which can be either a file id or a group id.
732 // This function is pure virtual and it's up to H5File and Group
733 // to call the right getId() - although, as the structure of the
734 // library at this time, getId() is basically the IdComponent::getId()
735 // ***Updated: after the classes are rearranged (HDFFV-9920), functions
736 // in CommonFG are moved to Group, and they can call getId()
737 // instead of getLocId(). getLocId() is kept for backward
738 // compatibility on user applications. Aug 18, 2016 -BMR
739 // ***Updated: Moving to Group was a mistake, now to H5Location
740 // Aug 24, 2016 -BMR
741 // - when a failure returned by the C API, the functions will call
742 // throwException, which is a pure virtual function and is implemented
743 // by H5File to throw a FileIException and by Group to throw a
744 // GroupIException.
745 // ***Updated: after HDFFV-9920, methods in classes H5Location and Group
746 // use throwException to distinguish the FileIException and GroupIException.
747 // CommonFG is no longer used in the library. Aug 18, 2016 -BMR
748 // H5Location::throwException is changed to throw LocationException for any
749 // subclass that is not H5File or Group. Aug 14, 2017 -BMR
750 // ***Note: following the changes in HDFFV-9920, some of the methods could
751 // throw different exceptions, but for backward-compatibility, throwException
752 // is kept in those methods as well. Sep 17, 2016 -BMR
753 //
754
755 //--------------------------------------------------------------------------
756 // Function: H5Location::createGroup
757 ///\brief Creates a new group at this location, which can be a file,
758 /// group, dataset, attribute, or named datatype.
759 ///\param name - IN: Name of the group to create
760 ///\param size_hint - IN: Indicates the number of bytes to reserve for
761 /// the names that will appear in the group
762 ///\return Group instance
763 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
764 ///\par Description
765 /// The optional \a size_hint specifies how much file space to
766 /// reserve for storing the names that will appear in this new
767 /// group. If a non-positive value is provided for the \a size_hint
768 /// then a default size is chosen.
769 // Programmer Binh-Minh Ribler - 2000
770 //--------------------------------------------------------------------------
createGroup(const char * name,const LinkCreatPropList & lcpl) const771 Group H5Location::createGroup(const char* name, const LinkCreatPropList& lcpl) const
772 {
773 // Call C routine H5Gcreate2 to create the named group, giving the
774 // location id which can be a file id or a group id
775 hid_t group_id = H5Gcreate2(getId(), name, lcpl.getId(), H5P_DEFAULT, H5P_DEFAULT);
776
777 // If the creation of the group failed, throw an exception
778 if (group_id < 0)
779 throwException("createGroup", "H5Gcreate2 failed");
780
781 // No failure, create and return the Group object
782 Group group;
783 H5Location *ptr = &group;
784 ptr->p_setId(group_id);
785 return(group);
786 }
787
788 //--------------------------------------------------------------------------
789 // Function: H5Location::createGroup
790 ///\brief This is an overloaded member function, provided for convenience.
791 /// It differs from the above function in that it takes an
792 /// \c H5std_string for \a name.
793 // Programmer Binh-Minh Ribler - 2000
794 //--------------------------------------------------------------------------
createGroup(const H5std_string & name,const LinkCreatPropList & lcpl) const795 Group H5Location::createGroup(const H5std_string& name, const LinkCreatPropList& lcpl) const
796 {
797 return(createGroup( name.c_str(), lcpl));
798 }
799
800 //--------------------------------------------------------------------------
801 // Function: H5Location::createGroup
802 ///\brief Creates a new group at this location, which can be a file,
803 /// group, dataset, attribute, or named datatype.
804 ///\param name - IN: Name of the group to create
805 ///\param size_hint - IN: Indicates the number of bytes to reserve for
806 /// the names that will appear in the group
807 ///\return Group instance
808 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
809 ///\par Description
810 /// The optional \a size_hint specifies how much file space to
811 /// reserve for storing the names that will appear in this new
812 /// group. If a non-positive value is provided for the \a size_hint
813 /// then a default size is chosen.
814 // Programmer Binh-Minh Ribler - 2000
815 //--------------------------------------------------------------------------
createGroup(const char * name,size_t size_hint) const816 Group H5Location::createGroup(const char* name, size_t size_hint) const
817 {
818 // Group creation property list for size hint
819 hid_t gcpl_id = 0;
820
821 // Set the local heap size hint
822 if (size_hint > 0)
823 {
824 // If the creation of the property list failed, throw an exception
825 if ((gcpl_id = H5Pcreate(H5P_GROUP_CREATE)) < 0)
826 throwException("createGroup", "H5Pcreate failed");
827
828 if (H5Pset_local_heap_size_hint(gcpl_id, size_hint) < 0) {
829 H5Pclose(gcpl_id);
830 throwException("createGroup", "H5Pset_local_heap_size_hint failed");
831 }
832 }
833
834 // Call C routine H5Gcreate2 to create the named group, giving the
835 // location id which can be a file id or a group id
836 hid_t group_id = H5Gcreate2(getId(), name, H5P_DEFAULT, gcpl_id, H5P_DEFAULT);
837
838 // Close the group creation property list, if necessary
839 if(gcpl_id > 0)
840 H5Pclose(gcpl_id);
841
842 // If the creation of the group failed, throw an exception
843 if (group_id < 0)
844 throwException("createGroup", "H5Gcreate2 failed");
845
846 // No failure, create and return the Group object
847 Group group;
848 H5Location *ptr = &group;
849 ptr->p_setId(group_id);
850 return(group);
851 }
852
853 //--------------------------------------------------------------------------
854 // Function: H5Location::createGroup
855 ///\brief This is an overloaded member function, provided for convenience.
856 /// It differs from the above function in that it takes an
857 /// \c H5std_string for \a name.
858 // Programmer Binh-Minh Ribler - 2000
859 //--------------------------------------------------------------------------
createGroup(const H5std_string & name,size_t size_hint) const860 Group H5Location::createGroup(const H5std_string& name, size_t size_hint) const
861 {
862 return(createGroup( name.c_str(), size_hint));
863 }
864
865 //--------------------------------------------------------------------------
866 // Function: H5Location::openGroup
867 ///\brief Opens an existing group in a location which can be a file
868 /// or another group.
869 ///\param name - IN: Name of the group to open
870 ///\return Group instance
871 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
872 // Programmer Binh-Minh Ribler - 2000
873 //--------------------------------------------------------------------------
openGroup(const char * name) const874 Group H5Location::openGroup(const char* name) const
875 {
876 // Call C routine H5Gopen2 to open the named group, giving the
877 // location id which can be a file id or a group id
878 hid_t group_id = H5Gopen2(getId(), name, H5P_DEFAULT);
879
880 // If the opening of the group failed, throw an exception
881 if (group_id < 0)
882 throwException("openGroup", "H5Gopen2 failed");
883
884 // No failure, create and return the Group object
885 Group group;
886 //group.p_setId(group_id);
887 H5Location *ptr = &group;
888 ptr->p_setId(group_id);
889 return(group);
890 }
891
892 //--------------------------------------------------------------------------
893 // Function: H5Location::openGroup
894 ///\brief This is an overloaded member function, provided for convenience.
895 /// It differs from the above function in that it takes an
896 /// \c H5std_string for \a name.
897 // Programmer Binh-Minh Ribler - 2000
898 //--------------------------------------------------------------------------
openGroup(const H5std_string & name) const899 Group H5Location::openGroup(const H5std_string& name) const
900 {
901 return(openGroup( name.c_str()));
902 }
903
904 //--------------------------------------------------------------------------
905 // Function: H5Location::createDataSet
906 ///\brief Creates a new dataset at this location.
907 ///\param name - IN: Name of the dataset to create
908 ///\param data_type - IN: Datatype of the dataset
909 ///\param data_space - IN: Dataspace for the dataset
910 ///\param dcpl - IN: Dataset creation properly list
911 ///\param lcpl - IN: Link creation properly list
912 ///\param dapl - IN: Dataset access properly list
913 ///\return DataSet instance
914 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
915 // 2000
916 // Modification:
917 // Jul 2018
918 // Added LinkCreatPropList and DSetAccPropList but did not
919 // follow the order in the C function: lcpl, dcpl, dapl, to
920 // accommodate the existing createDataSet calls.
921 //--------------------------------------------------------------------------
createDataSet(const char * name,const DataType & data_type,const DataSpace & data_space,const DSetCreatPropList & dcpl,const DSetAccPropList & dapl,const LinkCreatPropList & lcpl) const922 DataSet H5Location::createDataSet(const char* name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& dcpl, const DSetAccPropList& dapl, const LinkCreatPropList& lcpl) const
923 {
924 // Obtain identifiers for C API
925 hid_t type_id = data_type.getId();
926 hid_t space_id = data_space.getId();
927 hid_t dcpl_id = dcpl.getId();
928 hid_t lcpl_id = lcpl.getId();
929 hid_t dapl_id = dapl.getId();
930
931 // Call C routine H5Dcreate2 to create the named dataset
932 hid_t dataset_id = H5Dcreate2(getId(), name, type_id, space_id, lcpl_id, dcpl_id, dapl_id);
933
934 // If the creation of the dataset failed, throw an exception
935 if (dataset_id < 0)
936 throwException("createDataSet", "H5Dcreate2 failed");
937
938 // No failure, create and return the DataSet object
939 DataSet dataset;
940 f_DataSet_setId(&dataset, dataset_id);
941 return(dataset);
942 }
943
944 //--------------------------------------------------------------------------
945 // Function: H5Location::createDataSet
946 ///\brief This is an overloaded member function, provided for convenience.
947 /// It differs from the above function in that it takes an
948 /// \c H5std_string for \a name.
949 // 2000
950 // Modification:
951 // Jul 2018
952 // Added LinkCreatPropList and DSetAccPropList but did not
953 // follow the order in the C function: lcpl, dcpl, dapl, to
954 // accommodate the existing createDataSet calls.
955 //--------------------------------------------------------------------------
createDataSet(const H5std_string & name,const DataType & data_type,const DataSpace & data_space,const DSetCreatPropList & dcpl,const DSetAccPropList & dapl,const LinkCreatPropList & lcpl) const956 DataSet H5Location::createDataSet(const H5std_string& name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& dcpl, const DSetAccPropList& dapl, const LinkCreatPropList& lcpl) const
957 {
958 return(createDataSet(name.c_str(), data_type, data_space, dcpl, dapl, lcpl));
959 }
960
961 //--------------------------------------------------------------------------
962 // Function: H5Location::openDataSet
963 ///\brief Opens an existing dataset at this location.
964 ///\param name - IN: Name of the dataset to open
965 ///\return DataSet instance
966 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
967 // 2000
968 // Modification:
969 // Jul 2018
970 // Added DSetAccPropList argument
971 //--------------------------------------------------------------------------
openDataSet(const char * name,const DSetAccPropList & dapl) const972 DataSet H5Location::openDataSet(const char* name, const DSetAccPropList& dapl) const
973 {
974 // Call C function H5Dopen2 to open the specified dataset, giving
975 // the location id and the dataset's name
976 hid_t dapl_id = dapl.getId();
977 hid_t dataset_id = H5Dopen2(getId(), name, dapl_id);
978
979 // If the dataset's opening failed, throw an exception
980 if(dataset_id < 0)
981 throwException("openDataSet", "H5Dopen2 failed");
982
983 // No failure, create and return the DataSet object
984 DataSet dataset;
985 f_DataSet_setId(&dataset, dataset_id);
986 return(dataset);
987 }
988
989 //--------------------------------------------------------------------------
990 // Function: H5Location::openDataSet
991 ///\brief This is an overloaded member function, provided for convenience.
992 /// It differs from the above function in that it takes an
993 /// \c H5std_string for \a name.
994 // 2000
995 // Modification:
996 // Jul 2018
997 // Added DSetAccPropList argument
998 //--------------------------------------------------------------------------
openDataSet(const H5std_string & name,const DSetAccPropList & dapl) const999 DataSet H5Location::openDataSet(const H5std_string& name, const DSetAccPropList& dapl) const
1000 {
1001 return(openDataSet(name.c_str(), dapl));
1002 }
1003
1004 //--------------------------------------------------------------------------
1005 // Function: H5Location::link
1006 ///\brief Creates a soft link from \a link_name to \a target_name.
1007 ///\param target_name - IN: Name of object, can be a non-existing object
1008 ///\param link_name - IN: Link name for the target name
1009 ///\param lcpl - IN: Link creation plist - default to LinkCreatPropList::DEFAULT
1010 ///\param lapl - IN: Link access plist - default to LinkAccPropList::DEFAULT
1011 ///\exception H5::FileIException or H5::GroupIException
1012 ///\par Description
1013 /// Note that both names are interpreted relative to the current
1014 /// location.
1015 /// For information on creating a soft link, please refer to the
1016 /// H5Lcreate_soft APIs in the HDF5 C Reference Manual.
1017 // March 2018
1018 //--------------------------------------------------------------------------
link(const char * target_name,const char * link_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1019 void H5Location::link(const char *target_name, const char *link_name,
1020 const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1021 {
1022 herr_t ret_value = -1;
1023 hid_t lcpl_id = lcpl.getId();
1024 hid_t lapl_id = lapl.getId();
1025
1026 ret_value = H5Lcreate_soft(target_name, getId(), link_name, lcpl_id, lapl_id);
1027 if (ret_value < 0)
1028 throwException("link", "creating soft link failed");
1029 }
1030
1031 //--------------------------------------------------------------------------
1032 // Function: H5Location::link
1033 ///\brief This is an overloaded member function, provided for convenience.
1034 /// It differs from the above function in that it takes an
1035 /// \c H5std_string for \a target_name and \a link_name.
1036 ///\exception H5::FileIException or H5::GroupIException
1037 // March, 2018
1038 //--------------------------------------------------------------------------
link(const H5std_string & target_name,const H5std_string & link_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1039 void H5Location::link(const H5std_string& target_name, const H5std_string&
1040 link_name, const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1041 {
1042 link(target_name.c_str(), link_name.c_str(), lcpl, lapl);
1043 }
1044
1045 //--------------------------------------------------------------------------
1046 // Function: H5Location::link
1047 ///\brief Creates a hard link from \a new_name to \a curr_name.
1048 ///\param curr_name - IN: Name of the existing object
1049 ///\param new_loc - IN: New group or root group
1050 ///\param new_name - IN: New name for the object
1051 ///\param lcpl - IN: Link creation plist - default to LinkCreatPropList::DEFAULT
1052 ///\param lapl - IN: Link access plist - default to LinkAccPropList::DEFAULT
1053 ///\exception H5::FileIException or H5::GroupIException
1054 ///\par Description
1055 /// Note that both names are interpreted relative to the
1056 /// specified location.
1057 /// For information on creating a hard link, please refer to the
1058 /// H5Lcreate_hard APIs in the HDF5 C Reference Manual.
1059 // March 2018
1060 //--------------------------------------------------------------------------
link(const char * curr_name,const Group & new_loc,const char * new_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1061 void H5Location::link(const char *curr_name, const Group& new_loc,
1062 const char *new_name, const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1063 {
1064 herr_t ret_value = -1;
1065 hid_t new_loc_id = new_loc.getId();
1066 hid_t lcpl_id = lcpl.getId();
1067 hid_t lapl_id = lapl.getId();
1068
1069 ret_value = H5Lcreate_hard(getId(), curr_name, new_loc.getId(), new_name, H5P_DEFAULT, H5P_DEFAULT);
1070 if (ret_value < 0)
1071 throwException("link", "creating link failed");
1072 }
1073
1074 //--------------------------------------------------------------------------
1075 // Function: H5Location::link
1076 ///\brief This is an overloaded member function, provided for convenience.
1077 /// It differs from the above function in that it takes an
1078 /// \c H5std_string for \a curr_name and \a new_name.
1079 ///\exception H5::FileIException or H5::GroupIException
1080 // March, 2018
1081 //--------------------------------------------------------------------------
link(const H5std_string & curr_name,const Group & new_loc,const H5std_string & new_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1082 void H5Location::link(const H5std_string& curr_name, const Group& new_loc,
1083 const H5std_string& new_name, const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1084 {
1085 link(curr_name.c_str(), new_loc, new_name.c_str(), lcpl, lapl);
1086 }
1087
1088 //--------------------------------------------------------------------------
1089 // Function: H5Location::link
1090 ///\brief Creates a hard link from \a new_name to \a curr_name - can be
1091 /// used to pass in H5L_SAME_LOC.
1092 ///\param curr_name - IN: Name of the existing object
1093 ///\param loc_id - IN: Group or root group ID, or H5L_SAME_LOC
1094 ///\param new_name - IN: New name for the link
1095 ///\param lcpl - IN: Link creation plist - default to LinkCreatPropList::DEFAULT
1096 ///\param lapl - IN: Link access plist - default to LinkAccPropList::DEFAULT
1097 ///\exception H5::FileIException or H5::GroupIException
1098 ///\par Description
1099 /// Note that both names are interpreted relative to the
1100 /// specified location.
1101 /// For information on creating a hard link, please refer to the
1102 /// H5Lcreate_hard APIs in the HDF5 C Reference Manual.
1103 // March 2018
1104 //--------------------------------------------------------------------------
link(const char * curr_name,const hid_t same_loc,const char * new_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1105 void H5Location::link(const char *curr_name, const hid_t same_loc,
1106 const char *new_name, const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1107 {
1108 herr_t ret_value = -1;
1109 hid_t lcpl_id = lcpl.getId();
1110 hid_t lapl_id = lapl.getId();
1111
1112 ret_value = H5Lcreate_hard(getId(), curr_name, same_loc, new_name, H5P_DEFAULT, H5P_DEFAULT);
1113
1114 if (ret_value < 0)
1115 throwException("link", "creating link failed");
1116 }
1117
1118 //--------------------------------------------------------------------------
1119 // Function: H5Location::link
1120 ///\brief This is an overloaded member function, provided for convenience.
1121 /// It differs from the above function in that it takes an
1122 /// \c H5std_string for \a curr_name and \a new_name.
1123 ///\exception H5::FileIException or H5::GroupIException
1124 // March, 2018
1125 //--------------------------------------------------------------------------
link(const H5std_string & curr_name,const hid_t same_loc,const H5std_string & new_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1126 void H5Location::link(const H5std_string& curr_name, const hid_t same_loc,
1127 const H5std_string& new_name, const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1128 {
1129 link(curr_name.c_str(), same_loc, new_name.c_str(), lcpl, lapl);
1130 }
1131
1132 //--------------------------------------------------------------------------
1133 // Function: H5Location::link
1134 ///\brief Creates a link of the specified type from \a new_name to
1135 /// \a curr_name.
1136 ///\param link_type - IN: Link type; possible values are
1137 /// \li \c H5G_LINK_HARD
1138 /// \li \c H5G_LINK_SOFT
1139 ///\param curr_name - IN: Name of the existing object if link is a hard
1140 /// link; can be anything for the soft link
1141 ///\param new_name - IN: New name for the object
1142 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1143 ///\par Description
1144 /// Note that both names are interpreted relative to the
1145 /// specified location.
1146 /// For information on creating hard link and soft link, please
1147 /// refer to the H5Lcreate_hard and H5Lcreate_soft APIs in the
1148 /// HDF5 C Reference Manual.
1149 // Programmer Binh-Minh Ribler - 2000
1150 // Modification
1151 // 2007: QAK modified to use H5L APIs - BMR
1152 // Mar 2018: Inadequate functionality, new hard link is only in
1153 // H5L_SAME_LOC. This function will be retired in favor of
1154 // its replacement. - BMR
1155 //--------------------------------------------------------------------------
link(H5L_type_t link_type,const char * curr_name,const char * new_name) const1156 void H5Location::link(H5L_type_t link_type, const char* curr_name, const char* new_name) const
1157 {
1158 herr_t ret_value = -1;
1159
1160 switch(link_type) {
1161 case H5L_TYPE_HARD:
1162 ret_value = H5Lcreate_hard(getId(), curr_name, H5L_SAME_LOC, new_name, H5P_DEFAULT, H5P_DEFAULT);
1163 break;
1164
1165 case H5L_TYPE_SOFT:
1166 ret_value = H5Lcreate_soft(curr_name,getId(), new_name, H5P_DEFAULT, H5P_DEFAULT);
1167 break;
1168
1169 case H5L_TYPE_ERROR:
1170 case H5L_TYPE_EXTERNAL:
1171 case H5L_TYPE_MAX:
1172 default:
1173 throwException("link", "unknown link type");
1174 break;
1175 } /* end switch */
1176
1177 if (ret_value < 0)
1178 throwException("link", "creating link failed");
1179 }
1180
1181 //--------------------------------------------------------------------------
1182 // Function: H5Location::link
1183 ///\brief This is an overloaded member function, provided for convenience.
1184 /// It differs from the above function in that it takes an
1185 /// \c H5std_string for \a curr_name and \a new_name.
1186 // Programmer Binh-Minh Ribler - 2000
1187 //--------------------------------------------------------------------------
link(H5L_type_t link_type,const H5std_string & curr_name,const H5std_string & new_name) const1188 void H5Location::link(H5L_type_t link_type, const H5std_string& curr_name, const H5std_string& new_name) const
1189 {
1190 link(link_type, curr_name.c_str(), new_name.c_str());
1191 }
1192
1193 //--------------------------------------------------------------------------
1194 // Function: H5Location::copyLink
1195 ///\brief Copies a link from one group to another.
1196 ///\param src_name - IN: Original name
1197 ///\param dst - IN: Destination location
1198 ///\param dst_name - IN: New name
1199 ///\param lcpl - IN: Link creation plist - default LinkCreatPropList::DEFAULT
1200 ///\param lapl - IN: Link access plist - default LinkAccPropList::DEFAULT
1201 ///\exception H5::FileIException or H5::GroupIException
1202 // March, 2018
1203 //--------------------------------------------------------------------------
copyLink(const char * src_name,const Group & dst,const char * dst_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1204 void H5Location::copyLink(const char *src_name,
1205 const Group& dst, const char *dst_name, const LinkCreatPropList& lcpl,
1206 const LinkAccPropList& lapl) const
1207 {
1208 herr_t ret_value;
1209 hid_t dst_id = dst.getId();
1210 hid_t lcpl_id = lcpl.getId();
1211 hid_t lapl_id = lapl.getId();
1212
1213 ret_value = H5Lcopy(getId(), src_name, dst_id, dst_name, lcpl_id, lapl_id);
1214 if(ret_value < 0)
1215 throwException("copyLink", "H5Lcopy failed");
1216 }
1217
1218 //--------------------------------------------------------------------------
1219 // Function: H5Location::copyLink
1220 ///\brief This is an overloaded member function, provided for convenience.
1221 /// It differs from the above function in that it takes an
1222 /// \c H5std_string for \a src_name and \a dst_name.
1223 ///\exception H5::FileIException or H5::GroupIException
1224 // March, 2018
1225 //--------------------------------------------------------------------------
copyLink(const H5std_string & src_name,const Group & dst,const H5std_string & dst_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1226 void H5Location::copyLink(const H5std_string& src_name,
1227 const Group& dst, const H5std_string& dst_name, const LinkCreatPropList& lcpl,
1228 const LinkAccPropList& lapl) const
1229 {
1230 copyLink(src_name.c_str(), dst, dst_name.c_str(), lcpl, lapl);
1231 }
1232
1233 //--------------------------------------------------------------------------
1234 // Function: H5Location::copyLink
1235 ///\brief Copies a link from a group in the same location.
1236 ///\param src_name - IN: Original name
1237 ///\param dst_name - IN: New name
1238 ///\param lcpl - IN: Link creation plist - default LinkCreatPropList::DEFAULT
1239 ///\param lapl - IN: Link access plist - default LinkAccPropList::DEFAULT
1240 ///\exception H5::FileIException or H5::GroupIException
1241 // March, 2018
1242 //--------------------------------------------------------------------------
copyLink(const char * src_name,const char * dst_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1243 void H5Location::copyLink(const char *src_name,
1244 const char *dst_name, const LinkCreatPropList& lcpl,
1245 const LinkAccPropList& lapl) const
1246 {
1247 herr_t ret_value;
1248 hid_t lcpl_id = lcpl.getId();
1249 hid_t lapl_id = lapl.getId();
1250
1251 ret_value = H5Lcopy(getId(), src_name, H5L_SAME_LOC, dst_name, lcpl_id, lapl_id);
1252 if(ret_value < 0)
1253 throwException("copyLink", "H5Lcopy H5L_SAME_LOC failed");
1254 }
1255
1256 //--------------------------------------------------------------------------
1257 // Function: H5Location::copyLink
1258 ///\brief This is an overloaded member function, provided for convenience.
1259 /// It differs from the above function in that it takes an
1260 /// \c H5std_string for \a src_name and \a dst_name.
1261 ///\exception H5::FileIException or H5::GroupIException
1262 // March, 2018
1263 //--------------------------------------------------------------------------
copyLink(const H5std_string & src_name,const H5std_string & dst_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1264 void H5Location::copyLink(const H5std_string& src_name,
1265 const H5std_string& dst_name, const LinkCreatPropList& lcpl,
1266 const LinkAccPropList& lapl) const
1267 {
1268 copyLink(src_name.c_str(), dst_name.c_str(), lcpl, lapl);
1269 }
1270
1271 //--------------------------------------------------------------------------
1272 // Function: H5Location::moveLink
1273 ///\brief Renames a link in this group and moves it to a new location.
1274 ///\param src_name - IN: Original name
1275 ///\param dst - IN: Destination location
1276 ///\param dst_name - IN: New name
1277 ///\param lcpl - IN: Link creation plist - default LinkCreatPropList::DEFAULT
1278 ///\param lapl - IN: Link access plist - default LinkAccPropList::DEFAULT
1279 ///\exception H5::FileIException or H5::GroupIException
1280 ///\note
1281 /// Exercise care in moving groups as it is possible to render
1282 /// data in a file inaccessible with H5Location::moveLink. Please refer
1283 /// to the Group Interface in the HDF5 User's Guide for details.
1284 // March, 2018
1285 //--------------------------------------------------------------------------
moveLink(const char * src_name,const Group & dst,const char * dst_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1286 void H5Location::moveLink(const char* src_name, const Group& dst, const char* dst_name, const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1287 {
1288 herr_t ret_value;
1289 hid_t dst_id = dst.getId();
1290 hid_t lcpl_id = lcpl.getId();
1291 hid_t lapl_id = lapl.getId();
1292
1293 ret_value = H5Lmove(getId(), src_name, dst_id, dst_name, lcpl_id, lapl_id);
1294 if (ret_value < 0)
1295 throwException("moveLink", "H5Lmove failed");
1296 }
1297
1298 //--------------------------------------------------------------------------
1299 // Function: H5Location::moveLink
1300 ///\brief This is an overloaded member function, provided for convenience.
1301 /// It differs from the above function in that it takes an
1302 /// \c H5std_string for \a src_name and \a dst_name.
1303 ///\exception H5::FileIException or H5::GroupIException
1304 // March, 2018
1305 //--------------------------------------------------------------------------
moveLink(const H5std_string & src_name,const Group & dst,const H5std_string & dst_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1306 void H5Location::moveLink(const H5std_string& src_name, const Group& dst, const H5std_string& dst_name, const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1307 {
1308 moveLink(src_name.c_str(), dst, dst_name.c_str(), lcpl, lapl);
1309 }
1310
1311 //--------------------------------------------------------------------------
1312 // Function: H5Location::moveLink
1313 ///\brief Renames a link in this group.
1314 ///\param src_name - IN: Original name
1315 ///\param dst_name - IN: New name
1316 ///\param lcpl - IN: Link creation plist - default LinkCreatPropList::DEFAULT
1317 ///\param lapl - IN: Link access plist - default LinkAccPropList::DEFAULT
1318 ///\exception H5::FileIException or H5::GroupIException
1319 ///\note
1320 /// Exercise care in moving groups as it is possible to render
1321 /// data in a file inaccessible with H5Location::moveLink. Please refer
1322 /// to the Group Interface in the HDF5 User's Guide for details.
1323 // March, 2018
1324 //--------------------------------------------------------------------------
moveLink(const char * src_name,const char * dst_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1325 void H5Location::moveLink(const char* src_name, const char* dst_name, const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1326 {
1327 herr_t ret_value;
1328 hid_t lcpl_id = lcpl.getId();
1329 hid_t lapl_id = lapl.getId();
1330
1331 ret_value = H5Lmove(getId(), src_name, H5L_SAME_LOC, dst_name, lcpl_id, lapl_id);
1332 if (ret_value < 0)
1333 throwException("moveLink", "H5Lmove H5L_SAME_LOC failed");
1334 }
1335
1336 //--------------------------------------------------------------------------
1337 // Function: H5Location::moveLink
1338 ///\brief This is an overloaded member function, provided for convenience.
1339 /// It differs from the above function in that it takes an
1340 /// \c H5std_string for \a src_name and \a dst_name.
1341 ///\exception H5::FileIException or H5::GroupIException
1342 // March, 2018
1343 //--------------------------------------------------------------------------
moveLink(const H5std_string & src_name,const H5std_string & dst_name,const LinkCreatPropList & lcpl,const LinkAccPropList & lapl) const1344 void H5Location::moveLink(const H5std_string& src_name, const H5std_string& dst_name, const LinkCreatPropList& lcpl, const LinkAccPropList& lapl) const
1345 {
1346 moveLink(src_name.c_str(), dst_name.c_str(), lcpl, lapl);
1347 }
1348
1349 //--------------------------------------------------------------------------
1350 // Function: H5Location::move
1351 ///\brief Renames an object at this location. - Deprecated due to inadequate functionality
1352 ///\param src - IN: Object's original name
1353 ///\param dst - IN: Object's new name
1354 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1355 ///\note
1356 /// Exercise care in moving groups as it is possible to render
1357 /// data in a file inaccessible with H5Location::move. Please refer
1358 /// to the Group Interface in the HDF5 User's Guide for details.
1359 // Modification
1360 // 2007: QAK modified to use H5L APIs - BMR
1361 // 2018: Will be replaced by H5Location::moveLink() -BMR
1362 //--------------------------------------------------------------------------
move(const char * src,const char * dst) const1363 void H5Location::move(const char* src, const char* dst) const
1364 {
1365 moveLink(src, dst, LinkCreatPropList::DEFAULT, LinkAccPropList::DEFAULT);
1366 }
1367
1368 //--------------------------------------------------------------------------
1369 // Function: H5Location::move
1370 ///\brief This is an overloaded member function, provided for convenience.
1371 /// It differs from the above function in that it takes an
1372 /// \c H5std_string for \a src and \a dst. - Deprecated due to inadequate functionality
1373 // Modification
1374 // 2018: Will be replaced by H5Location::moveLink() -BMR
1375 //--------------------------------------------------------------------------
move(const H5std_string & src,const H5std_string & dst) const1376 void H5Location::move(const H5std_string& src, const H5std_string& dst) const
1377 {
1378 moveLink(src.c_str(), dst.c_str(), LinkCreatPropList::DEFAULT, LinkAccPropList::DEFAULT);
1379 }
1380
1381 //--------------------------------------------------------------------------
1382 // Function: H5Location::unlink
1383 ///\brief Removes the specified link from this group.
1384 ///\param name - IN: Name of the object to be removed
1385 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1386 // March, 2018
1387 //--------------------------------------------------------------------------
unlink(const char * name,const LinkAccPropList & lapl) const1388 void H5Location::unlink(const char* name, const LinkAccPropList& lapl) const
1389 {
1390 herr_t ret_value = H5Ldelete(getId(), name, lapl.getId());
1391 if (ret_value < 0)
1392 throwException("unlink", "H5Ldelete failed");
1393 }
1394
1395 //--------------------------------------------------------------------------
1396 // Function: H5Location::unlink
1397 ///\brief This is an overloaded member function, provided for convenience.
1398 /// It differs from the above function in that it takes an
1399 /// \c H5std_string for \a name.
1400 // March, 2018
1401 //--------------------------------------------------------------------------
unlink(const H5std_string & name,const LinkAccPropList & lapl) const1402 void H5Location::unlink(const H5std_string& name, const LinkAccPropList& lapl) const
1403 {
1404 unlink(name.c_str(), lapl);
1405 }
1406
1407 //--------------------------------------------------------------------------
1408 // Function: H5Location::getObjinfo
1409 ///\brief Retrieves information about an HDF5 object.
1410 ///\param objinfo - OUT: Struct containing the object info
1411 ///\param fields - IN: Indicates the group of information to be retrieved
1412 ///\par Description
1413 /// Valid values of \a fields are as follows:
1414 /// \li \c H5O_INFO_BASIC (default)
1415 /// \li \c H5O_INFO_TIME
1416 /// \li \c H5O_INFO_NUM_ATTRS
1417 /// \li \c H5O_INFO_HDR
1418 /// \li \c H5O_INFO_META_SIZE
1419 /// \li \c H5O_INFO_ALL
1420 // July, 2018
1421 //--------------------------------------------------------------------------
getObjinfo(H5O_info_t & objinfo,unsigned fields) const1422 void H5Location::getObjinfo(H5O_info_t& objinfo, unsigned fields) const
1423 {
1424
1425 // Use C API to get information of the object
1426 herr_t ret_value = H5Oget_info2(getId(), &objinfo, fields);
1427
1428 // Throw exception if C API returns failure
1429 if (ret_value < 0)
1430 throwException(inMemFunc("getObjinfo"), "H5Oget_info2 failed");
1431 }
1432
1433 //--------------------------------------------------------------------------
1434 // Function: H5Location::getObjinfo
1435 ///\brief Retrieves information about an HDF5 object given its name.
1436 ///\param name - IN: Name of the object to be queried - \c char *
1437 ///\param objinfo - OUT: Struct containing the object info
1438 ///\param fields - IN: Indicates the group of information to be retrieved
1439 /// - default to H5O_INFO_BASIC
1440 ///\param lapl - IN: Link access property list
1441 ///\par Description
1442 /// Valid values of \a fields are as follows:
1443 /// \li \c H5O_INFO_BASIC (default)
1444 /// \li \c H5O_INFO_TIME
1445 /// \li \c H5O_INFO_NUM_ATTRS
1446 /// \li \c H5O_INFO_HDR
1447 /// \li \c H5O_INFO_META_SIZE
1448 /// \li \c H5O_INFO_ALL
1449 // July, 2018
1450 //--------------------------------------------------------------------------
getObjinfo(const char * name,H5O_info_t & objinfo,unsigned fields,const LinkAccPropList & lapl) const1451 void H5Location::getObjinfo(const char* name, H5O_info_t& objinfo, unsigned fields, const LinkAccPropList& lapl) const
1452 {
1453 // Use C API to get information of the object
1454 herr_t ret_value = H5Oget_info_by_name2(getId(), name, &objinfo, fields, lapl.getId());
1455
1456 // Throw exception if C API returns failure
1457 if (ret_value < 0)
1458 throwException(inMemFunc("getObjinfo"), "H5Oget_info_by_name2 failed");
1459 }
1460
1461 //--------------------------------------------------------------------------
1462 // Function: H5Location::getObjinfo
1463 ///\brief This is an overloaded member function, provided for convenience.
1464 /// It differs from the above function in that it takes
1465 /// a reference to an \c H5std_string for \a name.
1466 ///\param name - IN: Name of the object to be queried - \c H5std_string
1467 ///\param objinfo - OUT: Struct containing the object info
1468 ///\param fields - IN: Indicates the group of information to be retrieved
1469 /// - default to H5O_INFO_BASIC
1470 ///\param lapl - IN: Link access property list
1471 // July, 2018
1472 //--------------------------------------------------------------------------
getObjinfo(const H5std_string & name,H5O_info_t & objinfo,unsigned fields,const LinkAccPropList & lapl) const1473 void H5Location::getObjinfo(const H5std_string& name, H5O_info_t& objinfo, unsigned fields, const LinkAccPropList& lapl) const
1474 {
1475 getObjinfo(name.c_str(), objinfo, fields, lapl);
1476 }
1477
1478 //--------------------------------------------------------------------------
1479 // Function: H5Location::getObjinfo
1480 ///\brief Retrieves information about an HDF5 object given its index.
1481 ///\param grp_name - IN: Group name where the object belongs - \c char *
1482 ///\param idx_type - IN: Type of index
1483 ///\param order - IN: Order to traverse
1484 ///\param idx - IN: Object position
1485 ///\param objinfo - OUT: Struct containing the object info
1486 ///\param fields - IN: Indicates the group of information to be retrieved
1487 /// - default to H5O_INFO_BASIC
1488 ///\param lapl - IN: Link access property list
1489 ///\par Description
1490 /// Valid values of \a fields are as follows:
1491 /// \li \c H5O_INFO_BASIC (default)
1492 /// \li \c H5O_INFO_TIME
1493 /// \li \c H5O_INFO_NUM_ATTRS
1494 /// \li \c H5O_INFO_HDR
1495 /// \li \c H5O_INFO_META_SIZE
1496 /// \li \c H5O_INFO_ALL
1497 // July, 2018
1498 //--------------------------------------------------------------------------
getObjinfo(const char * grp_name,H5_index_t idx_type,H5_iter_order_t order,hsize_t idx,H5O_info_t & objinfo,unsigned fields,const LinkAccPropList & lapl) const1499 void H5Location::getObjinfo(const char* grp_name, H5_index_t idx_type,
1500 H5_iter_order_t order, hsize_t idx, H5O_info_t& objinfo, unsigned fields,
1501 const LinkAccPropList& lapl) const
1502 {
1503 // Use C API to get information of the object
1504 herr_t ret_value = H5Oget_info_by_idx2(getId(), grp_name, idx_type, order,
1505 idx, &objinfo, fields, lapl.getId());
1506
1507 // Throw exception if C API returns failure
1508 if (ret_value < 0)
1509 throwException(inMemFunc("getObjinfo"), "H5Oget_info_by_idx2 failed");
1510 }
1511
1512 //--------------------------------------------------------------------------
1513 // Function: H5Location::getObjinfo
1514 ///\brief This is an overloaded member function, provided for convenience.
1515 /// It differs from the above function in that it takes
1516 /// a reference to an \c H5std_string for \a name.
1517 ///\param name - IN: Name of the object to be queried - \c H5std_string
1518 ///\param objinfo - OUT: Struct containing the object info
1519 ///\param fields - IN: Indicates a group of information to be retrieved
1520 /// - default to H5O_INFO_BASIC
1521 ///\param lapl - IN: Link access property list
1522 // July, 2018
1523 //--------------------------------------------------------------------------
getObjinfo(const H5std_string & grp_name,H5_index_t idx_type,H5_iter_order_t order,hsize_t idx,H5O_info_t & objinfo,unsigned fields,const LinkAccPropList & lapl) const1524 void H5Location::getObjinfo(const H5std_string& grp_name, H5_index_t idx_type,
1525 H5_iter_order_t order, hsize_t idx, H5O_info_t& objinfo, unsigned fields,
1526 const LinkAccPropList& lapl) const
1527 {
1528 getObjinfo(grp_name.c_str(), idx_type, order, idx, objinfo, fields, lapl);
1529 }
1530
1531 #ifndef H5_NO_DEPRECATED_SYMBOLS
1532 //--------------------------------------------------------------------------
1533 // Function: H5Location::getObjinfo
1534 ///\brief Returns information about an object.
1535 ///\param name - IN: Name of the object
1536 ///\param follow_link - IN: Link flag
1537 ///\param statbuf - OUT: Buffer to return information about the object
1538 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1539 ///\par Description
1540 /// For information, please refer to the H5Gget_objinfo API in
1541 /// the HDF5 C Reference Manual.
1542 // 2000
1543 //--------------------------------------------------------------------------
getObjinfo(const char * name,hbool_t follow_link,H5G_stat_t & statbuf) const1544 void H5Location::getObjinfo(const char* name, hbool_t follow_link, H5G_stat_t& statbuf) const
1545 {
1546 herr_t ret_value = H5Gget_objinfo(getId(), name, follow_link, &statbuf);
1547 if (ret_value < 0)
1548 throwException("getObjinfo", "H5Gget_objinfo failed");
1549 }
1550
1551 //--------------------------------------------------------------------------
1552 // Function: H5Location::getObjinfo
1553 ///\brief This is an overloaded member function, provided for convenience.
1554 /// It differs from the above function in that it takes an
1555 /// \c H5std_string for \a name.
1556 // Programmer Binh-Minh Ribler - 2000
1557 //--------------------------------------------------------------------------
getObjinfo(const H5std_string & name,hbool_t follow_link,H5G_stat_t & statbuf) const1558 void H5Location::getObjinfo(const H5std_string& name, hbool_t follow_link, H5G_stat_t& statbuf) const
1559 {
1560 getObjinfo(name.c_str(), follow_link, statbuf);
1561 }
1562
1563 //--------------------------------------------------------------------------
1564 // Function: H5Location::getObjinfo
1565 ///\brief This is an overloaded member function, provided for convenience.
1566 /// It differs from the above functions in that it doesn't have
1567 /// the paramemter \a follow_link.
1568 // Nov, 2005
1569 //--------------------------------------------------------------------------
getObjinfo(const char * name,H5G_stat_t & statbuf) const1570 void H5Location::getObjinfo(const char* name, H5G_stat_t& statbuf) const
1571 {
1572 herr_t ret_value = H5Gget_objinfo(getId(), name, 0, &statbuf);
1573 if (ret_value < 0)
1574 throwException("getObjinfo", "H5Gget_objinfo failed");
1575 }
1576
1577 //--------------------------------------------------------------------------
1578 // Function: H5Location::getObjinfo
1579 ///\brief This is an overloaded member function, provided for convenience.
1580 /// It differs from the above function in that it takes an
1581 /// \c H5std_string for \a name.
1582 // Programmer Binh-Minh Ribler - Nov, 2005
1583 //--------------------------------------------------------------------------
getObjinfo(const H5std_string & name,H5G_stat_t & statbuf) const1584 void H5Location::getObjinfo(const H5std_string& name, H5G_stat_t& statbuf) const
1585 {
1586 getObjinfo(name.c_str(), statbuf);
1587 }
1588
1589 #endif /* H5_NO_DEPRECATED_SYMBOLS */
1590
1591 //--------------------------------------------------------------------------
1592 // Function: H5Location::getLinkInfo
1593 ///\brief Returns the information of the named link.
1594 ///\param link_name - IN: Symbolic link to the object
1595 ///\param size - IN: Maximum number of characters of value to be returned
1596 ///\return Name of the object
1597 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1598 // 2000
1599 //--------------------------------------------------------------------------
getLinkInfo(const char * link_name,const LinkAccPropList & lapl) const1600 H5L_info_t H5Location::getLinkInfo(const char* link_name, const LinkAccPropList& lapl) const
1601 {
1602 H5L_info_t linkinfo; // link info structure
1603
1604 herr_t ret_value = H5Lget_info(getId(), link_name, &linkinfo, lapl.getId());
1605 if (ret_value < 0)
1606 throwException("getLinkInfo", "H5Lget_info to find buffer size failed");
1607
1608 return(linkinfo);
1609 }
1610
1611 //--------------------------------------------------------------------------
1612 // Function: H5Location::getLinkInfo
1613 ///\brief This is an overloaded member function, provided for convenience.
1614 /// It differs from the above function in that it takes an
1615 /// \c H5std_string for \a link_name.
1616 //--------------------------------------------------------------------------
getLinkInfo(const H5std_string & link_name,const LinkAccPropList & lapl) const1617 H5L_info_t H5Location::getLinkInfo(const H5std_string& link_name, const LinkAccPropList& lapl) const
1618 {
1619 return(getLinkInfo(link_name.c_str(), lapl));
1620 }
1621
1622 //--------------------------------------------------------------------------
1623 // Function: H5Location::getLinkval
1624 ///\brief Returns the name of the object that the symbolic link points to.
1625 ///\param name - IN: Symbolic link to the object
1626 ///\param size - IN: Maximum number of characters of value to be returned
1627 ///\return Name of the object
1628 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1629 // 2000
1630 //--------------------------------------------------------------------------
getLinkval(const char * name,size_t size) const1631 H5std_string H5Location::getLinkval(const char* name, size_t size) const
1632 {
1633 H5L_info_t linkinfo;
1634 char *value_C; // value in C string
1635 size_t val_size = size;
1636 H5std_string value = "";
1637 herr_t ret_value;
1638
1639 // if user doesn't provide buffer size, determine it
1640 if (size == 0)
1641 {
1642 ret_value = H5Lget_info(getId(), name, &linkinfo, H5P_DEFAULT);
1643 if (ret_value < 0)
1644 throwException("getLinkval", "H5Lget_info to find buffer size failed");
1645
1646 val_size = linkinfo.u.val_size;
1647 }
1648
1649 // if link has value, retrieve the value, otherwise, return null string
1650 if (val_size > 0)
1651 {
1652 value_C = new char[val_size+1]; // temporary C-string for C API
1653 HDmemset(value_C, 0, val_size+1); // clear buffer
1654
1655 ret_value = H5Lget_val(getId(), name, value_C, val_size, H5P_DEFAULT);
1656 if (ret_value < 0)
1657 {
1658 delete []value_C;
1659 throwException("getLinkval", "H5Lget_val failed");
1660 }
1661
1662 value = H5std_string(value_C);
1663 delete []value_C;
1664 }
1665 return(value);
1666 }
1667
1668 //--------------------------------------------------------------------------
1669 // Function: H5Location::getLinkval
1670 ///\brief This is an overloaded member function, provided for convenience.
1671 /// It differs from the above function in that it takes an
1672 /// \c H5std_string for \a name.
1673 // Programmer Binh-Minh Ribler - 2000
1674 //--------------------------------------------------------------------------
getLinkval(const H5std_string & name,size_t size) const1675 H5std_string H5Location::getLinkval(const H5std_string& name, size_t size) const
1676 {
1677 return(getLinkval( name.c_str(), size));
1678 }
1679
1680 //--------------------------------------------------------------------------
1681 // Function: H5Location::mount
1682 ///\brief Mounts the file \a child onto this group.
1683 ///\param name - IN: Name of the group
1684 ///\param child - IN: File to mount
1685 ///\param plist - IN: Property list to use
1686 ///\exception H5::FileIException or H5::GroupIException
1687 // Programmer Binh-Minh Ribler - 2014 (original 2000)
1688 //--------------------------------------------------------------------------
mount(const char * name,const H5File & child,const PropList & plist) const1689 void H5Location::mount(const char* name, const H5File& child, const PropList& plist) const
1690 {
1691 // Obtain identifiers for C API
1692 hid_t plist_id = plist.getId();
1693 hid_t child_id = child.getId();
1694
1695 // Call C routine H5Fmount to do the mouting
1696 herr_t ret_value = H5Fmount(getId(), name, child_id, plist_id);
1697
1698 // Raise exception if H5Fmount returns negative value
1699 if (ret_value < 0)
1700 throwException("mount", "H5Fmount failed");
1701 }
1702
1703 //--------------------------------------------------------------------------
1704 // Function: H5Location::mount
1705 // Purpose This is an overloaded member function, kept for backward
1706 // compatibility. It differs from the above function in that it
1707 // misses const's. This wrapper will be removed in future release.
1708 // Param name - IN: Name of the group
1709 // Param child - IN: File to mount
1710 // Param plist - IN: Property list to use
1711 // Exception H5::FileIException or H5::GroupIException
1712 // Programmer Binh-Minh Ribler - 2000
1713 // Modification
1714 // Modified to call its replacement. -BMR, 2014/04/16
1715 // Removed from documentation. -BMR, 2016/03/07 1.8.17 and 1.10.0
1716 // Removed from code. -BMR, 2016/08/11 1.8.18 and 1.10.1
1717 //--------------------------------------------------------------------------
1718 //void H5Location::mount(const char* name, H5File& child, PropList& plist) const
1719 //{
1720 // mount(name, child, plist);
1721 //}
1722
1723 //--------------------------------------------------------------------------
1724 // Function: H5Location::mount
1725 ///\brief This is an overloaded member function, provided for convenience.
1726 /// It takes an \c H5std_string for \a name.
1727 // Programmer Binh-Minh Ribler - 2000
1728 //--------------------------------------------------------------------------
mount(const H5std_string & name,const H5File & child,const PropList & plist) const1729 void H5Location::mount(const H5std_string& name, const H5File& child, const PropList& plist) const
1730 {
1731 mount(name.c_str(), child, plist);
1732 }
1733
1734 //--------------------------------------------------------------------------
1735 // Function: H5Location::mount
1736 // Purpose This is an overloaded member function, kept for backward
1737 // compatibility. It differs from the above function in that it
1738 // misses const's. This wrapper will be removed in future release.
1739 // Programmer Binh-Minh Ribler - 2014
1740 // Modification
1741 // Modified to call its replacement. -BMR, 2014/04/16
1742 // Removed from documentation. -BMR, 2016/03/07 1.8.17 and 1.10.0
1743 // Removed from code. -BMR, 2016/08/11 1.8.18 and 1.10.1
1744 //--------------------------------------------------------------------------
1745 //void H5Location::mount(const H5std_string& name, H5File& child, PropList& plist) const
1746 //{
1747 // mount(name.c_str(), child, plist);
1748 //}
1749
1750 //--------------------------------------------------------------------------
1751 // Function: H5Location::unmount
1752 ///\brief Unmounts the specified file.
1753 ///\param name - IN: Name of the file to unmount
1754 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1755 // Programmer Binh-Minh Ribler - 2000
1756 //--------------------------------------------------------------------------
unmount(const char * name) const1757 void H5Location::unmount(const char* name) const
1758 {
1759 // Call C routine H5Fmount to do the mouting
1760 herr_t ret_value = H5Funmount(getId(), name);
1761
1762 // Raise exception if H5Funmount returns negative value
1763 if (ret_value < 0)
1764 throwException("unmount", "H5Funmount failed");
1765 }
1766
1767 //--------------------------------------------------------------------------
1768 // Function: H5Location::unmount
1769 ///\brief This is an overloaded member function, provided for convenience.
1770 /// It differs from the above function in that it takes an
1771 /// \c H5std_string for \a name.
1772 // Programmer Binh-Minh Ribler - 2000
1773 //--------------------------------------------------------------------------
unmount(const H5std_string & name) const1774 void H5Location::unmount(const H5std_string& name) const
1775 {
1776 unmount(name.c_str());
1777 }
1778
1779 #ifndef H5_NO_DEPRECATED_SYMBOLS
1780 //--------------------------------------------------------------------------
1781 // Function: H5Location::iterateElems
1782 ///\brief Iterates a user's function over the entries of a group.
1783 ///\param name - IN : Name of group to iterate over
1784 ///\param idx - IN/OUT: Starting (IN) and ending (OUT) entry indices
1785 ///\param op - IN : User's function to operate on each entry
1786 ///\param op_data - IN/OUT: Data associated with the operation
1787 ///\return The return value of the first operator that returns non-zero,
1788 /// or zero if all members were processed with no operator
1789 /// returning non-zero.
1790 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1791 // Programmer Binh-Minh Ribler - 2000
1792 //--------------------------------------------------------------------------
iterateElems(const char * name,int * idx,H5G_iterate_t op,void * op_data)1793 int H5Location::iterateElems(const char* name, int *idx, H5G_iterate_t op , void* op_data)
1794 {
1795 int ret_value = H5Giterate(getId(), name, idx, op, op_data);
1796 if (ret_value < 0)
1797 {
1798 throwException("iterateElems", "H5Giterate failed");
1799 }
1800 return(ret_value);
1801 }
1802
1803 //--------------------------------------------------------------------------
1804 // Function: H5Location::iterateElems
1805 ///\brief This is an overloaded member function, provided for convenience.
1806 /// It differs from the above function in that it takes an
1807 /// \c H5std_string for \a name.
1808 // Programmer Binh-Minh Ribler - 2000
1809 //--------------------------------------------------------------------------
iterateElems(const H5std_string & name,int * idx,H5G_iterate_t op,void * op_data)1810 int H5Location::iterateElems(const H5std_string& name, int *idx, H5G_iterate_t op , void* op_data)
1811 {
1812 return(iterateElems( name.c_str(), idx, op, op_data));
1813 }
1814 #endif /* H5_NO_DEPRECATED_SYMBOLS */
1815
1816 //--------------------------------------------------------------------------
1817 // Function: H5Location::getNumObjs
1818 ///\brief Deprecated - moved to H5::Group in 1.10.2.
1819 ///\return Deprecated
1820 ///\exception Deprecated
1821 // Programmer Binh-Minh Ribler - January, 2003
1822 //--------------------------------------------------------------------------
getNumObjs() const1823 hsize_t H5Location::getNumObjs() const
1824 {
1825 H5G_info_t ginfo; // Group information
1826
1827 herr_t ret_value = H5Gget_info(getId(), &ginfo);
1828 if(ret_value < 0)
1829 throwException("getNumObjs", "H5Gget_info failed");
1830 return (ginfo.nlinks);
1831 }
1832
1833 //--------------------------------------------------------------------------
1834 // Function: H5Location::getObjnameByIdx
1835 ///\brief Returns the name of an object in this group, given the
1836 /// object's index.
1837 ///\param idx - IN: Transient index of the object
1838 ///\return Object name
1839 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1840 ///\par Description
1841 /// The value of idx can be any nonnegative number less than the
1842 /// total number of objects in the group, which is returned by
1843 /// the function \c H5Location::getNumObjs. Note that this is a
1844 /// transient index; thus, an object may have a different index
1845 /// each time the group is opened.
1846 // Programmer Binh-Minh Ribler - Mar, 2005
1847 //--------------------------------------------------------------------------
getObjnameByIdx(hsize_t idx) const1848 H5std_string H5Location::getObjnameByIdx(hsize_t idx) const
1849 {
1850 // call H5Lget_name_by_idx with name as NULL to get its length
1851 ssize_t name_len = H5Lget_name_by_idx(getId(), ".", H5_INDEX_NAME, H5_ITER_INC, idx, NULL, 0, H5P_DEFAULT);
1852 if(name_len < 0)
1853 throwException("getObjnameByIdx", "H5Lget_name_by_idx failed");
1854
1855 // now, allocate C buffer to get the name
1856 char* name_C = new char[name_len+1];
1857 HDmemset(name_C, 0, name_len+1); // clear buffer
1858
1859 name_len = H5Lget_name_by_idx(getId(), ".", H5_INDEX_NAME, H5_ITER_INC, idx, name_C, name_len+1, H5P_DEFAULT);
1860
1861 if (name_len < 0)
1862 {
1863 delete []name_C;
1864 throwException("getObjnameByIdx", "H5Lget_name_by_idx failed");
1865 }
1866
1867 // clean up and return the string
1868 H5std_string name = H5std_string(name_C);
1869 delete []name_C;
1870 return (name);
1871 }
1872
1873 //--------------------------------------------------------------------------
1874 // Function: H5Location::getObjnameByIdx
1875 ///\brief Retrieves the name of an object in this group, given the
1876 /// object's index.
1877 ///\param idx - IN: Transient index of the object
1878 ///\param name - IN/OUT: Retrieved name of the object
1879 ///\param size - IN: Length to retrieve
1880 ///\return Actual size of the object name or 0, if object has no name
1881 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1882 ///\par Description
1883 /// The value of idx can be any nonnegative number less than the
1884 /// total number of objects in the group, which is returned by
1885 /// the function \c H5Location::getNumObjs. Note that this is a
1886 /// transient index; thus, an object may have a different index
1887 /// each time the group is opened.
1888 // Programmer Binh-Minh Ribler - January, 2003
1889 //--------------------------------------------------------------------------
getObjnameByIdx(hsize_t idx,char * name,size_t size) const1890 ssize_t H5Location::getObjnameByIdx(hsize_t idx, char* name, size_t size) const
1891 {
1892 ssize_t name_len = H5Lget_name_by_idx(getId(), ".", H5_INDEX_NAME, H5_ITER_INC, idx, name, size, H5P_DEFAULT);
1893 if(name_len < 0)
1894 throwException("getObjnameByIdx", "H5Lget_name_by_idx failed");
1895
1896 return (name_len);
1897 }
1898
1899 //--------------------------------------------------------------------------
1900 // Function: H5Location::getObjnameByIdx
1901 ///\brief This is an overloaded member function, provided for convenience.
1902 /// It differs from the above function in that it takes an
1903 /// \c H5std_string for \a name.
1904 // Programmer Binh-Minh Ribler - January, 2003
1905 //--------------------------------------------------------------------------
getObjnameByIdx(hsize_t idx,H5std_string & name,size_t size) const1906 ssize_t H5Location::getObjnameByIdx(hsize_t idx, H5std_string& name, size_t size) const
1907 {
1908 char* name_C = new char[size+1]; // temporary C-string for object name
1909 HDmemset(name_C, 0, size+1); // clear buffer
1910
1911 // call overloaded function to get the name
1912 ssize_t name_len = getObjnameByIdx(idx, name_C, size+1);
1913 if(name_len < 0)
1914 {
1915 delete []name_C;
1916 throwException("getObjnameByIdx", "H5Lget_name_by_idx failed");
1917 }
1918
1919 // clean up and return the string
1920 name = H5std_string(name_C);
1921 delete []name_C;
1922 return (name_len);
1923 }
1924
1925 //--------------------------------------------------------------------------
1926 // Function: H5Location::childObjType
1927 ///\brief Returns the type of an object in this file/group, given the
1928 /// object's name.
1929 ///\param objname - IN: Name of the object
1930 ///\return Object type, which can have the following values for group,
1931 /// dataset, and named datatype
1932 /// \li \c H5O_TYPE_GROUP
1933 /// \li \c H5O_TYPE_DATASET
1934 /// \li \c H5O_TYPE_NAMED_DATATYPE
1935 /// For information, please refer to the H5Oget_info_by_name API in
1936 /// the HDF5 C Reference Manual.
1937 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1938 /// Exception will be thrown when:
1939 /// - an error returned by the C API
1940 /// - object type is not one of the valid values above
1941 // Programmer Binh-Minh Ribler - April, 2014
1942 //--------------------------------------------------------------------------
childObjType(const char * objname) const1943 H5O_type_t H5Location::childObjType(const char* objname) const
1944 {
1945 H5O_info_t objinfo;
1946 H5O_type_t objtype = H5O_TYPE_UNKNOWN;
1947
1948 // Use C API to get information of the object
1949 herr_t ret_value = H5Oget_info_by_name2(getId(), objname, &objinfo, H5O_INFO_BASIC, H5P_DEFAULT);
1950
1951 // Throw exception if C API returns failure
1952 if (ret_value < 0)
1953 throwException("childObjType", "H5Oget_info_by_name failed");
1954 // Return a valid type or throw an exception for unknown type
1955 else
1956 switch (objinfo.type)
1957 {
1958 case H5O_TYPE_GROUP:
1959 case H5O_TYPE_DATASET:
1960 case H5O_TYPE_NAMED_DATATYPE:
1961 objtype = objinfo.type;
1962 break;
1963 case H5O_TYPE_UNKNOWN:
1964 case H5O_TYPE_NTYPES:
1965 default:
1966 throwException("childObjType", "Unknown type of object");
1967 }
1968 return(objtype);
1969 }
1970
1971 //--------------------------------------------------------------------------
1972 // Function: H5Location::childObjType
1973 ///\brief This is an overloaded member function, provided for convenience.
1974 /// It takes an \a H5std_string for the object's name.
1975 ///\brief Returns the type of an object in this group, given the
1976 /// object's name.
1977 ///\param objname - IN: Name of the object (H5std_string&)
1978 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
1979 // Programmer Binh-Minh Ribler - April, 2014
1980 //--------------------------------------------------------------------------
childObjType(const H5std_string & objname) const1981 H5O_type_t H5Location::childObjType(const H5std_string& objname) const
1982 {
1983 // Use overloaded function
1984 H5O_type_t objtype = childObjType(objname.c_str());
1985 return(objtype);
1986 }
1987
1988 //--------------------------------------------------------------------------
1989 // Function: H5Location::childObjType
1990 ///\brief Returns the type of an object in this file/group, given the
1991 /// object's index and its type and order.
1992 ///\param index - IN: Position of the object
1993 ///\param index_type - IN: Type of the index, default to H5_INDEX_NAME
1994 ///\param order - IN: Traversing order, default to H5_ITER_INC
1995 ///\param objname - IN: Name of the object, default to "."
1996 ///\return Object type, which can have the following values for group,
1997 /// dataset, and named datatype
1998 /// \li \c H5O_TYPE_GROUP
1999 /// \li \c H5O_TYPE_DATASET
2000 /// \li \c H5O_TYPE_NAMED_DATATYPE
2001 /// For information, please refer to the H5Oget_info_by_idx API in
2002 /// the HDF5 C Reference Manual.
2003 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
2004 /// Exception will be thrown when:
2005 /// - an error returned by the C API
2006 /// - object type is not one of the valid values above
2007 // Developer's Notes:
2008 // - this overload uses H5Oget_info_by_idx instead of H5Oget_info_by_name
2009 // like the previous childObjType()
2010 // - index is the required argument so, first
2011 // - objname is last because it's more likely the location is already
2012 // fully specified
2013 // - Leave property list out for now because C API is not using it, it
2014 // can be added later when needed.
2015 // Programmer Binh-Minh Ribler - April, 2014
2016 //--------------------------------------------------------------------------
childObjType(hsize_t index,H5_index_t index_type,H5_iter_order_t order,const char * objname) const2017 H5O_type_t H5Location::childObjType(hsize_t index, H5_index_t index_type, H5_iter_order_t order, const char* objname) const
2018 {
2019 herr_t ret_value;
2020 H5O_info_t objinfo;
2021 H5O_type_t objtype = H5O_TYPE_UNKNOWN;
2022
2023 // Use C API to get information of the object
2024 ret_value = H5Oget_info_by_idx2(getId(), objname, index_type, order, index, &objinfo, H5O_INFO_BASIC, H5P_DEFAULT);
2025
2026 // Throw exception if C API returns failure
2027 if (ret_value < 0)
2028 throwException("childObjType", "H5Oget_info_by_idx failed");
2029 // Return a valid type or throw an exception for unknown type
2030 else
2031 switch (objinfo.type)
2032 {
2033 case H5O_TYPE_GROUP:
2034 case H5O_TYPE_DATASET:
2035 case H5O_TYPE_NAMED_DATATYPE:
2036 objtype = objinfo.type;
2037 break;
2038 case H5O_TYPE_UNKNOWN:
2039 case H5O_TYPE_NTYPES:
2040 default:
2041 throwException("childObjType", "Unknown type of object");
2042 }
2043 return(objtype);
2044 }
2045
2046 //--------------------------------------------------------------------------
2047 // Function: H5Location::childObjVersion
2048 ///\brief Returns the object header version of an object in this file/group,
2049 /// given the object's name.
2050 ///\param objname - IN: Name of the object
2051 ///\return Object version, which can have the following values:
2052 /// \li \c H5O_VERSION_1
2053 /// \li \c H5O_VERSION_2
2054 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
2055 /// Exception will be thrown when:
2056 /// - an error returned by the C API
2057 /// - version number is not one of the valid values above
2058 // Programmer Binh-Minh Ribler - April, 2014
2059 //--------------------------------------------------------------------------
childObjVersion(const char * objname) const2060 unsigned H5Location::childObjVersion(const char* objname) const
2061 {
2062 H5O_info_t objinfo;
2063 unsigned version = 0;
2064
2065 // Use C API to get information of the object
2066 herr_t ret_value = H5Oget_info_by_name2(getId(), objname, &objinfo, H5O_INFO_HDR, H5P_DEFAULT);
2067
2068 // Throw exception if C API returns failure
2069 if (ret_value < 0)
2070 throwException("childObjVersion", "H5Oget_info_by_name failed");
2071 // Return a valid version or throw an exception for invalid value
2072 else
2073 {
2074 version = objinfo.hdr.version;
2075 if (version != H5O_VERSION_1 && version != H5O_VERSION_2)
2076 throwException("childObjVersion", "Invalid version for object");
2077 }
2078 return(version);
2079 }
2080
2081 //--------------------------------------------------------------------------
2082 // Function: H5Location::childObjVersion
2083 ///\brief This is an overloaded member function, provided for convenience.
2084 /// It takes an \a H5std_string for the object's name.
2085 ///\brief Returns the type of an object in this group, given the
2086 /// object's name.
2087 ///\param objname - IN: Name of the object (H5std_string&)
2088 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
2089 // Programmer Binh-Minh Ribler - April, 2014
2090 //--------------------------------------------------------------------------
childObjVersion(const H5std_string & objname) const2091 unsigned H5Location::childObjVersion(const H5std_string& objname) const
2092 {
2093 // Use overloaded function
2094 unsigned version = childObjVersion(objname.c_str());
2095 return(version);
2096 }
2097
2098 #ifndef H5_NO_DEPRECATED_SYMBOLS
2099 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2100 //--------------------------------------------------------------------------
2101 // Function: H5Location::getObjTypeByIdx
2102 ///\brief Returns the type of an object in this group, given the
2103 /// object's index.
2104 ///\param idx - IN: Transient index of the object
2105 ///\return Object type
2106 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
2107 // Programmer Binh-Minh Ribler - January, 2003
2108 //--------------------------------------------------------------------------
getObjTypeByIdx(hsize_t idx) const2109 H5G_obj_t H5Location::getObjTypeByIdx(hsize_t idx) const
2110 {
2111 H5G_obj_t obj_type = H5Gget_objtype_by_idx(getId(), idx);
2112 if (obj_type == H5G_UNKNOWN)
2113 throwException("getObjTypeByIdx", "H5Gget_objtype_by_idx failed");
2114
2115 return (obj_type);
2116 }
2117
2118 //--------------------------------------------------------------------------
2119 // Function: H5Location::getObjTypeByIdx
2120 ///\brief This is an overloaded member function, provided for convenience.
2121 /// It differs from the above function because it also provides
2122 /// the returned object type in text (char*)
2123 ///\param idx - IN: Transient index of the object
2124 ///\param type_name - OUT: Object type in text
2125 ///\return Object type
2126 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
2127 // Programmer Binh-Minh Ribler - May, 2010
2128 // Modification
2129 // Modified to use the other function. -BMR, 2016/03/07
2130 //--------------------------------------------------------------------------
getObjTypeByIdx(hsize_t idx,char * type_name) const2131 H5G_obj_t H5Location::getObjTypeByIdx(hsize_t idx, char* type_name) const
2132 {
2133 H5std_string stype_name(type_name);
2134 return(getObjTypeByIdx(idx, stype_name));
2135 }
2136 //--------------------------------------------------------------------------
2137 // Function: H5Location::getObjTypeByIdx
2138 ///\brief This is an overloaded member function, provided for convenience.
2139 /// It differs from the above function because it also provides
2140 /// the returned object type in text (H5std_string&)
2141 ///\param idx - IN: Transient index of the object
2142 ///\param type_name - OUT: Object type in text
2143 ///\return Object type
2144 ///\exception H5::FileIException/H5::GroupIException/H5::LocationException
2145 // Programmer Binh-Minh Ribler - January, 2003
2146 //--------------------------------------------------------------------------
getObjTypeByIdx(hsize_t idx,H5std_string & type_name) const2147 H5G_obj_t H5Location::getObjTypeByIdx(hsize_t idx, H5std_string& type_name) const
2148 {
2149 H5G_obj_t obj_type = H5Gget_objtype_by_idx(getId(), idx);
2150 switch (obj_type)
2151 {
2152 case H5G_LINK: type_name = H5std_string("symbolic link"); break;
2153 case H5G_GROUP: type_name = H5std_string("group"); break;
2154 case H5G_DATASET: type_name = H5std_string("dataset"); break;
2155 case H5G_TYPE: type_name = H5std_string("datatype"); break;
2156 case H5G_UNKNOWN:
2157 case H5G_UDLINK:
2158 case H5G_RESERVED_5:
2159 case H5G_RESERVED_6:
2160 case H5G_RESERVED_7:
2161 default:
2162 throwException("getObjTypeByIdx", "H5Gget_objtype_by_idx failed");
2163 }
2164 return (obj_type);
2165 }
2166
2167 #endif // DOXYGEN_SHOULD_SKIP_THIS
2168 #endif /* H5_NO_DEPRECATED_SYMBOLS */
2169
2170 //--------------------------------------------------------------------------
2171 // Function: H5Location::throwException
2172 ///\brief Invokes subclass' throwException
2173 ///\param func_name - Name of the function where failure occurs
2174 ///\param msg - Message describing the failure
2175 ///\exception H5::GroupIException
2176 // Programmer Binh-Minh Ribler - 2000
2177 // Modification
2178 // August 2017 - BMR
2179 // Keep H5Location::throwException and H5File::throwException to
2180 // maintain backward compatibility. For other subclasses, throw
2181 // LocationException.
2182 //--------------------------------------------------------------------------
throwException(const H5std_string & func_name,const H5std_string & msg) const2183 void H5Location::throwException(const H5std_string& func_name, const H5std_string& msg) const
2184 {
2185 throw LocationException(inMemFunc(func_name.c_str()), msg);
2186 }
2187
2188 //--------------------------------------------------------------------------
2189 // Function: f_DataSet_setId - friend
2190 // Modification:
2191 // Moved to H5CommonFG.cpp after the rearrangement of classes
2192 // -BMR, Dec 2016
2193 //--------------------------------------------------------------------------
2194
2195 // end of From H5CommonFG.cpp
2196
2197 //--------------------------------------------------------------------------
2198 // Function: f_Attribute_setId - friend
2199 // Modification:
2200 // Moved to H5Object.cpp after the rearrangement of classes
2201 // -BMR, Dec 2016
2202 //--------------------------------------------------------------------------
2203
2204 //--------------------------------------------------------------------------
2205 // Function: f_DataSpace_setId - friend
2206 // Purpose This function is friend to class H5::DataSpace so that it can
2207 // can set DataSpace::id in order to work around a problem
2208 // described in the JIRA issue HDFFV-7947.
2209 // Applications shouldn't need to use it.
2210 // param dspace - IN/OUT: DataSpace object to be changed
2211 // param new_id - IN: New id to set
2212 // Programmer Binh-Minh Ribler - 2015
2213 //--------------------------------------------------------------------------
f_DataSpace_setId(DataSpace * dspace,hid_t new_id)2214 void f_DataSpace_setId(DataSpace* dspace, hid_t new_id)
2215 {
2216 dspace->p_setId(new_id);
2217 }
2218
2219 //--------------------------------------------------------------------------
2220 // Function: H5Location destructor
2221 ///\brief Noop destructor.
2222 // Programmer Binh-Minh Ribler - 2000
2223 //--------------------------------------------------------------------------
~H5Location()2224 H5Location::~H5Location() {}
2225
2226 #endif // DOXYGEN_SHOULD_SKIP_THIS
2227
2228 } // end namespace
2229