H5FDstream.h

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * 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 files COPYING and Copyright.html.  COPYING can be found at the root   *
 * of the source code distribution tree; Copyright.html can be found at the  *
 * root level of an installed copy of the electronic HDF5 document set and   *
 * is linked from the top-level documents page.  It can also be found at     *
 * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
 * access to either file, you may request a copy from help@hdfgroup.org.     *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * Copyright © 2000 The author.
 * The author prefers this code not be used for military purposes.
 *
 *
 * Author:  Thomas Radke <tradke@aei-potsdam.mpg.de>
 *          Tuesday, September 12, 2000
 *
 * Purpose:     The public header file for the Stream Virtual File Driver.
 *
 * Modifications:
 *          Thomas Radke, Thursday, October 26, 2000
 *          Added support for Windows.
 *
 */
#ifndef H5FDstream_H
#define H5FDstream_H

#include <hdf5.h>
#include "hdf5stream_config.h"

#include "H5FDstreamDllApi.h"

#ifdef H5_HAVE_STREAM
#   define H5FD_STREAM  (H5FD_stream_init())
#else
#   define H5FD_STREAM (-1)
#endif /*H5_HAVE_STREAM */

#ifdef H5_HAVE_STREAM
/* check what sockets type we have (Unix or Windows sockets)
   Note that only MS compilers require to use Windows sockets
   but gcc under Windows does not. */
#if ! defined(H5_HAVE_WINSOCK_H) || defined(__GNUC__)
#define H5FD_STREAM_HAVE_UNIX_SOCKETS  1
#endif

/* define the data type for socket descriptors
   and the constant indicating an invalid descriptor */
#ifdef H5FD_STREAM_HAVE_UNIX_SOCKETS
#define H5FD_STREAM_SOCKET_TYPE            int
#define H5FD_STREAM_INVALID_SOCKET         -1

#else
#include <winsock.h>

#define H5FD_STREAM_SOCKET_TYPE            SOCKET
#define H5FD_STREAM_INVALID_SOCKET         INVALID_SOCKET

#endif


#ifdef __cplusplus
extern "C" {
#endif

/* prototype for read broadcast callback routine */
typedef int (*H5FD_stream_broadcast_t) (unsigned char **file,
                                        haddr_t *len,
                                        void *arg);

/*
  Prototype of a function that is called by the streaming file driver when
  it cannot send all data at once. This function might display a progress bar
  or perform some small computations until the data have left the local machine
  via the network connection.
 */
typedef int (*H5FDsendloop_callback_t)(size_t sent, size_t total, void*arg);

/*
  Prototype of a function that may modify the userblock of an HDF5 file.
  This functionality may be used to transport any additional information on
  an hdf5 file, e.g. to specify its content-type and file size in an application-defined
  manner. Still, any user client code that can read an HDF5 file via streams is able
  to read the streamed file independent from this userblock information.
  Nevertheless it may contain additional, hdf5-independent application-specific informaion.
  Note that the userblock must first be set by an appropriate HDF5 call, and this
  function MUST know about the size that has been set there. It cannot find out
  (at least I don't know how - WB) how large the userblock actually is, so consistency
  must be ensured by user code.
 */
typedef void (*H5FDmodify_userblock_callback_t)(void*ptr, size_t filesize, void*arg, H5FD_STREAM_SOCKET_TYPE socket);
        
#define H5FD_STREAMVFD_VERSION  2
        
/* driver-specific file access properties */
typedef struct H5FD_stream_fapl_t
{
  size_t       increment;            /* how much to grow memory in reallocs  */
  H5FD_STREAM_SOCKET_TYPE socket;    /* externally provided socket descriptor*/
  hbool_t      do_socket_io;         /* do I/O on socket                     */
  hbool_t      have_master_socket;   /* on write, a master socket is provided, not a client socket */   
  int          backlog;              /* backlog argument for listen call     */
  H5FD_stream_broadcast_t broadcast_fn; /* READ broadcast callback           */
  void        *broadcast_arg;        /* READ broadcast callback user argument*/
  unsigned int maxhunt;              /* how many more ports to try to bind to*/
  unsigned short int port;           /* port a socket was bound/connected to */
  H5FDsendloop_callback_t sendloop_callback_fn;
                                     /* Idle function to be called when data are written to a client.
                                        It may issue some other task, or at least call sleep(0) to
                                        enable task switching in a multitasking environment.
                                        May be NULL. */
  void        *sendloop_arg;         /* sendloop callback user argument */
  H5FDmodify_userblock_callback_t modify_userblock_callback_fn;
                                    /* callback function that may modify the userblock. May be NULL. */
  void *modify_userblock_args;       /* any user parameters for the modify userblock callback function */
} H5FD_stream_fapl_t;


/* prototypes of exported functions */
H5FDstream_API hid_t  H5FD_stream_init (void);
/* Sets reasonable default values for an streaming FAPL.
   It is recommended to use this function on empty H5FD_stream_fapl_t objects
   before any user values are set, because it initializes any members to
   values that ensure the default behaviour and is thus future-save in
   case of any future additions to the fapl structure. */
H5FDstream_API void   H5Pinit_fapl_stream (H5FD_stream_fapl_t *fapl);

H5FDstream_API herr_t H5Pset_fapl_stream (hid_t fapl_id,
                                   H5FD_stream_fapl_t *fapl);
        
H5FDstream_API herr_t H5Pget_fapl_stream (hid_t fapl_id,
                                   H5FD_stream_fapl_t *fapl /*out*/ );

#ifdef __cplusplus
}
#endif

#endif /* H5_HAVE_STREAM */

#endif /* H5FDstream_H */