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 23 \brief H5Location is an abstract base class, added in version 1.8.12. 24 25 It provides a collection of wrappers for the C functions that take a 26 location identifier to specify the HDF5 object. The location identifier 27 can be either file, group, dataset, attribute, or named datatype. 28 Wrappers for H5A functions stay in H5Object. 29 */ 30 // Inheritance: IdComponent 31 class H5_DLLCPP H5Location : public IdComponent { 32 public: 33 // Checks if a link of a given name exists in a location 34 bool nameExists(const char* name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 35 bool nameExists(const H5std_string& name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 36 37 // Checks if a link of a given name exists in a location 38 // Deprecated in favor of nameExists for better name. 39 bool exists(const char* name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 40 bool exists(const H5std_string& name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 41 42 // Flushes all buffers associated with this location to disk. 43 void flush(H5F_scope_t scope) const; 44 45 // Gets the name of the file, specified by this location. 46 H5std_string getFileName() const; 47 48 #ifndef H5_NO_DEPRECATED_SYMBOLS 49 // Retrieves the type of object that an object reference points to. 50 H5G_obj_t getObjType(void *ref, H5R_type_t ref_type = H5R_OBJECT) const; 51 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 52 53 // Retrieves the type of object that an object reference points to. 54 H5O_type_t getRefObjType(void *ref, H5R_type_t ref_type = H5R_OBJECT) const; 55 // Note: getRefObjType deprecates getObjType, but getObjType's name is 56 // misleading, so getRefObjType is used in the new function instead. 57 58 // Sets the comment for an HDF5 object specified by its name. 59 void setComment(const char* name, const char* comment) const; 60 void setComment(const H5std_string& name, const H5std_string& comment) const; 61 void setComment(const char* comment) const; 62 void setComment(const H5std_string& comment) const; 63 64 // Retrieves comment for the HDF5 object specified by its name. 65 ssize_t getComment(const char* name, size_t buf_size, char* comment) const; 66 H5std_string getComment(const char* name, size_t buf_size=0) const; 67 H5std_string getComment(const H5std_string& name, size_t buf_size=0) const; 68 69 // Removes the comment for the HDF5 object specified by its name. 70 void removeComment(const char* name) const; 71 void removeComment(const H5std_string& name) const; 72 73 // Creates a reference to a named object or to a dataset region 74 // in this object. 75 void reference(void* ref, const char* name, 76 H5R_type_t ref_type = H5R_OBJECT) const; 77 void reference(void* ref, const H5std_string& name, 78 H5R_type_t ref_type = H5R_OBJECT) const; 79 void reference(void* ref, const char* name, const DataSpace& dataspace, 80 H5R_type_t ref_type = H5R_DATASET_REGION) const; 81 void reference(void* ref, const H5std_string& name, const DataSpace& dataspace, 82 H5R_type_t ref_type = H5R_DATASET_REGION) const; 83 84 // Open a referenced object whose location is specified by either 85 // a file, an HDF5 object, or an attribute. 86 void dereference(const H5Location& loc, const void* ref, H5R_type_t ref_type = H5R_OBJECT, const PropList& plist = PropList::DEFAULT); 87 // Removed in 1.10.1, because H5Location is baseclass 88 //void dereference(const Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT, const PropList& plist = PropList::DEFAULT); 89 90 // Retrieves a dataspace with the region pointed to selected. 91 DataSpace getRegion(void *ref, H5R_type_t ref_type = H5R_DATASET_REGION) const; 92 93 // Create a new group with using link create property list. 94 Group createGroup(const char* name, const LinkCreatPropList& lcpl) const; 95 Group createGroup(const H5std_string& name, const LinkCreatPropList& lcpl) const; 96 97 // From CommonFG 98 // Creates a new group at this location which can be a file 99 // or another group. 100 Group createGroup(const char* name, size_t size_hint = 0) const; 101 Group createGroup(const H5std_string& name, size_t size_hint = 0) const; 102 103 // Opens an existing group in a location which can be a file 104 // or another group. 105 Group openGroup(const char* name) const; 106 Group openGroup(const H5std_string& name) const; 107 108 // Creates a new dataset in this location. 109 DataSet createDataSet(const char* name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist = DSetCreatPropList::DEFAULT, const DSetAccPropList& dapl = DSetAccPropList::DEFAULT, const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT) const; 110 DataSet createDataSet(const H5std_string& name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist = DSetCreatPropList::DEFAULT, const DSetAccPropList& dapl = DSetAccPropList::DEFAULT, const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT) const; 111 112 // Deprecated to add LinkCreatPropList and DSetAccPropList - 1.10.3 113 // DataSet createDataSet(const char* name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist = DSetCreatPropList::DEFAULT) const; 114 // DataSet createDataSet(const H5std_string& name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist = DSetCreatPropList::DEFAULT) const; 115 116 // Opens an existing dataset at this location. 117 // DSetAccPropList is added - 1.10.3 118 DataSet openDataSet(const char* name, const DSetAccPropList& dapl = DSetAccPropList::DEFAULT) const; 119 DataSet openDataSet(const H5std_string& name, const DSetAccPropList& dapl = DSetAccPropList::DEFAULT) const; 120 121 H5L_info_t getLinkInfo(const char* link_name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 122 H5L_info_t getLinkInfo(const H5std_string& link_name, const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 123 124 // Returns the value of a symbolic link. 125 H5std_string getLinkval(const char* link_name, size_t size=0) const; 126 H5std_string getLinkval(const H5std_string& link_name, size_t size=0) const; 127 128 // Returns the number of objects in this group. 129 // Deprecated - moved to H5::Group in 1.10.2. 130 hsize_t getNumObjs() const; 131 132 // Retrieves the name of an object in this group, given the 133 // object's index. 134 H5std_string getObjnameByIdx(hsize_t idx) const; 135 ssize_t getObjnameByIdx(hsize_t idx, char* name, size_t size) const; 136 ssize_t getObjnameByIdx(hsize_t idx, H5std_string& name, size_t size) const; 137 138 // Retrieves the type of an object in this file or group, given the 139 // object's name 140 H5O_type_t childObjType(const H5std_string& objname) const; 141 H5O_type_t childObjType(const char* objname) const; 142 H5O_type_t childObjType(hsize_t index, H5_index_t index_type=H5_INDEX_NAME, H5_iter_order_t order=H5_ITER_INC, const char* objname=".") const; 143 144 // Returns the object header version of an object in this file or group, 145 // given the object's name. 146 unsigned childObjVersion(const char* objname) const; 147 unsigned childObjVersion(const H5std_string& objname) const; 148 149 // Retrieves information about an HDF5 object. 150 void getObjinfo(H5O_info_t& objinfo, unsigned fields = H5O_INFO_BASIC) const; 151 152 // Retrieves information about an HDF5 object, given its name. 153 void getObjinfo(const char* name, H5O_info_t& objinfo, 154 unsigned fields = H5O_INFO_BASIC, 155 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 156 void getObjinfo(const H5std_string& name, H5O_info_t& objinfo, 157 unsigned fields = H5O_INFO_BASIC, 158 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 159 160 // Retrieves information about an HDF5 object, given its index. 161 void getObjinfo(const char* grp_name, H5_index_t idx_type, 162 H5_iter_order_t order, hsize_t idx, H5O_info_t& objinfo, 163 unsigned fields = H5O_INFO_BASIC, 164 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 165 void getObjinfo(const H5std_string& grp_name, H5_index_t idx_type, 166 H5_iter_order_t order, hsize_t idx, H5O_info_t& objinfo, 167 unsigned fields = H5O_INFO_BASIC, 168 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 169 170 #ifndef H5_NO_DEPRECATED_SYMBOLS 171 // Returns the type of an object in this group, given the 172 // object's index. 173 H5G_obj_t getObjTypeByIdx(hsize_t idx) const; 174 H5G_obj_t getObjTypeByIdx(hsize_t idx, char* type_name) const; 175 H5G_obj_t getObjTypeByIdx(hsize_t idx, H5std_string& type_name) const; 176 177 // Returns information about an HDF5 object, given by its name, 178 // at this location. - Deprecated 179 void getObjinfo(const char* name, hbool_t follow_link, H5G_stat_t& statbuf) const; 180 void getObjinfo(const H5std_string& name, hbool_t follow_link, H5G_stat_t& statbuf) const; 181 void getObjinfo(const char* name, H5G_stat_t& statbuf) const; 182 void getObjinfo(const H5std_string& name, H5G_stat_t& statbuf) const; 183 184 // Iterates over the elements of this group - not implemented in 185 // C++ style yet. 186 int iterateElems(const char* name, int *idx, H5G_iterate_t op, void *op_data); 187 int iterateElems(const H5std_string& name, int *idx, H5G_iterate_t op, void *op_data); 188 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 189 190 // Creates a soft link from link_name to target_name. 191 void link(const char *target_name, const char *link_name, 192 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 193 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 194 void link(const H5std_string& target_name, 195 const H5std_string& link_name, 196 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 197 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 198 199 // Creates a hard link from new_name to curr_name. 200 void link(const char *curr_name, 201 const Group& new_loc, const char *new_name, 202 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 203 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 204 void link(const H5std_string& curr_name, 205 const Group& new_loc, const H5std_string& new_name, 206 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 207 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 208 209 // Creates a hard link from new_name to curr_name in same location. 210 void link(const char *curr_name, 211 const hid_t same_loc, const char *new_name, 212 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 213 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 214 void link(const H5std_string& curr_name, 215 const hid_t same_loc, const H5std_string& new_name, 216 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 217 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 218 219 // Creates a link of the specified type from new_name to current_name; 220 // both names are interpreted relative to the specified location id. 221 // Deprecated due to inadequate functionality. 222 void link(H5L_type_t link_type, const char* curr_name, const char* new_name) const; 223 void link(H5L_type_t link_type, const H5std_string& curr_name, const H5std_string& new_name) const; 224 225 // Removes the specified link from this location. 226 void unlink(const char *link_name, 227 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 228 void unlink(const H5std_string& link_name, 229 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 230 231 // Mounts the file 'child' onto this location. 232 void mount(const char* name, const H5File& child, const PropList& plist) const; 233 void mount(const H5std_string& name, const H5File& child, const PropList& plist) const; 234 235 // Unmounts the file named 'name' from this parent location. 236 void unmount(const char* name) const; 237 void unmount(const H5std_string& name) const; 238 239 // Copies a link from a group to another. 240 void copyLink(const char *src_name, 241 const Group& dst, const char *dst_name, 242 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 243 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 244 void copyLink(const H5std_string& src_name, 245 const Group& dst, const H5std_string& dst_name, 246 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 247 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 248 249 // Makes a copy of a link in the same group. 250 void copyLink(const char *src_name, const char *dst_name, 251 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 252 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 253 void copyLink(const H5std_string& src_name, 254 const H5std_string& dst_name, 255 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 256 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 257 258 // Renames a link in this group and moves to a new location. 259 void moveLink(const char* src_name, 260 const Group& dst, const char* dst_name, 261 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 262 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 263 void moveLink(const H5std_string& src_name, 264 const Group& dst, const H5std_string& dst_name, 265 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 266 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 267 268 // Renames a link in this group. 269 void moveLink(const char* src_name, const char* dst_name, 270 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 271 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 272 void moveLink(const H5std_string& src_name, 273 const H5std_string& dst_name, 274 const LinkCreatPropList& lcpl = LinkCreatPropList::DEFAULT, 275 const LinkAccPropList& lapl = LinkAccPropList::DEFAULT) const; 276 277 // Renames an object at this location. 278 // Deprecated due to inadequate functionality. 279 void move(const char* src, const char* dst) const; 280 void move(const H5std_string& src, const H5std_string& dst) const; 281 282 // end From CommonFG 283 284 /// For subclasses, H5File and Group, to throw appropriate exception. 285 virtual void throwException(const H5std_string& func_name, const H5std_string& msg) const; 286 287 // Default constructor 288 H5Location(); 289 290 protected: 291 #ifndef DOXYGEN_SHOULD_SKIP_THIS 292 // *** Deprecation warning *** 293 // The following two constructors are no longer appropriate after the 294 // data member "id" had been moved to the sub-classes. 295 // The copy constructor is a noop and is removed in 1.8.15 and the 296 // other will be removed from 1.10 release, and then from 1.8 if its 297 // removal does not raise any problems in two 1.10 releases. 298 299 // Creates a copy of an existing object giving the location id. 300 // H5Location(const hid_t loc_id); 301 302 // Creates a reference to an HDF5 object or a dataset region. 303 void p_reference(void* ref, const char* name, hid_t space_id, H5R_type_t ref_type) const; 304 305 // Dereferences a ref into an HDF5 id. 306 hid_t p_dereference(hid_t loc_id, const void* ref, H5R_type_t ref_type, const PropList& plist, const char* from_func); 307 308 #ifndef H5_NO_DEPRECATED_SYMBOLS 309 // Retrieves the type of object that an object reference points to. 310 H5G_obj_t p_get_obj_type(void *ref, H5R_type_t ref_type) const; 311 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 312 313 // Retrieves the type of object that an object reference points to. 314 H5O_type_t p_get_ref_obj_type(void *ref, H5R_type_t ref_type) const; 315 316 // Sets the identifier of this object to a new value. - this one 317 // doesn't increment reference count 318 //virtual void p_setId(const hid_t new_id); 319 320 #endif // DOXYGEN_SHOULD_SKIP_THIS 321 322 // Noop destructor. 323 virtual ~H5Location(); 324 325 }; // end of H5Location 326 } // namespace H5 327 328 #endif // __H5Location_H 329