Purpose: Add new C++ wrappers (HDFFV-10156)

Description:
    Added wrappers for H5Iis_valid, H5Ps/get_nlinks, H5Tget_create_plist,
    H5Oopen, and H5Oclose

        // Checks if the given ID is valid.
        static bool isValid(hid_t an_id);

        // Sets the number of soft or user-defined links that can be
        // traversed before a failure occurs.
        void setNumLinks(size_t nlinks) const;

        // Gets the number of soft or user-defined link traversals allowed
        size_t getNumLinks() const;

        // Returns a copy of the creation property list of a datatype.
        PropList getCreatePlist() const;

        // Opens an object within a group or a file, i.e., root group.
        hid_t openObjId(const char* name,...);
        hid_t openObjId(const H5std_string& name,...);

        // Closes an object opened by getObjId().
        void closeObjId(hid_t obj_id) const;

        // Gets general information about this file.
        void getFileInfo(H5F_info2_t& file_info) const;

Platforms tested:
    Linux/32 2.6 (jam)
    Linux/64 (platypus)
    Darwin (osx1010test)

13 files changed, 233 insertions, 27 deletions

diff --git a/c++/src/H5DataType.cpp b/c++/src/H5DataType.cpp
index 84e59e8..679f42f 100644
--- a/c++/src/H5DataType.cpp
+++ b/c++/src/H5DataType.cpp
@@ -681,6 +681,31 @@ bool DataType::isVariableStr() const
 }
 
 //--------------------------------------------------------------------------
+// Function:    DataType::getCreatePlist
+///\brief       Returns a copy of the property list, which is for datatype
+///             creation.
+///\return      A property list object
+///\exception   H5::DataTypeIException
+// Programmer   Binh-Minh Ribler - May, 2017
+// Description
+//              Currently, there is no datatype creation property list class
+//              in the C++ API because there is no associated functionality.
+//--------------------------------------------------------------------------
+PropList DataType::getCreatePlist() const
+{
+    hid_t create_plist_id = H5Tget_create_plist(id);
+    if (create_plist_id < 0)
+    {
+        throw DataTypeIException(inMemFunc("getCreatePlist"),
+            "H5Tget_create_plist returns negative value");
+    }
+    // create and return the DSetCreatPropList object
+    PropList create_plist;
+    f_PropList_setId(&create_plist, create_plist_id);
+    return(create_plist);
+}
+
+//--------------------------------------------------------------------------
 // Function:    DataType::getId
 ///\brief       Get the id of this datatype
 ///\return      Datatype identifier
diff --git a/c++/src/H5DataType.h b/c++/src/H5DataType.h
index 1118dcf..ac998ef 100644
--- a/c++/src/H5DataType.h
+++ b/c++/src/H5DataType.h
@@ -111,6 +111,9 @@ class H5_DLLCPP DataType : public H5Object {
         // Checks whether this datatype is a variable-length string.
         bool isVariableStr() const;
 
+        // Returns a copy of the creation property list of a datatype.
+        PropList getCreatePlist() const;
+
         ///\brief Returns this class name.
         virtual H5std_string fromClass () const { return("DataType"); }
 
diff --git a/c++/src/H5Exception.cpp b/c++/src/H5Exception.cpp
index ebb7d62..ed10044 100644
--- a/c++/src/H5Exception.cpp
+++ b/c++/src/H5Exception.cpp
@@ -425,6 +425,29 @@ DataTypeIException::DataTypeIException(const H5std_string& func, const H5std_str
 DataTypeIException::~DataTypeIException() throw() {}
 
 //--------------------------------------------------------------------------
+// Subclass:    ObjHeaderIException
+// Programmer   Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
+//--------------------------------------------------------------------------
+// Function:    ObjHeaderIException default constructor
+///\brief       Default constructor.
+//--------------------------------------------------------------------------
+ObjHeaderIException::ObjHeaderIException():Exception(){}
+//--------------------------------------------------------------------------
+// Function:    ObjHeaderIException overloaded constructor
+///\brief       Creates an ObjHeaderIException with the name of the function,
+///             in which the failure occurs, and an optional detailed message.
+///\param       func - IN: Name of the function where failure occurs
+///\param       message   - IN: Message on the failure
+//--------------------------------------------------------------------------
+ObjHeaderIException::ObjHeaderIException(const H5std_string& func, const H5std_string& message) : Exception(func, message) {}
+//--------------------------------------------------------------------------
+// Function:    ObjHeaderIException destructor
+///\brief       Noop destructor.
+//--------------------------------------------------------------------------
+ObjHeaderIException::~ObjHeaderIException() throw() {}
+
+//--------------------------------------------------------------------------
 // Subclass:    PropListIException
 // Programmer   Binh-Minh Ribler - 2000
 //--------------------------------------------------------------------------
diff --git a/c++/src/H5Exception.h b/c++/src/H5Exception.h
index b57ca64..b8f29a4 100644
--- a/c++/src/H5Exception.h
+++ b/c++/src/H5Exception.h
@@ -121,6 +121,13 @@ class H5_DLLCPP DataTypeIException : public Exception {
         virtual ~DataTypeIException() throw();
 };
 
+class H5_DLLCPP ObjHeaderIException : public Exception {
+   public:
+        ObjHeaderIException(const H5std_string& func_name, const H5std_string& message = DEFAULT_MSG);
+        ObjHeaderIException();
+        virtual ~ObjHeaderIException() throw();
+};
+
 class H5_DLLCPP PropListIException : public Exception {
    public:
         PropListIException(const H5std_string& func_name, const H5std_string& message = DEFAULT_MSG);
diff --git a/c++/src/H5File.cpp b/c++/src/H5File.cpp
index 4d7177a..e84717c 100644
--- a/c++/src/H5File.cpp
+++ b/c++/src/H5File.cpp
@@ -349,6 +349,25 @@ FileAccPropList H5File::getAccessPlist() const
 }
 
 //--------------------------------------------------------------------------
+// Function:    H5File::getFileInfo
+///\brief       Retrieves the general information of this file.
+///
+///\exception   H5::FileIException
+///\par Description
+///             The retrieved information may include information about
+///             superblock extension, free space management, and shared object
+// Programmer   Binh-Minh Ribler - May 2017
+//--------------------------------------------------------------------------
+void H5File::getFileInfo(H5F_info_t& file_info) const
+{
+    herr_t ret_value = H5Fget_info(id, &file_info);
+    if (ret_value < 0)
+    {
+        throw FileIException("H5File::getFileInfo", "H5Fget_info failed");
+    }
+}
+
+//--------------------------------------------------------------------------
 // Function:    H5File::getFreeSpace
 ///\brief       Returns the amount of free space in the file.
 ///\return      Amount of free space
diff --git a/c++/src/H5File.h b/c++/src/H5File.h
index e06a942..06c4edc 100644
--- a/c++/src/H5File.h
+++ b/c++/src/H5File.h
@@ -54,6 +54,9 @@ class H5_DLLCPP H5File : public Group {
         // Gets the creation property list of this file.
         FileCreatPropList getCreatePlist() const;
 
+        // Gets general information about this file.
+        void getFileInfo(H5F_info_t& file_info) const;
+
         // Retrieves the file size of an opened file.
         hsize_t getFileSize() const;
 
diff --git a/c++/src/H5Group.cpp b/c++/src/H5Group.cpp
index a5d052c..07e76a2 100644
--- a/c++/src/H5Group.cpp
+++ b/c++/src/H5Group.cpp
@@ -105,11 +105,16 @@ Group::Group(const H5Location& loc, const void* ref, H5R_type_t ref_type) : H5Ob
 ///\param       ref_type - IN: Reference type - default to H5R_OBJECT
 ///\exception   H5::ReferenceException
 // Programmer   Binh-Minh Ribler - Oct, 2006
+// Modification
+//      May, 2017
+//              Removed in 1.8.19 because H5Location is Attribute's baseclass
+//              now. -BMR
 //--------------------------------------------------------------------------
-Group::Group(const Attribute& attr, const void* ref, H5R_type_t ref_type) : H5Object(), id(H5I_INVALID_HID)
+/*Group::Group(const Attribute& attr, const void* ref, H5R_type_t ref_type) : H5Object(), id(H5I_INVALID_HID)
 {
     id = H5Location::p_dereference(attr.getId(), ref, ref_type, "constructor - by dereference");
 }
+*/
 
 //--------------------------------------------------------------------------
 // Function:    Group::getId
diff --git a/c++/src/H5Group.h b/c++/src/H5Group.h
index 0d26b27..ab5b186 100644
--- a/c++/src/H5Group.h
+++ b/c++/src/H5Group.h
@@ -39,7 +39,8 @@ class H5_DLLCPP Group : public H5Object, public CommonFG {
 
         // Creates a group by way of dereference.
         Group(const H5Location& loc, const void* ref, H5R_type_t ref_type = H5R_OBJECT);
-        Group(const Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT);
+        // Removed in 1.10.1, because H5Location is baseclass
+        //Group(const Attribute& attr, const void* ref, H5R_type_t ref_type = H5R_OBJECT);
 
         // default constructor
         Group();
diff --git a/c++/src/H5IdComponent.cpp b/c++/src/H5IdComponent.cpp
index 7054369..a8e8ba4 100644
--- a/c++/src/H5IdComponent.cpp
+++ b/c++/src/H5IdComponent.cpp
@@ -163,6 +163,27 @@ H5I_type_t IdComponent::getHDFObjType() const
 }
 
 //--------------------------------------------------------------------------
+// Function:    isValid (static)
+///\brief       Checks if the given ID is valid.
+///\return      true if the given identifier is valid, and false, otherwise.
+///\par Description
+///             A valid ID is one that is in use and has an application
+///             reference count of at least 1.
+// Programmer   Binh-Minh Ribler - Mar 1, 2017
+//--------------------------------------------------------------------------
+bool IdComponent::isValid(hid_t an_id)
+{
+    // Call C function
+    htri_t ret_value = H5Iis_valid(an_id);
+    if (ret_value > 0)
+        return true;
+    else if (ret_value == 0)
+        return false;
+    else // Raise exception when H5Iis_valid returns a negative value
+        throw IdComponentException("isValid", "H5Iis_valid failed");
+}
+
+//--------------------------------------------------------------------------
 // Function:    IdComponent::operator=
 ///\brief       Assignment operator.
 ///\param       rhs - IN: Reference to the existing object
diff --git a/c++/src/H5IdComponent.h b/c++/src/H5IdComponent.h
index e9d0c84..1ada605 100644
--- a/c++/src/H5IdComponent.h
+++ b/c++/src/H5IdComponent.h
@@ -47,6 +47,9 @@ class H5_DLLCPP IdComponent {
         // Returns an HDF5 object type of this object.
         H5I_type_t getHDFObjType() const;
 
+        // Checks if the given ID is valid.
+        static bool isValid(hid_t an_id);
+
         // Assignment operator.
         IdComponent& operator=(const IdComponent& rhs);
 
diff --git a/c++/src/H5Library.cpp b/c++/src/H5Library.cpp
index 7adc508..3e656e5 100644
--- a/c++/src/H5Library.cpp
+++ b/c++/src/H5Library.cpp
@@ -27,7 +27,6 @@
 #include "H5DcreatProp.h"
 #include "H5DxferProp.h"
 #include "H5LaccProp.h"
-#include "H5LaccProp.h"
 #include "H5Location.h"
 #include "H5Object.h"
 #include "H5DataType.h"
diff --git a/c++/src/H5Location.cpp b/c++/src/H5Location.cpp
index f10ad0d..33d0832 100644
--- a/c++/src/H5Location.cpp
+++ b/c++/src/H5Location.cpp
@@ -251,23 +251,6 @@ int H5Location::iterateAttrs(attr_operator_t user_op, unsigned *_idx, void *op_d
 }
 
 //--------------------------------------------------------------------------
-// Function:    H5Location::getNumAttrs
-///\brief       Deprecated - Returns the number of attributes attached to this HDF5 object.
-///\return      Number of attributes
-///\exception   H5::AttributeIException
-// Programmer   Binh-Minh Ribler - 2000
-//--------------------------------------------------------------------------
-int H5Location::getNumAttrs() const
-{
-   H5O_info_t oinfo;    /* Object info */
-
-    if(H5Oget_info(getId(), &oinfo) < 0)
-        throw AttributeIException(inMemFunc("getNumAttrs"), "H5Oget_info failed");
-    else
-        return(static_cast<int>(oinfo.num_attrs));
-}
-
-//--------------------------------------------------------------------------
 // Function:    H5Location::attrExists
 ///\brief       Deprecated - Checks whether the named attribute exists at this location.
 ///\param       name - IN: Name of the attribute to be queried
@@ -354,6 +337,23 @@ void H5Location::renameAttr(const H5std_string& oldname, const H5std_string& new
 }
 
 //--------------------------------------------------------------------------
+// Function:    H5Location::getNumAttrs
+///\brief       Returns the number of attributes attached to this HDF5 object.
+///\return      Number of attributes
+///\exception   H5::AttributeIException
+// Programmer   Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
+int H5Location::getNumAttrs() const
+{
+   H5O_info_t oinfo;    /* Object info */
+
+    if(H5Oget_info(getId(), &oinfo) < 0)
+        throw AttributeIException(inMemFunc("getNumAttrs"), "H5Oget_info failed");
+    else
+        return(static_cast<int>(oinfo.num_attrs));
+}
+
+//--------------------------------------------------------------------------
 // Function:    H5Location::nameExists
 ///\brief       Checks if a link of a given name exists in a location
 ///\param       name - IN: Searched name
@@ -431,6 +431,39 @@ H5std_string H5Location::getFileName() const
 }
 
 //--------------------------------------------------------------------------
+// Function:    H5Location::objVersion
+///\brief       Returns the header version of this HDF5 object.
+///\return      Object version, which can have the following values:
+///             \li \c H5O_VERSION_1
+///             \li \c H5O_VERSION_2
+///\exception   H5::ObjHeaderIException
+///             Exception will be thrown when:
+///             - an error returned by the C API
+///             - version number is not one of the valid values above
+// Programmer   Binh-Minh Ribler - May, 2017
+//--------------------------------------------------------------------------
+unsigned H5Location::objVersion() const
+{
+    H5O_info_t objinfo;
+    unsigned version = 0;
+
+    // Use C API to get information of the object
+    herr_t ret_value = H5Oget_info(getId(), &objinfo);
+
+    // Throw exception if C API returns failure
+    if (ret_value < 0)
+        throw ObjHeaderIException(inMemFunc("objVersion"), "H5Oget_info failed");
+    // Return a valid version or throw an exception for invalid value
+    else
+    {
+        version = objinfo.hdr.version;
+        if (version != H5O_VERSION_1 && version != H5O_VERSION_2)
+            throw ObjHeaderIException(inMemFunc("objVersion"), "Invalid version for object");
+    }
+    return(version);
+}
+
+//--------------------------------------------------------------------------
 // Function:    H5Location::setComment
 ///\brief       Sets or resets the comment for an object specified by its name.
 ///\param       name  - IN: Name of the object
@@ -454,7 +487,7 @@ void H5Location::setComment(const char* name, const char* comment) const
 {
     herr_t ret_value = H5Oset_comment_by_name(getId(), name, comment, H5P_DEFAULT);
     if(ret_value < 0)
-        throw LocationException(inMemFunc("setComment"), "H5Oset_comment_by_name failed");
+        throw ObjHeaderIException(inMemFunc("setComment"), "H5Oset_comment_by_name failed");
 }
 
 //--------------------------------------------------------------------------
@@ -481,7 +514,7 @@ void H5Location::setComment(const char* comment) const
 {
     herr_t ret_value = H5Oset_comment_by_name(getId(), ".", comment, H5P_DEFAULT);
     if(ret_value < 0)
-        throw LocationException(inMemFunc("setComment"), "H5Oset_comment_by_name failed");
+        throw ObjHeaderIException(inMemFunc("setComment"), "H5Oset_comment_by_name failed");
 }
 
 //--------------------------------------------------------------------------
@@ -511,7 +544,7 @@ void H5Location::removeComment(const char* name) const
 {
     herr_t ret_value = H5Oset_comment_by_name(getId(), name, NULL, H5P_DEFAULT);
     if(ret_value < 0)
-        throw LocationException(inMemFunc("removeComment"), "H5Oset_comment_by_name failed");
+        throw ObjHeaderIException(inMemFunc("removeComment"), "H5Oset_comment_by_name failed");
 }
 
 //--------------------------------------------------------------------------
@@ -551,7 +584,7 @@ ssize_t H5Location::getComment(const char* name, size_t buf_size, char* comment)
     // If H5Oget_comment_by_name returns a negative value, raise an exception
     if (comment_len < 0)
     {
-        throw LocationException("H5Location::getComment", "H5Oget_comment_by_name failed");
+        throw ObjHeaderIException(inMemFunc("getComment"), "H5Oget_comment_by_name failed");
     }
     // If the comment is longer than the provided buffer size, the C library
     // will not null terminate it
@@ -584,7 +617,7 @@ H5std_string H5Location::getComment(const char* name, size_t buf_size) const
     // If H5Oget_comment_by_name returns a negative value, raise an exception
     if (comment_len < 0)
     {
-        throw LocationException("H5Location::getComment", "H5Oget_comment_by_name failed");
+        throw ObjHeaderIException(inMemFunc("getComment"), "H5Oget_comment_by_name failed");
     }
 
     // If comment exists, calls C routine again to get it
@@ -605,7 +638,7 @@ H5std_string H5Location::getComment(const char* name, size_t buf_size) const
         if (temp_len < 0)
         {
             delete []comment_C;
-            throw LocationException("H5Location::getComment", "H5Oget_comment_by_name failed");
+            throw ObjHeaderIException(inMemFunc("getComment"), "H5Oget_comment_by_name failed");
         }
 
         // Convert the C comment to return
@@ -630,6 +663,61 @@ H5std_string H5Location::getComment(const H5std_string& name, size_t buf_size) c
 {
     return(getComment(name.c_str(), buf_size));
 }
+
+//--------------------------------------------------------------------------
+// Function:    H5Location::openObjId
+///\brief       Opens an object without knowing the object type.
+///\param       obj_name - IN: Path to the object
+///\param       lapl     - IN: Access property list for the link pointing
+///                            to the object
+///\exception   H5::ObjHeaderIException
+///\par Description
+///             This function opens an object at this location, using
+///             H5Oopen.  Thus, an object can be opened without knowing
+///             the object's type.
+// Programmer   Binh-Minh Ribler - May, 2017
+//--------------------------------------------------------------------------
+hid_t H5Location::openObjId(const char* obj_name, const LinkAccPropList& lapl) const
+{
+    hid_t ret_value = H5Oopen(getId(), obj_name, lapl.getId());
+    if (ret_value < 0)
+    {
+        throw ObjHeaderIException(inMemFunc("openObjId"), "H5Oopen failed");
+    }
+    return(ret_value);
+}
+
+//--------------------------------------------------------------------------
+// Function:    H5Location::openObjId
+///\brief       This is an overloaded member function, provided for convenience.
+///             It takes a reference to a \c H5std_string for the object's path.
+///\param       obj_name - IN: Path to the object
+///\param       lapl     - IN: Access property list for the link pointing to
+///                            the object
+///\exception   H5::ObjHeaderIException
+// Programmer   Binh-Minh Ribler - May, 2017
+//--------------------------------------------------------------------------
+hid_t H5Location::openObjId(const H5std_string& obj_name, const LinkAccPropList& lapl) const
+{
+    return(openObjId(obj_name.c_str(), lapl));
+}
+
+//--------------------------------------------------------------------------
+// Function:    H5Location::closeObjId
+///\brief       Closes an object, which was opened with H5Location::openObjId
+///
+///\exception   H5::ObjHeaderIException
+// Programmer   Binh-Minh Ribler - May, 2017
+//--------------------------------------------------------------------------
+void H5Location::closeObjId(hid_t obj_id) const
+{
+    herr_t ret_value = H5Oclose(obj_id);
+    if (ret_value < 0)
+    {
+        throw ObjHeaderIException(inMemFunc("closeObjId"), "H5Oclose failed");
+    }
+}
+
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 
 //--------------------------------------------------------------------------
@@ -958,7 +1046,6 @@ DataSpace H5Location::getRegion(void *ref, H5R_type_t ref_type) const
     }
 }
 
-
 //--------------------------------------------------------------------------
 // Function:    H5Location destructor
 ///\brief       Noop destructor.
diff --git a/c++/src/H5Location.h b/c++/src/H5Location.h
index 11f8f87..d202328 100644
--- a/c++/src/H5Location.h
+++ b/c++/src/H5Location.h
@@ -95,6 +95,9 @@ class H5_DLLCPP H5Location : public IdComponent {
         virtual void removeAttr(const char* name) const;
         virtual void removeAttr(const H5std_string& name) const;
 
+        // 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;
@@ -129,6 +132,13 @@ class H5_DLLCPP H5Location : public IdComponent {
         // 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().
+        void closeObjId(hid_t obj_id) const;
+
         ///\brief Returns an identifier. (pure virtual)
         virtual hid_t getId() const = 0;