HDFFV-10149 continued

Description:
    - Moved the new wrappers committed on Mar 9:
        43158f3bb3
      to H5Location and renamed some of them for overloading.
      This is because the loc_id in the C APIs can be file, group, dataset,
      named datatype, and attribute.  Previous implementation was wrong
      following some inaccurate C API reference manual.

    - Only the following wrappers are modified or added:
      + H5Lcreate_soft: changed name from newLink to link
        // Creates a soft link from link_name to target_name.
        void link(const char *target_name, const char *link_name,...)
        void link(const H5std_string& target_name,...)

      + H5Lcreate_hard: changed name from newLink to link
        // Creates a hard link from new_name to curr_name.
        void link(const char *curr_name, const Group& new_loc,...)
        void link(const H5std_string& curr_name, const Group& new_loc,...)

        // Creates a hard link from new_name to curr_name in same location.
        void link(const char *curr_name, const hid_t same_loc,...)
        void link(const H5std_string& curr_name, const hid_t same_loc,...)

      + H5Ldelete: modified existing functions to add 2nd argument
        // Removes the specified link from this location.
        void unlink(const char *link_name,
            const LinkAccPropList& lapl = LinkAccPropList::DEFAULT)
        void unlink(const H5std_string& link_name,
            const LinkAccPropList& lapl = LinkAccPropList::DEFAULT)

    - copyLink and moveLink were only moved from Group to H5Location, no change

    - Added class LinkCreatPropList

    - Added overloaded functions H5Location::createGroup to take a link creation
      property list
        Group createGroup(const char* name, const LinkCreatPropList& lcpl)
        Group createGroup(const H5std_string& name, const LinkCreatPropList& lcpl)
    - Added wrapper for H5Lget_info() to H5Location
        H5L_info_t getLinkInfo(const H5std_string& link_name,...)

Platforms tested:
    Linux/64 (jelly)
    Linux/ppc64 (ostrich)
    Darwin (osx1010test)

c++/src/H5LcreatProp.cpp

@@ -0,0 +1,146 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * 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://support.hdfgroup.org/ftp/HDF5/releases.  *
+ * If you do not have access to either file, you may request a copy from     *
+ * help@hdfgroup.org.                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+#include <string>
+
+#include "H5Include.h"
+#include "H5Exception.h"
+#include "H5IdComponent.h"
+#include "H5PropList.h"
+#include "H5LcreatProp.h"
+
+namespace H5 {
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+// This DOXYGEN_SHOULD_SKIP_THIS block is a work-around approach to control
+// the order of creation and deletion of the global constants.  See Design Notes
+// in "H5PredType.cpp" for information.
+
+// Initialize a pointer for the constant
+LinkCreatPropList* LinkCreatPropList::DEFAULT_ = 0;
+
+//--------------------------------------------------------------------------
+// Function:    LinkCreatPropList::getConstant
+//              Creates a LinkCreatPropList object representing the HDF5 constant
+//              H5P_LINK_CREATE, pointed to by LinkCreatPropList::DEFAULT_
+// exception    H5::PropListIException
+// Description
+//              If LinkCreatPropList::DEFAULT_ already points to an allocated
+//              object, throw a PropListIException.  This scenario should not
+//              happen.
+// December, 2016
+//--------------------------------------------------------------------------
+LinkCreatPropList* LinkCreatPropList::getConstant()
+{
+    // Tell the C library not to clean up, H5Library::termH5cpp will call
+    // H5close - more dependency if use H5Library::dontAtExit()
+    if (!IdComponent::H5dontAtexit_called)
+     {
+        (void) H5dont_atexit();
+        IdComponent::H5dontAtexit_called = true;
+    }
+
+    // If the constant pointer is not allocated, allocate it. Otherwise,
+    // throw because it shouldn't be.
+    if (DEFAULT_ == 0)
+        DEFAULT_ = new LinkCreatPropList(H5P_LINK_CREATE);
+    else
+        throw PropListIException("LinkCreatPropList::getConstant", "LinkCreatPropList::getConstant is being invoked on an allocated DEFAULT_");
+    return(DEFAULT_);
+}
+
+//--------------------------------------------------------------------------
+// Function:    LinkCreatPropList::deleteConstants
+// Purpose:     Deletes the constant object that LinkCreatPropList::DEFAULT_
+//              points to.
+// exception    H5::PropListIException
+// December, 2016
+//--------------------------------------------------------------------------
+void LinkCreatPropList::deleteConstants()
+{
+    if (DEFAULT_ != 0)
+        delete DEFAULT_;
+}
+
+//--------------------------------------------------------------------------
+// Purpose:     Constant for default property
+//--------------------------------------------------------------------------
+const LinkCreatPropList& LinkCreatPropList::DEFAULT = *getConstant();
+
+#endif // DOXYGEN_SHOULD_SKIP_THIS
+
+//--------------------------------------------------------------------------
+// Function:    Default Constructor
+///\brief       Creates a file access property list
+// December, 2016
+//--------------------------------------------------------------------------
+LinkCreatPropList::LinkCreatPropList() : PropList(H5P_LINK_CREATE) {}
+
+//--------------------------------------------------------------------------
+// Function:    LinkCreatPropList copy constructor
+///\brief       Copy Constructor: makes a copy of the original
+///\param       original - IN: LinkCreatPropList instance to copy
+// December, 2016
+//--------------------------------------------------------------------------
+LinkCreatPropList::LinkCreatPropList(const LinkCreatPropList& original) : PropList(original) {}
+
+//--------------------------------------------------------------------------
+// Function:    LinkCreatPropList overloaded constructor
+///\brief       Creates a file access property list using the id of an
+///             existing one.
+// December, 2016
+//--------------------------------------------------------------------------
+LinkCreatPropList::LinkCreatPropList(const hid_t plist_id) : PropList(plist_id) {}
+
+//--------------------------------------------------------------------------
+// Function:    LinkCreatPropList::setCharEncoding
+///\brief       Sets the character encoding of the string.
+///\exception   H5::PropListIException
+// March, 2018
+//--------------------------------------------------------------------------
+void LinkCreatPropList::setCharEncoding(H5T_cset_t encoding) const
+{
+    herr_t ret_value = H5Pset_char_encoding(id, encoding);
+    // Throw exception if H5Pset_char_encoding returns failure
+    if (ret_value < 0)
+    {
+        throw PropListIException("setCharEncoding", "H5Pset_char_encoding failed");
+    }
+}
+
+//--------------------------------------------------------------------------
+// Function:    LinkCreatPropList::getCharEncoding
+///\brief       Gets the character encoding of the string.
+///\exception   H5::PropListIException
+// March, 2018
+//--------------------------------------------------------------------------
+H5T_cset_t LinkCreatPropList::getCharEncoding() const
+{
+    H5T_cset_t encoding;
+    herr_t ret_value = H5Pget_char_encoding(id, &encoding);
+    // Throw exception if H5Pget_char_encoding returns failure
+    if (ret_value < 0)
+    {
+        throw PropListIException("getCharEncoding", "H5Pget_char_encoding failed");
+    }
+    return(encoding);
+}
+
+//--------------------------------------------------------------------------
+// Function:    LinkCreatPropList destructor
+///\brief       Noop destructor
+// December, 2016
+//--------------------------------------------------------------------------
+LinkCreatPropList::~LinkCreatPropList() {}
+
+} // end namespace