F5X.h

Go to the documentation of this file.

/*
 $Id: F5X.h,v 1.26 2008/02/22 23:51:25 werner Exp $
*/
 
#ifndef __F5_F5X_H
#define __F5_F5X_H      "Extensions to the HDF5 API"
 
#include "hdf5inc.h"
 
#include "F5WinDLLApi.h"
 
#ifdef  __cplusplus
extern "C"
{
#endif
 
/** \defgroup extensions Useful extension of the HDF5 API.
        These extensions are of general use, not only in conjunction
        with the fiber bundle concept,
        but they just happen to sit here in this library.
  */
/** @{ */
 
/** Open some URL for reading data (read-only).
    Note that this function may well invoke the streaming HDF5
    driver when a valid socket descriptor is given.
    Such might well be created by a call to F5connect().
    Note that the socket needs to be closed explicitely.
 */
F5_API hid_t F5open(const char *filename, int socket );
 
/**
   Open a socket connection to the specified host and port.
   The URL must be of the form:
    @code
        HDF5://myhost.com:6666/T=0.000000/
    @endcode
 */
F5_API  int F5connect(const char*url);
 
F5_API  int F5listen(const char *service);
 
/**
   A forwarding call to the platformspecific
   system call to close a socket.
 */
F5_API  void F5closesocket(int socket);
 
/** Calling windows socket init on windows */
F5_API  void F5socket_init();
 
/** Calling windows socket cleanup on windows */
F5_API  void F5socket_cleanup();
 
/**
   Create a group using utf8 encoding for the link name
   and making use of the estimated group entry and name
   length properties for optimization.
   If these values are negative, no such hints will be set.
 */
F5_API hid_t F5Gcreate(hid_t loc_id, const char *name,
                       int est_num_entries, int est_name_len );
 
 
/** Open some file for appending data. */
F5_API hid_t F5append(const char *filename );
 
/** Open some group if it exists, otherwise create one. */
F5_API hid_t F5Gappend(hid_t loc_id, const char *name);
 
/** Open or create a group, if created then with estimated hints
    about its number of entries and estimated length of its member names.
*/
F5_API hid_t F5Gappend_hinted_creation(hid_t loc_id, const char *name,
                                       int est_num_entries, int est_name_len );
        
F5_API hid_t F5Gappend_external(hid_t loc_id, const char *name,
                               const char *target_file_name,
                               const char *target_obj_name,
                               const char *prefix );
 
        
/** Open some dataset if it exists, otherwise create one. */
F5_API hid_t F5Dappend(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t create_plist_id );
 
/** Create a new dataset, possibly deleting an old one if such exists. */
F5_API hid_t F5Dcreate(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t create_plist_id );
 
/** Open a group */
F5_API int F5Gopen(hid_t location, const char*name);
 
/** Check if a group exists. */
F5_API int F5Gexist(hid_t location, const char*name);
 
/** Try to open an HDF5 group, silently return -1 if it does not exist. */
F5_API hid_t F5Gtry_to_open(hid_t location, const char*name);
 
/** Check if a dataset exists. */
F5_API int F5Dexist(hid_t location, const char*name);
 
F5_API hid_t F5Dtry_to_open(hid_t location, const char*name);
 
/** Close an object regardless of its type.
 
        Use this function to close any HDF5-Object,
        if you do not know the type of the object.
        This is especially usefull after a call to H5Rdereference().
 
        @remark Normally you shouldn't use this function,
                because you should know the objects you are creating.
 
    @remark The function doesn't work for properties, supported are
                only the following types:
            - H5I_FILE
            - H5I_GROUP
            - H5I_DATATYPE
            - H5I_DATASPACE
            - H5I_DATASET
            - H5I_ATTR
 
        @param ret_type_id
                A pointer to a storage to take the type of the given object.
                See H5Iget_type() for a list of types.
 
        @param obj_id
                The ID of the object to be closed.
 
        @return Error Code of the closing function.
                (A non-negative value if successful; otherwise a negative value.)
 
        @todo Better Error Value than "-1".
 
        @note Could/should rename this to F5Dclose(), to denote it as
              a function to close F5 dataset ID's, which can be HDF5
              groups or datasets.
 */
F5_API herr_t F5Xclose(hid_t obj_id /*, H5I_type_t *pret_type_id*/);
 
/**
   Call H5Cclose with a debug message when F5_VERBOSITY is larger then 110
 */
F5_API  herr_t _F5Gclose(hid_t id, const char*filename, int lineno);
 
#define H5Gclose(x)     _F5Gclose(x, __FILE__, __LINE__)
 
/** @} */
 
#ifdef  __cplusplus
}    /* extern "C" */
#endif
 
#endif  /* __F5_F5X_H */