[svn-r12528] Added User-Defined links to the library.

Users can create external links using H5L_create_external().  These links
point to an object in another HDF5 file.  Users can alter the behavior of
external links or create new kinds of links by registering callbacks
using the H5L interface.

Added tests, tools support, etc.

Also a number of other, minor changes have been made (some restructuring of
the H5L interface, for instance).

Additional documentation and examples are forthcoming.

1 files changed, 88 insertions, 20 deletions

diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index a922908..29dc840 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -34,42 +34,110 @@
 extern "C" {
 #endif
 
-/* Types of links */
-typedef enum H5L_link_t {
-    H5L_LINK_ERROR	= -1,
-    H5L_LINK_HARD	= 0,
-    H5L_LINK_SOFT	= 1
-} H5L_link_t;
+/* Link classes.
+ * Values less than 64 are reserved for the HDF5 library's internal use.
+ * Values 64 to 255 are for "user-defined" link types; these types are
+ * defined by HDF5 but their behavior can be overridden by users.
+ * Users who want to create new classes of links should contact the HDF5
+ * development team at hdfhelp@ncsa.uiuc.edu .
+ * These values can never change because they appear in HDF5 files. 
+ */
+typedef int H5L_link_t;
+#define H5L_LINK_ERROR    (-1)
+#define H5L_LINK_HARD     0
+#define H5L_LINK_SOFT     1
+#define H5L_LINK_BUILTIN_MAX H5L_LINK_SOFT  /* Maximum value link value for "built-in" link types */
+#define H5L_LINK_UD_MIN   64     /*link ids at or above this value are "user-defined" link types. */
+#define H5L_LINK_EXTERNAL 64
+#define H5L_LINK_MAX      255	 /*maximum link id                        */
 
 /* Metadata buffer for user query function */
 typedef struct H5L_linkinfo_t {
-    H5T_cset_t          cset;           /* Character set of link name   */
-    time_t              ctime;          /* Creation time                */
-    H5L_link_t          linkclass;      /* Type of link                 */
+    H5T_cset_t          cset;           /* Character set of link name     */
+    time_t              ctime;          /* Creation time                  */
+    H5L_link_t          linkclass;      /* Type of link                   */
     union {
-        haddr_t         objno;          /* Data stored in a hard link   */
-        size_t          link_size;      /* Size of a soft link          */
+        haddr_t         address;        /* Address hard link points to    */
+        size_t          link_size;      /* Size of a soft link or UD link */
     } u;
 } H5L_linkinfo_t;
 
 #define H5L_SAME_LOC 0
 
+/* The H5L_link_class_t struct can be used to override the behavior of a
+ * "user-defined" link class. Users should populate the struct with callback
+ * functions defined below.
+ */
+/* Current version of the H5L_link_class_t struct */
+#define H5L_LINK_CLASS_T_VERS (0)
+
+/* Callback prototypes for user-defined links */
+/* Link creation callback */
+typedef herr_t (*H5L_create_func_t)(const char * link_name, hid_t loc_group, void * udata, size_t udata_size, hid_t lcpl_id);
+
+/* Callback for when the link is moved */
+typedef herr_t (*H5L_move_func_t)(const char * new_name, hid_t new_loc, void * udata, size_t udata_size);
+
+/* Callback for when the link is moved */
+typedef herr_t (*H5L_copy_func_t)(const char * new_name, hid_t new_loc, void * udata, size_t udata_size);
+
+/* The actual link function, called during traversal */
+typedef herr_t (*H5L_func_t)(const char * link_name, hid_t cur_group, void * udata, size_t udata_size, hid_t lapl_id);
+
+/* Callback for when the link is deleted */
+typedef herr_t (*H5L_delete_func_t)(const char * link_name, hid_t loc_group, void * udata, size_t udata_size);
+
+/* Callback for querying the link */
+/* Returns the size of the buffer needed */
+typedef ssize_t (*H5L_query_func_t)(const char * link_name, void * udata, size_t udata_size, void * buf /*out*/, size_t buf_size);
+
+/* User-defined link types */
+typedef struct H5L_link_class_t {
+    int version;                    /* Version number of this struct        */
+    H5L_link_t id;                  /* Link type ID                         */
+    const char *comment;            /* Comment for debugging                */
+    H5L_create_func_t create_func;  /* Callback during link creation        */
+    H5L_move_func_t move_func;      /* Callback after moving link           */
+    H5L_copy_func_t copy_func;      /* Callback after copying link          */
+    H5L_func_t trav_func;           /* The main traversal function          */
+    H5L_delete_func_t del_func;     /* Callback for link deletion           */
+    H5L_query_func_t query_func;    /* Callback for queries                 */
+} H5L_link_class_t;
+
+#define H5L_ELINK_PREFIX_PROP "elink_prefix"
+
+
+/* Public prototypes */
 H5_DLL herr_t H5Llink(hid_t cur_loc_id, const char *cur_name,
-                        hid_t obj_id, hid_t lcpl_id);
+                        hid_t obj_id, hid_t lcpl_id, hid_t lapl_id);
 H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc,
-                        const char *dst_name, hid_t lcpl_id);
+                        const char *dst_name, hid_t lcpl_id, hid_t lapl_id);
 H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc,
-                        const char *dst_name, hid_t lcpl_id);
+                        const char *dst_name, hid_t lcpl_id, hid_t lapl_id);
 H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name,
-		        hid_t dst_loc, const char *dst_name, hid_t lcpl_id);
-H5_DLL herr_t H5Lcreate_soft(const char *target_path, hid_t loc,
-                             const char *name, hid_t lcpl_id);
-H5_DLL herr_t H5Lunlink(hid_t loc_id, const char *name);
+		        hid_t dst_loc, const char *dst_name, hid_t lcpl_id,
+                        hid_t lapl_id);
+H5_DLL herr_t H5Lcreate_soft(const char *target_path, hid_t cur_loc,
+                             const char *cur_name, hid_t lcpl_id, hid_t lapl_id);
+H5_DLL herr_t H5Lunlink(hid_t loc_id, const char *name, hid_t lapl_id);
 H5_DLL herr_t H5Lget_linkval(hid_t loc_id, const char *name, size_t size,
-			      char *buf/*out*/);
+			      char *buf/*out*/, hid_t lapl_id);
 H5_DLL herr_t H5Lget_linkinfo(hid_t loc_id, const char *name,
-                              H5L_linkinfo_t *linkbuf /*out*/);
+                              H5L_linkinfo_t *linkbuf /*out*/, hid_t lapl_id);
+
+/* UD link functions */
+H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name,
+        H5L_link_t link_type, void * udata, size_t udata_size, hid_t lcpl_id,
+        hid_t lapl_id);
+H5_DLL herr_t H5Lregister(const H5L_link_class_t *cls);
+H5_DLL herr_t H5Lunregister(H5L_link_t id);
+H5_DLL htri_t H5Lis_registered(H5L_link_t id);
 
+/* External link functions */
+H5_DLL herr_t H5Lunpack_elink_val(char * ext_linkval/*in*/,
+            char ** filename/*out*/, char** obj_path /*out*/);
+H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name,
+        hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id);
 
 #ifdef __cplusplus
 }