c_cpp/lib/htslib/hfile_internal.h

   1 /*  hfile_internal.h -- internal parts of low-level input/output streams.
   2
   3     Copyright (C) 2013-2016 Genome Research Ltd.
   4
   5     Author: John Marshall <jm18@sanger.ac.uk>
   6
   7 Permission is hereby granted, free of charge, to any person obtaining a copy
   8 of this software and associated documentation files (the "Software"), to deal
   9 in the Software without restriction, including without limitation the rights
  10 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11 copies of the Software, and to permit persons to whom the Software is
  12 furnished to do so, subject to the following conditions:
  13
  14 The above copyright notice and this permission notice shall be included in
  15 all copies or substantial portions of the Software.
  16
  17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  23 DEALINGS IN THE SOFTWARE.  */
  24
  25 #ifndef HFILE_INTERNAL_H
  26 #define HFILE_INTERNAL_H
  27
  28 #include <stdarg.h>
  29
  30 #include "htslib/hfile.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*!
  37   @abstract  Resizes the buffer within an hFILE.
  38
  39   @notes  Changes the buffer size for an hFILE.  Ideally this is done
  40   immediately after opening.  If performed later, this function may
  41   fail if we are reducing the buffer size and the current offset into
  42   the buffer is beyond the new capacity.
  43
  44   @param fp        The file stream
  45   @param bufsiz    The size of the new bufsiz
  46
  47   @return Returns 0 on success, -1 on failure.
  48  */
  49 int hfile_set_blksize(hFILE *fp, size_t capacity);
  50
  51 struct BGZF;
  52 /*!
  53   @abstract Return the hFILE connected to a BGZF
  54  */
  55 struct hFILE *bgzf_hfile(struct BGZF *fp);
  56
  57 struct hFILE_backend {
  58     /* As per read(2), returning the number of bytes read (possibly 0) or
  59        negative (and setting errno) on errors.  Front-end code will call this
  60        repeatedly if necessary to attempt to get the desired byte count.  */
  61     ssize_t (*read)(hFILE *fp, void *buffer, size_t nbytes) HTS_RESULT_USED;
  62
  63     /* As per write(2), returning the number of bytes written or negative (and
  64        setting errno) on errors.  Front-end code will call this repeatedly if
  65        necessary until the desired block is written or an error occurs.  */
  66     ssize_t (*write)(hFILE *fp, const void *buffer, size_t nbytes)
  67         HTS_RESULT_USED;
  68
  69     /* As per lseek(2), returning the resulting offset within the stream or
  70        negative (and setting errno) on errors.  */
  71     off_t (*seek)(hFILE *fp, off_t offset, int whence) HTS_RESULT_USED;
  72
  73     /* Performs low-level flushing, if any, e.g., fsync(2); for writing streams
  74        only.  Returns 0 for success or negative (and sets errno) on errors. */
  75     int (*flush)(hFILE *fp) HTS_RESULT_USED;
  76
  77     /* Closes the underlying stream (for output streams, the buffer will
  78        already have been flushed), returning 0 for success or negative (and
  79        setting errno) on errors, as per close(2).  */
  80     int (*close)(hFILE *fp) HTS_RESULT_USED;
  81 };
  82
  83 /* May be called by hopen_*() functions to decode a fopen()-style mode into
  84    open(2)-style flags.  */
  85 int hfile_oflags(const char *mode);
  86
  87 /* Must be called by hopen_*() functions to allocate the hFILE struct and set
  88    up its base.  Capacity is a suggested buffer size (e.g., via fstat(2))
  89    or 0 for a default-sized buffer.  */
  90 hFILE *hfile_init(size_t struct_size, const char *mode, size_t capacity);
  91
  92 /* Alternative to hfile_init() for in-memory backends for which the base
  93    buffer is the only storage.  Buffer is already allocated via malloc(2)
  94    of size buf_size and with buf_filled bytes already filled.  Ownership
  95    of the buffer is transferred to the resulting hFILE.  */
  96 hFILE *hfile_init_fixed(size_t struct_size, const char *mode,
  97                         char *buffer, size_t buf_filled, size_t buf_size);
  98
  99 /* May be called by hopen_*() functions to undo the effects of hfile_init()
 100    in the event opening the stream subsequently fails.  (This is safe to use
 101    even if fp is NULL.  This takes care to preserve errno.)  */
 102 void hfile_destroy(hFILE *fp);
 103
 104
 105 struct hFILE_scheme_handler {
 106     /* Opens a stream when dispatched by hopen(); should call hfile_init()
 107        to malloc a struct "derived" from hFILE and initialise it appropriately,
 108        including setting base.backend to its own backend vector.  */
 109     hFILE *(*open)(const char *filename, const char *mode) HTS_RESULT_USED;
 110
 111     /* Returns whether the URL denotes remote storage when dispatched by
 112        hisremote().  For simple cases, use one of hfile_always_*() below.  */
 113     int (*isremote)(const char *filename) HTS_RESULT_USED;
 114
 115     /* The name of the plugin or other code providing this handler.  */
 116     const char *provider;
 117
 118     /* If multiple handlers are registered for the same scheme, the one with
 119        the highest priority is used; range is 0 (lowest) to 100 (highest).
 120        This field is used modulo 1000 as a priority; thousands indicate
 121        later revisions to this structure, as noted below.  */
 122     int priority;
 123
 124     /* Fields below are present when priority >= 2000.  */
 125
 126     /* Same as the open() method, used when extra arguments have been given
 127        to hopen().  */
 128     hFILE *(*vopen)(const char *filename, const char *mode, va_list args)
 129         HTS_RESULT_USED;
 130 };
 131
 132 /* May be used as an isremote() function in simple cases.  */
 133 extern int hfile_always_local (const char *fname);
 134 extern int hfile_always_remote(const char *fname);
 135
 136 /* Should be called by plugins for each URL scheme they wish to handle.  */
 137 void hfile_add_scheme_handler(const char *scheme,
 138                               const struct hFILE_scheme_handler *handler);
 139
 140 struct hFILE_plugin {
 141     /* On entry, HTSlib's plugin API version (currently 1).  */
 142     int api_version;
 143
 144     /* On entry, the plugin's handle as returned by dlopen() etc.  */
 145     void *obj;
 146
 147     /* The plugin should fill this in with its (human-readable) name.  */
 148     const char *name;
 149
 150     /* The plugin may wish to fill in a function to be called on closing.  */
 151     void (*destroy)(void);
 152 };
 153
 154 #ifdef ENABLE_PLUGINS
 155 #define PLUGIN_GLOBAL(identifier,suffix) identifier
 156
 157 /* Plugins must define an entry point with this signature.  */
 158 extern int hfile_plugin_init(struct hFILE_plugin *self);
 159
 160 #else
 161 #define PLUGIN_GLOBAL(identifier,suffix) identifier##suffix
 162
 163 /* Only plugins distributed within the HTSlib source that might be built
 164    even with --disable-plugins need to use PLUGIN_GLOBAL and be listed here;
 165    others can simply define hfile_plugin_init().  */
 166
 167 extern int hfile_plugin_init_gcs(struct hFILE_plugin *self);
 168 extern int hfile_plugin_init_libcurl(struct hFILE_plugin *self);
 169 extern int hfile_plugin_init_s3(struct hFILE_plugin *self);
 170 #endif
 171
 172 /* This one is never built as a separate plugin.  */
 173 extern int hfile_plugin_init_net(struct hFILE_plugin *self);
 174
 175 #ifdef __cplusplus
 176 }
 177 #endif
 178
 179 #endif