HDF5 C++ API  1.8.20
 All Classes Namespaces Functions Variables Typedefs Friends Pages
H5Location.h
1 // C++ informative line for the emacs editor: -*- C++ -*-
2 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
3  * Copyright by The HDF Group. *
4  * Copyright by the Board of Trustees of the University of Illinois. *
5  * All rights reserved. *
6  * *
7  * This file is part of HDF5. The full HDF5 copyright notice, including *
8  * terms governing use, modification, and redistribution, is contained in *
9  * the COPYING file, which can be found at the root of the source code *
10  * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. *
11  * If you do not have access to either file, you may request a copy from *
12  * help@hdfgroup.org. *
13  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
14 
15 #ifndef __H5Location_H
16 #define __H5Location_H
17 
18 #include "H5Classes.h" // constains forward class declarations
19 
20 namespace H5 {
21 
22 class H5Location; // forward declaration for UserData4Aiterate
23 
24 // Define the operator function pointer for H5Aiterate().
25 typedef void (*attr_operator_t)(H5Location& loc/*in*/,
26  const H5std_string attr_name/*in*/,
27  void *operator_data/*in,out*/);
28 
29 class UserData4Aiterate { // user data for attribute iteration
30  public:
32  void* opData;
34 };
35 
41 // Inheritance: IdComponent
42 class H5_DLLCPP H5Location : public IdComponent {
43  public:
44  // Checks if a link of a given name exists in this location
45  bool nameExists(const char* name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const;
46  bool nameExists(const H5std_string& name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const;
47 
48  // Flushes all buffers associated with this location to disk.
49  void flush(H5F_scope_t scope) const;
50 
51  // Gets the name of the file, specified by this location.
52  H5std_string getFileName() const;
53 
54  // Retrieves information about an object at this location
55  // specified by location
56  void getObjectInfo(H5O_info_t *oinfo) const;
57  // specified by the object's name
58  void getObjectInfo(const char *name, H5O_info_t *oinfo,
59  const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const;
60  void getObjectInfo(const H5std_string& name, H5O_info_t *oinfo,
61  const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const;
62 
63  // Determines the number of attributes at this location.
64  // - moved to H5Object (1.8.20)
65  int getNumAttrs() const; // Deprecated
66 
67 #ifndef H5_NO_DEPRECATED_SYMBOLS
68  // Retrieves the type of object that an object reference points to.
69  H5G_obj_t getObjType(void *ref, H5R_type_t ref_type = H5R_OBJECT) const;
70 #endif /* H5_NO_DEPRECATED_SYMBOLS */
71 
72  // Retrieves the type of object that an object reference points to.
73  H5O_type_t getRefObjType(void *ref, H5R_type_t ref_type = H5R_OBJECT) const;
74  // Note: getRefObjType deprecates getObjType, but getObjType's name is
75  // misleading, so getRefObjType is used in the new function instead.
76 
77  // Returns the object header version of an object
78  unsigned objVersion() const;
79 
80  // Sets the comment for an HDF5 object specified by its name.
81  void setComment(const char* name, const char* comment) const;
82  void setComment(const H5std_string& name, const H5std_string& comment) const;
83  void setComment(const char* comment) const;
84  void setComment(const H5std_string& comment) const;
85 
86  // Retrieves comment for the HDF5 object specified by its name.
87  ssize_t getComment(const char* name, size_t buf_size, char* comment) const;
88  H5std_string getComment(const char* name, size_t buf_size=0) const;
89  H5std_string getComment(const H5std_string& name, size_t buf_size=0) const;
90 
91  // Removes the comment for the HDF5 object specified by its name.
92  void removeComment(const char* name) const;
93  void removeComment(const H5std_string& name) const;
94 
95  // Creates a reference to a named object or to a dataset region
96  // in this object.
97  void reference(void* ref, const char* name,
98  H5R_type_t ref_type = H5R_OBJECT) const;
99  void reference(void* ref, const H5std_string& name,
100  H5R_type_t ref_type = H5R_OBJECT) const;
101  void reference(void* ref, const char* name, const DataSpace& dataspace,
102  H5R_type_t ref_type = H5R_DATASET_REGION) const;
103  void reference(void* ref, const H5std_string& name, const DataSpace& dataspace,
104  H5R_type_t ref_type = H5R_DATASET_REGION) const;
105 
106  // Open a referenced object whose location is specified by either
107  // a file, an HDF5 object, or an attribute.
108  void dereference(const H5Location& loc, const void* ref, H5R_type_t ref_type = H5R_OBJECT);
109  void dereference(const Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT);
110 
111  // Retrieves a dataspace with the region pointed to selected.
112  DataSpace getRegion(void *ref, H5R_type_t ref_type = H5R_DATASET_REGION) const;
113 
114  // Opens an object at this location, without knowing the object type.
115  hid_t openObjId(const char* name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const;
116  hid_t openObjId(const H5std_string& name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const;
117 
118  // Closes an object opened by openObjId().
119  void closeObjId(hid_t obj_id) const;
120 
122  virtual hid_t getId() const = 0;
123 
124 /***************************************************************************
125  Notes for H5A wrappers
126  ======================
127  These H5A wrappers are marked "deprecated" in 1.8.19.
128  They are moved to H5Object to prevent the object id from being
129  passed in to H5A APIs.
130 ***************************************************************************/
131 
132  // Creates an attribute for the specified object at this location
133  // PropList is currently not used, so always be default.
134  // Deprecated
135  virtual Attribute createAttribute(const char* name, const DataType& type, const DataSpace& space, const PropList& create_plist = PropList::DEFAULT) const;
136  virtual Attribute createAttribute(const H5std_string& name, const DataType& type, const DataSpace& space, const PropList& create_plist = PropList::DEFAULT) const;
137 
138  // Given its name, opens the attribute that belongs to an object at
139  // this location.
140  // Deprecated
141  virtual Attribute openAttribute(const char* name) const;
142  virtual Attribute openAttribute(const H5std_string& name) const;
143 
144  // Given its index, opens the attribute that belongs to an object at
145  // this location.
146  virtual Attribute openAttribute(const unsigned int idx) const; // Deprecated
147 
148  // Iterate user's function over the attributes at this location.
149  virtual int iterateAttrs(attr_operator_t user_op, unsigned* idx = NULL,
150  void* op_data = NULL); // Deprecated
151 
152  // Checks whether the named attribute exists at this location.
153  // Deprecated
154  virtual bool attrExists(const char* name) const;
155  virtual bool attrExists(const H5std_string& name) const;
156 
157  // Renames the named attribute to a new name.
158  // Deprecated
159  virtual void renameAttr(const char* oldname, const char* newname) const;
160  virtual void renameAttr(const H5std_string& oldname, const H5std_string& newname) const;
161 
162  // Removes the named attribute from this location.
163  // Deprecated
164  virtual void removeAttr(const char* name) const;
165  virtual void removeAttr(const H5std_string& name) const;
166 
167 /**************************** End of H5A note *******************************/
168 
169  protected:
170 #ifndef DOXYGEN_SHOULD_SKIP_THIS
171  // Default constructor,
172  H5Location();
173 
174  // *** Deprecation warning ***
175  // The following two constructors are no longer appropriate after the
176  // data member "id" had been moved to the sub-classes.
177  // The copy constructor is a noop and is removed in 1.8.15 and the
178  // other will be removed from 1.10 release, and then from 1.8 if its
179  // removal does not raise any problems in two 1.10 releases.
180 
181  // Creates a copy of an existing object giving the location id.
182  H5Location(const hid_t loc_id);
183 
184  // Creates a reference to an HDF5 object or a dataset region.
185  void p_reference(void* ref, const char* name, hid_t space_id, H5R_type_t ref_type) const;
186 
187  // Dereferences a ref into an HDF5 id.
188  hid_t p_dereference(hid_t loc_id, const void* ref, H5R_type_t ref_type, const char* from_func);
189 
190 #ifndef H5_NO_DEPRECATED_SYMBOLS
191  // Retrieves the type of object that an object reference points to.
192  H5G_obj_t p_get_obj_type(void *ref, H5R_type_t ref_type) const;
193 #endif /* H5_NO_DEPRECATED_SYMBOLS */
194 
195  // Retrieves the type of object that an object reference points to.
196  H5O_type_t p_get_ref_obj_type(void *ref, H5R_type_t ref_type) const;
197 
198  // Sets the identifier of this object to a new value. - this one
199  // doesn't increment reference count
200  virtual void p_setId(const hid_t new_id) = 0;
201 
202 #endif // DOXYGEN_SHOULD_SKIP_THIS
203 
204  // Noop destructor.
205  virtual ~H5Location();
206 
207 }; // end of H5Location
208 } // namespace H5
209 
210 #endif // __H5Location_H
211 
212 // Modification
213 // Oct 1, 2013 -BMR
214 // H5Location is added in version 1.8.12.
215 // Most of these methods were in H5Object but are now moved here
216 // because a location can be a file, group, dataset, or named datatype.
217 // May 04, 2017 -BMR
218 // Wrappers for H5A functions are copied to H5Object because H5A
219 // functions do not take an attribute id as loc_id. The original
220 // wrappers will be deprecated in future releases.
Class IdComponent provides wrappers of the C functions that operate on an HDF5 identifier.
Definition: H5IdComponent.h:27
Class DataSpace inherits from IdComponent and provides wrappers for the HDF5's dataspaces.
Definition: H5DataSpace.h:25
Class Attribute operates on HDF5 attributes.
Definition: H5Attribute.h:29
Class DataType provides generic operations on HDF5 datatypes.
Definition: H5DataType.h:28
H5Location is an abstract base class, providing a collection of wrappers of the C functions that take...
Definition: H5Location.h:42
void * opData
Definition: H5Location.h:32
void(* attr_operator_t)(H5Location &loc, const H5std_string attr_name, void *operator_data)
Definition: H5Location.h:25
H5Location * location
Definition: H5Location.h:33
Class PropList provides operations for generic property lists.
Definition: H5PropList.h:26
static const PropList & DEFAULT
Default property list.
Definition: H5PropList.h:29
Definition: H5Location.h:29
attr_operator_t op
Definition: H5Location.h:31


The HDF Group Help Desk:
  Copyright by The HDF Group
and the Board of Trustees of the University of Illinois