module Bindings.HDF5.Raw.H5A where #include #include import Foreign.C.String import Foreign.C.Types import Foreign.Ptr import Foreign.Storable import Bindings.HDF5.Raw.H5 import Bindings.HDF5.Raw.H5I -- IDs import Bindings.HDF5.Raw.H5O -- Object Headers import Bindings.HDF5.Raw.H5T -- Datatypes import Foreign.Ptr.Conventions -- |Information struct for attribute (for 'h5a_get_info'/'h5a_get_info_by_idx') #starttype H5A_info_t -- |Indicate if creation order is valid #field corder_valid, -- |Creation order #field corder, -- |Character set of attribute name #field cset, -- |Size of raw data #field data_size, #stoptype -- | Typedef for 'h5a_iterate2' callbacks. -- -- @ -- typedef herr_t (*H5A_operator2_t)(hid_t location_id/*in*/, -- const char *attr_name/*in*/, const H5A_info_t *ainfo/*in*/, void *op_data/*in,out*/); -- @ type H5A_operator2_t a = FunPtr (HId_t -> CString -> In H5A_info_t -> InOut a -> IO HErr_t) -- * Public function prototypes -- |Creates an attribute on an object -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object (dataset or group) to be attached to -- -- [@ attr_name :: CString @] Name of attribute to locate and open -- -- [@ type_id :: HId_t @] ID of datatype for attribute -- -- [@ space_id :: HId_t @] ID of dataspace for attribute -- -- [@ acpl_id :: HId_t @] ID of creation property list (currently not used) -- -- [@ aapl_id :: HId_t @] Attribute access property list -- -- Returns non-negative on success / negative on failure -- -- This function creates an attribute which is attached to the object -- specified with 'loc_id'. The name specified with 'attr_name' for -- each attribute for an object must be unique for that object. The 'type_id' -- and 'space_id' are created with the H5T and H5S interfaces respectively. -- The 'aapl_id' property list is currently unused, but will be used in the -- future for optional attribute access properties. The attribute ID returned -- from this function must be released with 'h5a_close' or resource leaks will -- develop. -- -- > hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, -- > hid_t space_id, hid_t acpl_id, hid_t aapl_id); #ccall H5Acreate2, -> CString -> -> -> -> -> IO -- |Creates an attribute on an object -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object (dataset or group) to be attached to -- [@ obj_name :: CString @] Name of object relative to location -- [@ attr_name :: CString @] Name of attribute to locate and open -- [@ type_id :: HId_t @] ID of datatype for attribute -- [@ space_id :: HId_t @] ID of dataspace for attribute -- [@ acpl_id :: HId_t @] ID of creation property list (currently not used) -- [@ aapl_id :: HId_t @] Attribute access property list -- [@ lapl_id :: HId_t @] Link access property list -- -- Returns non-negative on success / negative on failure -- -- This function creates an attribute which is attached to the object -- specified with 'loc_id/obj_name'. The name specified with 'attr_name' for -- each attribute for an object must be unique for that object. The 'type_id' -- and 'space_id' are created with the H5T and H5S interfaces respectively. -- The 'aapl_id' property list is currently unused, but will be used in the -- future for optional attribute access properties. The attribute ID returned -- from this function must be released with h5a_close or resource leaks will -- develop. -- -- > hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, -- > hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id); #ccall H5Acreate_by_name, -> CString -> CString -> -> -> -> -> -> IO -- |Opens an attribute for an object by looking up the attribute name -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object that attribute is attached to -- -- [@ attr_name :: CString @] Name of attribute to locate and open -- -- [@ aapl_id :: HId_t @] Attribute access property list -- -- Returns ID of attribute on success, negative on failure -- -- This function opens an existing attribute for access. The attribute -- name specified is used to look up the corresponding attribute for the -- object. The attribute ID returned from this function must be released with -- 'h5a_close' or resource leaks will develop. -- -- > hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); #ccall H5Aopen, -> CString -> -> IO -- |Opens an attribute for an object by looking up the attribute name -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object that attribute is attached to -- -- [@ obj_name :: CString @] Name of object relative to location -- -- [@ attr_name :: CString @] Name of attribute to locate and open -- -- [@ aapl_id :: HId_t @] Attribute access property list -- -- [@ lapl_id :: HId_t @] Link access property list -- -- Returns ID of attribute on success, negative on failure -- -- This function opens an existing attribute for access. The attribute -- name specified is used to look up the corresponding attribute for the -- object. The attribute ID returned from this function must be released with -- 'h5a_close' or resource leaks will develop. -- -- > hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, -- > const char *attr_name, hid_t aapl_id, hid_t lapl_id); #ccall H5Aopen_by_name, -> CString -> CString -> -> -> IO -- hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, -- H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t aapl_id, -- hid_t lapl_id); #ccall H5Aopen_by_idx, -> CString -> -> -> -> -> -> IO -- TODO: Figure out how many elements elements 'buf' is expected to contain, and why -- |Write out data to an attribute -- -- Parameters: -- -- [@ attr_id :: HId_t @] Attribute to write -- -- [@ dtype_id :: HId_t @] Memory datatype of buffer -- -- [@ buf :: InArray a @] Buffer of data to write -- -- Returns non-negative on success / negative on failure -- -- This function writes a complete attribute to disk. -- -- > herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); #ccall H5Awrite, -> -> InArray a -> IO -- |Read in data from an attribute -- -- Parameters: -- -- [@ attr_id :: HId_t @] Attribute to read -- -- [@ dtype_id :: HId_t @] Memory datatype of buffer -- -- [@ buf :: OutArray a @] Buffer for data to read -- -- Returns non-negative on success / negative on failure -- -- This function reads a complete attribute from disk. -- -- > herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf); #ccall H5Aread, -> -> OutArray a -> IO -- |Close an attribute ID -- -- Parameters: -- -- [@ attr_id :: HId_t @] Attribute to release access to -- -- Returns non-negative on success / negative on failure -- -- This function releases an attribute from use. Further use of the -- attribute ID will result in undefined behavior. -- -- > herr_t H5Aclose(hid_t attr_id); #ccall H5Aclose, -> IO -- |Gets a copy of the dataspace for an attribute -- -- Parameters: -- -- [@ attr_id :: HId_t @] Attribute to get dataspace of -- -- Returns a dataspace ID on success, negative on failure -- -- This function retrieves a copy of the dataspace for an attribute. -- The dataspace ID returned from this function must be released with -- 'h5s_close' or resource leaks will develop. -- -- > hid_t H5Aget_space(hid_t attr_id); #ccall H5Aget_space, -> IO -- |Gets a copy of the datatype for an attribute -- -- Parameters: -- -- [@ attr_id :: HId_t @] Attribute to get datatype of -- -- Returns a datatype ID on success, negative on failure -- -- This function retrieves a copy of the datatype for an attribute. -- The datatype ID returned from this function must be released with -- 'h5t_close' or resource leaks will develop. -- -- > hid_t H5Aget_type(hid_t attr_id); #ccall H5Aget_type, -> IO -- |Gets a copy of the creation property list for an attribute -- -- Parameters: -- -- [@ attr_id :: HId_t @] Attribute to get name of -- -- This function returns the ID of a copy of the attribute's creation -- property list, or negative on failure. The resulting ID must be closed -- with 'h5p_close' or resource leaks will occur. -- -- > hid_t H5Aget_create_plist(hid_t attr_id); #ccall H5Aget_create_plist, -> IO -- TODO: check semantics of returned strings (null terminated and/or returns size?) -- |Gets a copy of the name for an attribute -- -- Parameters: -- -- [@ attr_id :: HId_t @] Attribute to get name of -- -- [@ buf_size :: CSize @] The size of the buffer to store the string in. -- -- [@ buf :: OutArray CChar @] Buffer to store name in -- -- This function returns the length of the attribute's name (which may be -- longer than 'buf_size') on success or negative for failure. -- -- This function retrieves the name of an attribute for an attribute ID. -- Up to 'buf_size' characters are stored in 'buf' followed by a '\0' string -- terminator. If the name of the attribute is longer than 'buf_size'-1, -- the string terminator is stored in the last position of the buffer to -- properly terminate the string. -- -- > ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); #ccall H5Aget_name, -> -> OutArray CChar -> IO -- |Retrieve name of an attribute, according to the order within an index. -- -- Same pattern of behavior as 'h5i_get_name' -- -- Returns non-negative length of name, with information in @name@ buffer -- on success / negative on failure -- -- > ssize_t H5Aget_name_by_idx(hid_t loc_id, const char *obj_name, -- > H5_index_t idx_type, H5_iter_order_t order, hsize_t n, -- > char *name /*out*/, size_t size, hid_t lapl_id); #ccall H5Aget_name_by_idx, -> CString -> -> -> -> OutArray CChar -> -> -> IO -- |Returns the amount of storage size that is allocated for this attribute. -- The return value may be zero if no data has been stored. -- -- > hsize_t H5Aget_storage_size(hid_t attr_id); #ccall H5Aget_storage_size, -> IO -- |Retrieve information about an attribute. -- -- Returns non-negative on success / negative on failure -- -- > herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); #ccall H5Aget_info, -> Out -> IO -- |Retrieve information about an attribute by name. -- -- Returns non-negative on success / negative on failure -- -- > herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, -- > const char *attr_name, H5A_info_t *ainfo /*out*/, hid_t lapl_id); #ccall H5Aget_info_by_name, -> CString -> CString -> Out H5A_info_t -> -> IO -- |Retrieve information about an attribute, according to the order within an index. -- -- Returns non-negative on success / negative on failure -- -- > herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, -- > H5_index_t idx_type, H5_iter_order_t order, hsize_t n, -- > H5A_info_t *ainfo /*out*/, hid_t lapl_id); #ccall H5Aget_info_by_idx, -> CString -> -> -> -> Out -> -> IO -- |Rename an attribute -- -- Returns non-negative on success / negative on failure -- -- > herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name); #ccall H5Arename, -> CString -> CString -> IO -- |Rename an attribute -- -- Returns non-negative on success / negative on failure -- -- > herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, -- > const char *old_attr_name, const char *new_attr_name, hid_t lapl_id); #ccall H5Arename_by_name, -> CString -> CString -> CString -> -> IO -- |Calls a user's function for each attribute on an object. -- -- Parameters: -- -- [@ loc_id :: HId_t @] Base location for object -- -- [@ idx_type :: H5_index_t @] Type of index to use -- -- [@ order :: H5_iter_order_t @] Order to iterate over index -- -- [@ idx :: InOut HSize_t @] Starting (IN) & Ending (OUT) attribute in index & order -- -- [@ op :: H5A_operator2_t a @] User's function to pass each attribute to -- -- [@ op_data :: InOut a @] User's data to pass through to iterator operator function -- -- Returns a negative value if an error occurs, the return value of the -- last operator if it was non-zero (which can be a negative value), or zero -- if all attributes were processed. -- -- This function interates over the attributes of dataset or group -- specified with 'loc_id' & 'obj_name'. For each attribute of the object, -- the 'op_data' and some additional information (specified below) are passed -- to the 'op' function. The iteration begins with the '*idx' -- object in the group and the next attribute to be processed by the operator -- is returned in '*idx'. -- -- The operation receives the ID for the group or dataset being iterated -- over ('loc_id'), the name of the current attribute about the object -- ('attr_name'), the attribute's \"info\" struct ('ainfo') and the pointer to -- the operator data passed in to H5Aiterate2 ('op_data'). The return values -- from an operator are: -- -- * Zero causes the iterator to continue, returning zero when all -- attributes have been processed. -- -- * Positive causes the iterator to immediately return that positive -- value, indicating short-circuit success. The iterator can be -- restarted at the next attribute. -- -- * Negative causes the iterator to immediately return that value, -- indicating failure. The iterator can be restarted at the next -- attribute. -- -- > herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, -- > H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data); #ccall H5Aiterate2, -> -> -> InOut -> H5A_operator2_t a -> InOut a -> IO -- |Calls a user's function for each attribute on an object -- -- Parameters: -- -- [@ loc_id :: HId_t @] Base location for object -- -- [@ obj_name :: CString @] Name of object relative to location -- -- [@ idx_type :: H5_index_t @] Type of index to use -- -- [@ order :: H5_iter_order_t @] Order to iterate over index -- -- [@ idx :: InOut HSize_t @] Starting (IN) & Ending (OUT) attribute in index & order -- -- [@ op :: H5A_operator2_t a @] H5A_operator2_t IN: User's function to pass each attribute to -- -- [@ op_data :: InOut a @] User's data to pass through to iterator operator function -- -- [@ lapl_id :: HId_t @] Link access property list -- -- Returns a negative value if an error occurs, the return value of the -- last operator if it was non-zero (which can be a negative value), or zero -- if all attributes were processed. -- -- This function interates over the attributes of dataset or group -- specified with 'loc_id' & 'obj_name'. For each attribute of the object, -- the 'op_data' and some additional information (specified below) are passed -- to the 'op' function. The iteration begins with the '*idx' -- object in the group and the next attribute to be processed by the operator -- is returned in '*idx'. -- -- The operation receives the ID for the group or dataset being iterated -- over ('loc_id'), the name of the current attribute about the object -- ('attr_name'), the attribute's \"info\" struct ('ainfo') and the pointer to -- the operator data passed in to H5Aiterate_by_name ('op_data'). The return values -- from an operator are: -- -- * Zero causes the iterator to continue, returning zero when all -- attributes have been processed. -- -- * Positive causes the iterator to immediately return that positive -- value, indicating short-circuit success. The iterator can be -- restarted at the next attribute. -- -- * Negative causes the iterator to immediately return that value, -- indicating failure. The iterator can be restarted at the next -- attribute. -- -- > herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, -- > H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data, -- > hid_t lapd_id); #ccall H5Aiterate_by_name, -> CString -> -> -> InOut -> H5A_operator2_t a -> InOut a -> -> IO -- |Deletes an attribute from a location -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object (dataset or group) to have attribute deleted from -- -- [@ name :: CString @] Name of attribute to delete -- -- Returns non-negative on success / negative on failure -- -- This function removes the named attribute from a dataset or group. -- -- > herr_t H5Adelete(hid_t loc_id, const char *name); #ccall H5Adelete, -> CString -> IO -- |Deletes an attribute from a location -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object (dataset or group) to have attribute deleted from -- -- [@ obj_name :: CString @] Name of object relative to location -- -- [@ attr_name :: CString @] Name of attribute to delete -- -- [@ lapl_id :: HId_t @] Link access property list -- -- Returns non-negative on success / negative on failure -- -- This function removes the named attribute from a dataset or group. -- -- > herr_t H5Adelete_by_name(hid_t loc_id, const char *obj_name, -- > const char *attr_name, hid_t lapl_id); #ccall H5Adelete_by_name, -> CString -> CString -> -> IO -- |Deletes an attribute from a location, according to the order within an index -- -- Parameters: -- -- [@ loc_id :: HId_t @] Base location for object -- -- [@ obj_name :: CString @] Name of object relative to location -- -- [@ idx_type :: H5_index_t @] Type of index to use -- -- [@ order :: H5_iter_order_t @] Order to iterate over index -- -- [@ n :: HSize_t @] Offset within index -- -- [@ lapl_id :: HId_t @] Link access property list -- -- Returns non-negative on success / negative on failure -- -- This function removes an attribute from an object, using the 'idx_type' -- index to delete the 'n'th attribute in 'order' direction in the index. The -- object is specified relative to the 'loc_id' with the 'obj_name' path. To -- remove an attribute on the object specified by 'loc_id', pass in @"."@ for -- 'obj_name'. The link access property list, 'lapl_id', controls aspects of -- the group hierarchy traversal when using the 'obj_name' to locate the final -- object to operate on. -- -- > herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, -- > H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id); #ccall H5Adelete_by_idx, -> CString -> -> -> -> -> IO -- |Checks if an attribute with a given name exists on an opened object. -- -- > htri_t H5Aexists(hid_t obj_id, const char *attr_name); #ccall H5Aexists, -> CString -> IO -- |Checks if an attribute with a given name exists on an object. -- -- > htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, -- > const char *attr_name, hid_t lapl_id); #ccall H5Aexists_by_name, -> CString -> CString -> -> IO #ifndef H5_NO_DEPRECATED_SYMBOLS -- |Typedef for 'h5a_iterate1' callbacks -- -- > typedef herr_t (*H5A_operator1_t)(hid_t location_id/*in*/, -- > const char *attr_name/*in*/, void *operator_data/*in,out*/); type H5A_operator1_t a = FunPtr (HId_t -> CString -> InOut a -> IO HErr_t) -- |Creates an attribute on an object -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object (dataset or group) to be attached to -- -- [@ name :: CString @] Name of attribute to create -- -- [@ type_id :: HId_t @] ID of datatype for attribute -- -- [@ space_id :: HId_t @] ID of dataspace for attribute -- -- [@ plist_id :: HId_t @] ID of creation property list (currently not used) -- -- Returns non-negative on success / negative on failure -- -- This function creates an attribute which is attached to the object -- specified with 'location_id'. The name specified with 'name' for each -- attribute for an object must be unique for that object. The 'type_id' -- and 'space_id' are created with the H5T and H5S interfaces respectively. -- The attribute ID returned from this function must be released with -- 'h5a_close' or resource leaks will develop. -- -- Note: Deprecated in favor of 'h5a_create2' -- -- > hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, -- > hid_t space_id, hid_t acpl_id); #ccall H5Acreate1, -> CString -> -> -> -> IO -- |Opens an attribute for an object by looking up the attribute name -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object (dataset or group) to be attached to -- -- [@ name :: CString @] Name of attribute to locate and open -- -- Returns ID of attribute on success, negative on failure -- -- This function opens an existing attribute for access. The attribute -- name specified is used to look up the corresponding attribute for the -- object. The attribute ID returned from this function must be released with -- H5Aclose or resource leaks will develop. -- -- The location object may be either a group or a dataset, both of -- which may have any sort of attribute. -- -- Note: Deprecated in favor of 'h5a_open' -- -- > hid_t H5Aopen_name(hid_t loc_id, const char *name); #ccall H5Aopen_name, -> CString -> IO -- |Opens the n'th attribute for an object -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object that attribute is attached to -- -- [@ idx :: CUInt @] Index (0-based) attribute to open -- -- Returns ID of attribute on success, negative on failure -- -- This function opens an existing attribute for access. The attribute -- index specified is used to look up the corresponding attribute for the -- object. The attribute ID returned from this function must be released with -- 'h5a_close' or resource leaks will develop. -- -- The location object may be either a group or a dataset, both of -- which may have any sort of attribute. -- -- Note: Deprecated in favor of 'h5a_open_by_idx' -- -- > hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); #ccall H5Aopen_idx, -> CUInt -> IO -- |Determines the number of attributes attached to an object -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object (dataset or group) to be queried -- -- Returns number of attributes on success, negative on failure -- -- This function returns the number of attributes attached to a dataset or -- group, 'location_id'. -- -- Note: Deprecated in favor of 'h5o_get_info' -- -- > int H5Aget_num_attrs(hid_t loc_id); #ccall H5Aget_num_attrs, -> IO CInt -- |Calls a user's function for each attribute on an object -- -- Parameters: -- -- [@ loc_id :: HId_t @] Object (dataset or group) to be iterated over -- -- [@ attr_num :: InOut CUInt @] Starting (IN) & Ending (OUT) attribute number -- -- [@ op :: H5A_operator1_t a @] User's function to pass each attribute to -- -- [@ op_data :: InOut a @] User's data to pass through to iterator operator function -- -- Returns a negative value if something is wrong, the return value of the -- last operator if it was non-zero, or zero if all attributes were processed. -- -- This function interates over the attributes of dataset or group -- specified with 'loc_id'. For each attribute of the object, the -- 'op_data' and some additional information (specified below) are passed -- to the 'op' function. The iteration begins with the 'attr_num' -- object in the group and the next attribute to be processed by the operator -- is returned in 'attr_num'. -- -- The operation receives the ID for the group or dataset being iterated -- over ('loc_id'), the name of the current attribute about the object -- ('attr_name') and the pointer to the operator data passed in to 'h5a_iterate1' -- ('op_data'). The return values from an operator are: -- -- * Zero causes the iterator to continue, returning zero when all -- attributes have been processed. -- -- * Positive causes the iterator to immediately return that positive -- value, indicating short-circuit success. The iterator can be -- restarted at the next attribute. -- -- * Negative causes the iterator to immediately return that value, -- indicating failure. The iterator can be restarted at the next -- attribute. -- -- Note: Deprecated in favor of 'h5a_iterate2' -- -- > herr_t H5Aiterate1(hid_t loc_id, unsigned *attr_num, H5A_operator1_t op, -- > void *op_data); #ccall H5Aiterate1, -> InOut CUInt -> H5A_operator1_t a -> InOut a -> IO #endif /* H5_NO_DEPRECATED_SYMBOLS */