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

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