// C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://www.hdfgroup.org/licenses. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ #ifndef __H5Location_H #define __H5Location_H #include "H5Classes.h" // constains forward class declarations namespace H5 { class H5Location; // forward declaration for UserData4Aiterate // Define the operator function pointer for H5Aiterate(). typedef void (*attr_operator_t)(H5Location &loc /*in*/, const H5std_string attr_name /*in*/, void *operator_data /*in,out*/); class UserData4Aiterate { // user data for attribute iteration public: attr_operator_t op; void * opData; H5Location * location; }; /*! \class H5Location \brief H5Location is an abstract base class, providing a collection of wrappers of the C functions that take a location identifier, which can be either file, group, dataset, attribute, or named datatype. */ // Inheritance: IdComponent class H5_DLLCPP H5Location : public IdComponent { public: // Determines the number of attributes belong to this object. int getNumAttrs() const; // Checks if a link of a given name exists in this location bool nameExists(const char *name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; bool nameExists(const H5std_string &name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Flushes all buffers associated with this location to disk. void flush(H5F_scope_t scope) const; // Gets the name of the file, specified by this location. H5std_string getFileName() const; // Retrieves information about an object at this location // specified by location void getObjectInfo(H5O_info_t *oinfo) const; // specified by the object's name void getObjectInfo(const char *name, H5O_info_t *oinfo, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; void getObjectInfo(const H5std_string &name, H5O_info_t *oinfo, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; #ifndef H5_NO_DEPRECATED_SYMBOLS // Retrieves the type of object that an object reference points to. H5G_obj_t getObjType(void *ref, H5R_type_t ref_type = H5R_OBJECT) const; #endif /* H5_NO_DEPRECATED_SYMBOLS */ // Retrieves the type of object that an object reference points to. H5O_type_t getRefObjType(void *ref, H5R_type_t ref_type = H5R_OBJECT) const; // Note: getRefObjType deprecates getObjType, but getObjType's name is // misleading, so getRefObjType is used in the new function instead. // Returns the object header version of an object unsigned objVersion() const; // Sets the comment for an HDF5 object specified by its name. void setComment(const char *name, const char *comment) const; void setComment(const H5std_string &name, const H5std_string &comment) const; void setComment(const char *comment) const; void setComment(const H5std_string &comment) const; // Retrieves comment for the HDF5 object specified by its name. ssize_t getComment(const char *name, size_t buf_size, char *comment) const; H5std_string getComment(const char *name, size_t buf_size = 0) const; H5std_string getComment(const H5std_string &name, size_t buf_size = 0) const; // Removes the comment for the HDF5 object specified by its name. void removeComment(const char *name) const; void removeComment(const H5std_string &name) const; // Creates a reference to a named object or to a dataset region // in this object. void reference(void *ref, const char *name, H5R_type_t ref_type = H5R_OBJECT) const; void reference(void *ref, const H5std_string &name, H5R_type_t ref_type = H5R_OBJECT) const; void reference(void *ref, const char *name, const DataSpace &dataspace, H5R_type_t ref_type = H5R_DATASET_REGION) const; void reference(void *ref, const H5std_string &name, const DataSpace &dataspace, H5R_type_t ref_type = H5R_DATASET_REGION) const; // Open a referenced object whose location is specified by either // a file, an HDF5 object, or an attribute. void dereference(const H5Location &loc, const void *ref, H5R_type_t ref_type = H5R_OBJECT); void dereference(const Attribute &attr, const void *ref, H5R_type_t ref_type = H5R_OBJECT); // Retrieves a dataspace with the region pointed to selected. DataSpace getRegion(void *ref, H5R_type_t ref_type = H5R_DATASET_REGION) const; // Opens an object at this location, without knowing the object type. hid_t openObjId(const char *name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; hid_t openObjId(const H5std_string &name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Closes an object opened by openObjId() static void closeObjId(hid_t obj_id); // Creates a soft link from link_name to target_name. void link(const char *target_name, const char *link_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; void link(const H5std_string &target_name, const H5std_string &link_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; // Creates a hard link from new_name to curr_name. void link(const char *curr_name, const H5Location &new_loc, const char *new_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; void link(const H5std_string &curr_name, const H5Location &new_loc, const H5std_string &new_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; // Creates a hard link from new_name to curr_name in same location. void link(const char *curr_name, const hid_t same_loc, const char *new_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; void link(const H5std_string &curr_name, const hid_t same_loc, const H5std_string &new_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; // Removes the specified link from this location. void unlink(const char *link_name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; void unlink(const H5std_string &link_name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Copies a link from this location to another. void copyLink(const char *src_name, const H5Location &dst, const char *dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; void copyLink(const H5std_string &src_name, const H5Location &dst, const H5std_string &dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; // Makes a copy of a link in the same location. void copyLink(const char *src_name, const char *dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; void copyLink(const H5std_string &src_name, const H5std_string &dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; // Renames a link in this location and moves to a new location. void moveLink(const char *src_name, const H5Location &dst, const char *dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; void moveLink(const H5std_string &src_name, const H5Location &dst, const H5std_string &dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; // Renames a link in this location. void moveLink(const char *src_name, const char *dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; void moveLink(const H5std_string &src_name, const H5std_string &dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; // Returns the information of the named link. H5L_info_t getLinkInfo(const char * link_name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; H5L_info_t getLinkInfo(const H5std_string & link_name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Returns the value of a symbolic link. H5std_string getLinkval(const char *link_name, size_t size = 0) const; H5std_string getLinkval(const H5std_string &link_name, size_t size = 0) const; ///\brief Returns an identifier. (pure virtual) virtual hid_t getId() const = 0; /*************************************************************************** Notes for H5A wrappers ====================== These H5A wrappers are marked "deprecated" in 1.8.19. They are moved to H5Object to prevent the object id from being passed in to H5A APIs. Updated: they are removed from source code in 1.8.21. ***************************************************************************/ // Creates an attribute for the specified object at this location // PropList is currently not used, so always be default. // Deprecated // virtual Attribute createAttribute(const char* name, const DataType& type, const DataSpace& space, const // PropList& create_plist = PropList::DEFAULT) const; virtual Attribute createAttribute(const // H5std_string& name, const DataType& type, const DataSpace& space, const PropList& create_plist = // PropList::DEFAULT) const; // Given its name, opens the attribute that belongs to an object at // this location. // Deprecated // virtual Attribute openAttribute(const char* name) const; // virtual Attribute openAttribute(const H5std_string& name) const; // Given its index, opens the attribute that belongs to an object at // this location. // virtual Attribute openAttribute(const unsigned int idx) const; // Deprecated // Iterate user's function over the attributes at this location. virtual int iterateAttrs(attr_operator_t user_op, unsigned *idx = NULL, void *op_data = NULL); // Deprecated // Checks whether the named attribute exists at this location. // Deprecated // virtual bool attrExists(const char* name) const; // virtual bool attrExists(const H5std_string& name) const; // Renames the named attribute to a new name. // Deprecated // virtual void renameAttr(const char* oldname, const char* newname) const; // virtual void renameAttr(const H5std_string& oldname, const H5std_string& newname) const; // Removes the named attribute from this location. // Deprecated // virtual void removeAttr(const char* name) const; // virtual void removeAttr(const H5std_string& name) const; /**************************** End of H5A note *******************************/ protected: #ifndef DOXYGEN_SHOULD_SKIP_THIS // Default constructor H5Location(); // *** Deprecation warning *** // The following two constructors are no longer appropriate after the // data member "id" had been moved to the sub-classes. // The copy constructor is a noop and is removed in 1.8.15 and the // other will be removed from 1.10 release, and then from 1.8 if its // removal does not raise any problems in two 1.10 releases. // Creates a copy of an existing object giving the location id. H5Location(const hid_t loc_id); // Creates a reference to an HDF5 object or a dataset region. void p_reference(void *ref, const char *name, hid_t space_id, H5R_type_t ref_type) const; // Dereferences a ref into an HDF5 id. hid_t p_dereference(hid_t loc_id, const void *ref, H5R_type_t ref_type, const char *from_func); #ifndef H5_NO_DEPRECATED_SYMBOLS // Retrieves the type of object that an object reference points to. H5G_obj_t p_get_obj_type(void *ref, H5R_type_t ref_type) const; #endif /* H5_NO_DEPRECATED_SYMBOLS */ // Retrieves the type of object that an object reference points to. H5O_type_t p_get_ref_obj_type(void *ref, H5R_type_t ref_type) const; // Sets the identifier of this object to a new value. - this one // doesn't increment reference count virtual void p_setId(const hid_t new_id) = 0; #endif // DOXYGEN_SHOULD_SKIP_THIS // Noop destructor. virtual ~H5Location(); }; // end of H5Location } // namespace H5 #endif // __H5Location_H // Modification // Oct 1, 2013 -BMR // H5Location is added in version 1.8.12. // Most of these methods were in H5Object but are now moved here // because a location can be a file, group, dataset, or named datatype. // May 04, 2017 -BMR // Wrappers for H5A functions are copied to H5Object because H5A // functions do not take an attribute id as loc_id. The original // wrappers will be deprecated in future releases.