H5L_REGISTER registers a class of user-defined links, or changes the behavior of an existing class.

link_class is a pointer to a buffer containing a copy of the H5L_class_t struct. This struct is defined in H5Lpublic.h as follows:

  typedef struct H5L_class_t {
      int version;                    /* Version number of this struct  */
      H5L_type_t class_id;            /* Link class identifier          */
      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_traverse_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_class_t;      

The class definition passed with link_class must include at least the following:

• An H5L_class_t version (which should be H5L_LINK_CLASS_T_VERS)
• A link class identifier, class_id
• A traversal function, trav_func

Remaining struct members are optional and may be passed as NULL.

The link class passed in class_id must be in the user-definable range between H5L_TYPE_UD_MIN and H5L_TYPE_UD_MAX (see the “Link Class Identifiers...” table below) and will override any existing link class with that identifier.

As distributed, valid values of class_id used in HDF5 include the following (defined in H5Lpublic.h):

The hard and soft link class identifiers cannot be modified or reassigned, but the external link class is implemented as an example in the user-definable link class identifier range. H5L_REGISTER is used to register additional link classes. It could also be used to modify the behavior of the external link class, though that is not recommended.

The following table summarizes existing link types and values and the reserved and user-definable link class identifier value ranges.

Link Class Identifiers or Value Ranges, Descriptions, and Class Names

Note that HDF5 internally registers user-defined link classes only by the numeric value of the link class identifier. An application, on the other hand, will generally use a name for a user-defined class, if for no other purpose than as a variable name. Assume, for example, that a complex link type is registered with the link class identifier 73 and that the code includes the following assignment: 

     H5L_TYPE_COMPLEX_A = 73 
The application can refer to the link class with a term, H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing the code, while HDF5 recognizes it by the more cryptic numeric identifier, 73.

Returns a non-negative value if successful; otherwise returns a negative value.

Coming Soon!