git.gag.com Git - debian/amanda/blob - device-src/property.h

   1 /*
   2  * Copyright (c) 2007-2012 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  11  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  17  *
  18  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  19  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  20  */
  21
  22 #ifndef DEVICE_PROPERTY_H
  23 #define DEVICE_PROPERTY_H
  24
  25 #include <glib.h>
  26 #include <glib-object.h>
  27
  28 /* The properties interface defines define capabilities and other interesting
  29  * properties. */
  30
  31 typedef enum {
  32     PROPERTY_PHASE_BEFORE_START       = (1 << 0),
  33     PROPERTY_PHASE_BETWEEN_FILE_WRITE = (1 << 1),
  34     PROPERTY_PHASE_INSIDE_FILE_WRITE  = (1 << 2),
  35     PROPERTY_PHASE_BETWEEN_FILE_READ  = (1 << 3),
  36     PROPERTY_PHASE_INSIDE_FILE_READ   = (1 << 4),
  37     PROPERTY_PHASE_MAX                = (1 << 5)
  38 } PropertyPhaseFlags;
  39
  40 #define PROPERTY_PHASE_MASK (PROPERTY_PHASE_MAX-1)
  41 #define PROPERTY_PHASE_SHIFT 8
  42
  43 typedef enum {
  44     PROPERTY_ACCESS_GET_BEFORE_START = (PROPERTY_PHASE_BEFORE_START),
  45     PROPERTY_ACCESS_GET_BETWEEN_FILE_WRITE =
  46         (PROPERTY_PHASE_BETWEEN_FILE_WRITE),
  47     PROPERTY_ACCESS_GET_INSIDE_FILE_WRITE = (PROPERTY_PHASE_INSIDE_FILE_WRITE),
  48     PROPERTY_ACCESS_GET_BETWEEN_FILE_READ =
  49         (PROPERTY_PHASE_BETWEEN_FILE_READ),
  50     PROPERTY_ACCESS_GET_INSIDE_FILE_READ = (PROPERTY_PHASE_INSIDE_FILE_READ),
  51
  52     PROPERTY_ACCESS_SET_BEFORE_START =
  53         (PROPERTY_PHASE_BEFORE_START << PROPERTY_PHASE_SHIFT),
  54     PROPERTY_ACCESS_SET_BETWEEN_FILE_WRITE =
  55         (PROPERTY_PHASE_BETWEEN_FILE_WRITE << PROPERTY_PHASE_SHIFT),
  56     PROPERTY_ACCESS_SET_INSIDE_FILE_WRITE =
  57         (PROPERTY_PHASE_INSIDE_FILE_WRITE << PROPERTY_PHASE_SHIFT),
  58     PROPERTY_ACCESS_SET_BETWEEN_FILE_READ =
  59         (PROPERTY_PHASE_BETWEEN_FILE_READ << PROPERTY_PHASE_SHIFT),
  60     PROPERTY_ACCESS_SET_INSIDE_FILE_READ =
  61         (PROPERTY_PHASE_INSIDE_FILE_READ << PROPERTY_PHASE_SHIFT)
  62 } PropertyAccessFlags;
  63
  64 #define PROPERTY_ACCESS_GET_MASK (PROPERTY_PHASE_MASK)
  65 #define PROPERTY_ACCESS_SET_MASK (PROPERTY_PHASE_MASK << PROPERTY_PHASE_SHIFT)
  66
  67 /* Some properties can only be occasionally (or unreliably) detected, so
  68  * this enum allows the user to override the detected or default
  69  * setting.  Surety indicates a level of confidence in the value, while
  70  * source describes how we found out about it. */
  71 typedef enum {
  72     /* Support is not based on conclusive evidence. */
  73     PROPERTY_SURETY_BAD,
  74     /* Support is based on conclusive evidence. */
  75     PROPERTY_SURETY_GOOD,
  76 } PropertySurety;
  77
  78 typedef enum {
  79     /* property is from default setting. */
  80     PROPERTY_SOURCE_DEFAULT,
  81     /* property is from device query. */
  82     PROPERTY_SOURCE_DETECTED,
  83     /* property is from user override (configuration). */
  84     PROPERTY_SOURCE_USER,
  85 } PropertySource;
  86
  87 /*****
  88  * Initialization
  89  */
  90
  91 /* This should be called exactly once from device_api_init(). */
  92 extern void device_property_init(void);
  93
  94 /* This structure is usually statically allocated.  It holds information about
  95  * a property that is common across all devices.
  96  */
  97 typedef guint DevicePropertyId;
  98 typedef struct {
  99     DevicePropertyId ID; /* Set by device_property_register() */
 100     GType type;
 101     const char *name;
 102     const char *description;
 103 } DevicePropertyBase;
 104
 105 /* Registers a new property and returns its ID. This function takes ownership
 106  * of its argument; it must not be freed later.  It should be called from a
 107  * device driver's registration function. */
 108 extern DevicePropertyId device_property_register(DevicePropertyBase*);
 109
 110 /* Does the same thing, but fills in a new DevicePropertyBase with the given
 111  * values first, and does not return the ID.  This is more convenient for
 112  * device-specific properties. */
 113 extern void device_property_fill_and_register(
 114     DevicePropertyBase * base,
 115     GType type,
 116     const char * name,
 117     const char * desc);
 118
 119 /* Gets a DevicePropertyBase from its ID. */
 120 DevicePropertyBase* device_property_get_by_id(DevicePropertyId);
 121 DevicePropertyBase* device_property_get_by_name(const char*);
 122
 123 /*****
 124  * Class-level Property Information
 125  */
 126
 127 /* This structure is held inside a Device object. It holds information about a
 128  * property that is specific to the device driver, but not to a specific
 129  * instance of the driver. */
 130 struct Device; /* forward declaration */
 131 typedef gboolean (*PropertySetFn)(
 132     struct Device *self,
 133     DevicePropertyBase *base,
 134     GValue *val,
 135     PropertySurety surety,
 136     PropertySource source);
 137 typedef gboolean (*PropertyGetFn)(
 138     struct Device *self,
 139     DevicePropertyBase *base,
 140     GValue *val,
 141     PropertySurety *surety,
 142     PropertySource *source);
 143
 144 typedef struct {
 145     DevicePropertyBase *base;
 146     PropertyAccessFlags access;
 147     PropertySetFn setter;
 148     PropertyGetFn getter;
 149 } DeviceProperty;
 150
 151 /*****
 152  * Property-specific Types, etc.
 153  */
 154
 155 /* Standard property value types here.
 156  * Important: see property.c for the other half of type declarations.*/
 157 typedef enum {
 158     CONCURRENCY_PARADIGM_EXCLUSIVE,
 159     CONCURRENCY_PARADIGM_SHARED_READ,
 160     CONCURRENCY_PARADIGM_RANDOM_ACCESS
 161 } ConcurrencyParadigm;
 162 #define CONCURRENCY_PARADIGM_TYPE concurrency_paradigm_get_type()
 163 GType concurrency_paradigm_get_type (void);
 164
 165 #define STREAMING_REQUIREMENT_TYPE streaming_requirement_get_type()
 166 GType streaming_requirement_get_type (void);
 167
 168 typedef enum {
 169     MEDIA_ACCESS_MODE_READ_ONLY,
 170     MEDIA_ACCESS_MODE_WORM,
 171     MEDIA_ACCESS_MODE_READ_WRITE,
 172     MEDIA_ACCESS_MODE_WRITE_ONLY
 173 } MediaAccessMode;
 174 #define MEDIA_ACCESS_MODE_TYPE media_access_mode_get_type()
 175 GType media_access_mode_get_type (void);
 176
 177 /* Standard property definitions follow. See also property.c. */
 178
 179 /* Value is a ConcurrencyParadigm */
 180 extern DevicePropertyBase device_property_concurrency;
 181 #define PROPERTY_CONCURRENCY (device_property_concurrency.ID)
 182
 183 /* Value is a StreamingRequirement */
 184 typedef enum {
 185     STREAMING_REQUIREMENT_NONE,
 186     STREAMING_REQUIREMENT_DESIRED,
 187     STREAMING_REQUIREMENT_REQUIRED
 188 } StreamingRequirement;
 189 extern DevicePropertyBase device_property_streaming;
 190 #define PROPERTY_STREAMING (device_property_streaming.ID)
 191
 192 /* Value is a gboolean. */
 193 extern DevicePropertyBase device_property_compression;
 194 #define PROPERTY_COMPRESSION (device_property_compression.ID)
 195
 196 /* Value is a gdouble, representing (compressed size)/(original
 197    size). The period over which this value is measured is undefined. */
 198 extern DevicePropertyBase device_property_compression_rate;
 199 #define PROPERTY_COMPRESSION_RATE (device_property_compression_rate.ID)
 200
 201 /* Value is a gint; gives the write block size. */
 202 extern DevicePropertyBase device_property_block_size;
 203 #define PROPERTY_BLOCK_SIZE (device_property_block_size.ID)
 204
 205 /* Read-only.  Value is a guint. */
 206 extern DevicePropertyBase device_property_min_block_size;
 207 extern DevicePropertyBase device_property_max_block_size;
 208 #define PROPERTY_MIN_BLOCK_SIZE (device_property_min_block_size.ID)
 209 #define PROPERTY_MAX_BLOCK_SIZE (device_property_max_block_size.ID)
 210
 211 /* Value is a guint; gives the minimum buffer size for reads. Only
 212  * the tape device implements this, but it corresponds to the tapetype
 213  * readblocksize parameter, so it's a global property*/
 214 extern DevicePropertyBase device_property_read_block_size;
 215 #define PROPERTY_READ_BLOCK_SIZE (device_property_read_block_size.ID)
 216
 217 /* Value is a gboolean. */
 218 extern DevicePropertyBase device_property_appendable;
 219 #define PROPERTY_APPENDABLE (device_property_appendable.ID)
 220
 221 /* Value is a string. */
 222 extern DevicePropertyBase device_property_canonical_name;
 223 #define PROPERTY_CANONICAL_NAME (device_property_canonical_name.ID)
 224
 225 /* Value is MediaAccessMode. */
 226 extern DevicePropertyBase device_property_medium_access_type;
 227 #define PROPERTY_MEDIUM_ACCESS_TYPE (device_property_medium_access_type.ID)
 228
 229 /* Value is a gboolean. */
 230 extern DevicePropertyBase device_property_partial_deletion;
 231 #define PROPERTY_PARTIAL_DELETION (device_property_partial_deletion.ID)
 232
 233 /* Value is a gboolean. */
 234 extern DevicePropertyBase device_property_full_deletion;
 235 #define PROPERTY_FULL_DELETION (device_property_full_deletion.ID)
 236
 237 /* Value is a guint64. On devices that support it, this property will
 238    limit the total amount of data written to a volume; attempts to
 239    write beyond this point will cause the device to simulate "out of
 240    space". Zero means no limit. */
 241 extern DevicePropertyBase device_property_max_volume_usage;
 242 #define PROPERTY_MAX_VOLUME_USAGE (device_property_max_volume_usage.ID)
 243
 244 /* For devices supporting max_volume_usage this property will be used
 245 disable/enable property max_volume_usage. If FALSE, max_volume_usage
 246 will not be verified while writing to the device */
 247 extern DevicePropertyBase device_property_enforce_max_volume_usage;
 248 #define PROPERTY_ENFORCE_MAX_VOLUME_USAGE (device_property_enforce_max_volume_usage.ID)
 249 /* Should the device produce verbose output?  Value is a gboolean.  Not
 250  * present in all devices. */
 251 extern DevicePropertyBase device_property_verbose;
 252 #define PROPERTY_VERBOSE (device_property_verbose.ID)
 253
 254 /* A comment for the use of the user. */
 255 extern DevicePropertyBase device_property_comment;
 256 #define PROPERTY_COMMENT (device_property_comment.ID)
 257
 258 /* Does this device support LEOM? */
 259 extern DevicePropertyBase device_property_leom;
 260 #define PROPERTY_LEOM (device_property_leom.ID)
 261
 262 #endif