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

   1 /*
   2  * Copyright (c) 2005 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License version 2.1 as
   6  * published by the Free Software Foundation.
   7  *
   8  * This library 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 Lesser General Public
  11  * License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this library; if not, write to the Free Software Foundation,
  15  * Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA.
  16  *
  17  * Contact information: Zmanda Inc., 505 N Mathlida Ave, Suite 120
  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 (PROPERTY_PHASE_MASK/2)
  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
  67 /* This structure is usually statically allocated.
  68  * It holds information about a property that is common to all devices of
  69  * a given type. */
  70
  71 typedef int DevicePropertyId;
  72
  73 typedef struct {
  74     DevicePropertyId ID; /* Set by device_property_register() */
  75     GType type;
  76     const char *name;
  77     const char *description;
  78 } DevicePropertyBase;
  79
  80 /* This structure is usually held inside a Device object. It holds
  81  * information about a property that is specific to the device/medium
  82  * in question. */
  83 typedef struct {
  84     const DevicePropertyBase *base;
  85     PropertyAccessFlags access;
  86 } DeviceProperty;
  87
  88 /* Registers a new property and returns its ID. This function takes ownership
  89  * of its argument; it must not be freed later. */
  90 extern DevicePropertyId device_property_register(DevicePropertyBase*);
  91
  92 /* This should be called exactly once from device_api_init(). */
  93 extern void device_property_init(void);
  94
  95 /* Gets a DevicePropertyBase from its ID. */
  96 extern const DevicePropertyBase* device_property_get_by_id(DevicePropertyId);
  97 extern const DevicePropertyBase* device_property_get_by_name(const char*);
  98
  99 /* Standard property value types here.
 100  * Important: see property.c for the other half of type declarations.*/
 101 typedef enum {
 102     CONCURRENCY_PARADIGM_EXCLUSIVE,
 103     CONCURRENCY_PARADIGM_SHARED_READ,
 104     CONCURRENCY_PARADIGM_RANDOM_ACCESS
 105 } ConcurrencyParadigm;
 106 #define CONCURRENCY_PARADIGM_TYPE concurrency_paradigm_get_type()
 107 GType concurrency_paradigm_get_type (void);
 108
 109 typedef enum {
 110     STREAMING_REQUIREMENT_NONE,
 111     STREAMING_REQUIREMENT_DESIRED,
 112     STREAMING_REQUIREMENT_REQUIRED
 113 } StreamingRequirement;
 114 #define STREAMING_REQUIREMENT_TYPE streaming_requirement_get_type()
 115 GType streaming_requirement_get_type (void);
 116
 117 typedef enum {
 118     MEDIA_ACCESS_MODE_READ_ONLY,
 119     MEDIA_ACCESS_MODE_WORM,
 120     MEDIA_ACCESS_MODE_READ_WRITE,
 121     MEDIA_ACCESS_MODE_WRITE_ONLY
 122 } MediaAccessMode;
 123 #define MEDIA_ACCESS_MODE_TYPE media_access_mode_get_type()
 124 GType media_access_mode_get_type (void);
 125
 126 /* This one is not a Glibified enum */
 127 typedef enum {
 128     SIZE_ACCURACY_UNKNOWN,
 129     SIZE_ACCURACY_ESTIMATE,
 130     SIZE_ACCURACY_REAL
 131 } SizeAccuracy;
 132
 133 /* But SizeAccuracy does apear in this Glibified (gBoxed) struct. */
 134 typedef struct {
 135     SizeAccuracy accuracy;
 136     guint64           bytes;
 137 } QualifiedSize;
 138 #define QUALIFIED_SIZE_TYPE qualified_size_get_type()
 139 GType qualified_size_get_type (void);
 140
 141 /* Some features can only be occasionally (or unreliably) detected, so
 142    this enum allows the user to override the detected or default
 143    setting. */
 144 typedef enum {
 145     /* Feature support status. (exactly one of these is set) */
 146         /* Feature is supported & will be used */
 147         FEATURE_STATUS_ENABLED   = (1 << 0),
 148         /* Features will not be used. */
 149         FEATURE_STATUS_DISABLED  = (1 << 1),
 150
 151     /* Feature support confidence. (exactly one of these is set). */
 152         /* Support is not based on conclusive evidence. */
 153         FEATURE_SURETY_BAD       = (1 << 2),
 154         /* Support is based on conclusive evidence. */
 155         FEATURE_SURETY_GOOD      = (1 << 3),
 156
 157    /* Source of this information. (exactly one of these is set). */
 158         /* Source of status is from default setting. */
 159         FEATURE_SOURCE_DEFAULT   = (1 << 4),
 160         /* Source of status is from device query. */
 161         FEATURE_SOURCE_DETECTED  = (1 << 5),
 162         /* Source of status is from user override. */
 163         FEATURE_SOURCE_USER      = (1 << 6),
 164
 165     FEATURE_SUPPORT_FLAGS_MAX = (1 << 7)
 166 } FeatureSupportFlags;
 167
 168 #define FEATURE_SUPPORT_FLAGS_MASK (FEATURE_SUPPORT_FLAGS_MAX-1)
 169 #define FEATURE_SUPPORT_FLAGS_STATUS_MASK (FEATURE_STATUS_ENABLED |  \
 170                                            FEATURE_STATUS_DISABLED)
 171 #define FEATURE_SUPPORT_FLAGS_SURETY_MASK (FEATURE_SURETY_BAD |      \
 172                                            FEATURE_SURETY_GOOD)
 173 #define FEATURE_SUPPORT_FLAGS_SOURCE_MASK (FEATURE_SOURCE_DEFAULT |  \
 174                                            FEATURE_SOURCE_DETECTED | \
 175                                            FEATURE_SOURCE_USER)
 176 /* Checks that mutually exclusive flags are not set. */
 177 gboolean feature_support_flags_is_valid(FeatureSupportFlags);
 178 #define FEATURE_SUPPORT_FLAGS_TYPE feature_support_get_type()
 179 GType feature_support_get_type (void);
 180
 181 /* Standard property definitions follow. See also property.c. */
 182
 183 /* Value is a ConcurrencyParadigm */
 184 extern DevicePropertyBase device_property_concurrency;
 185 #define PROPERTY_CONCURRENCY (device_property_concurrency.ID)
 186
 187 /* Value is a 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, where a negative number indicates variable block size. */
 201 extern DevicePropertyBase device_property_block_size;
 202 #define PROPERTY_BLOCK_SIZE (device_property_block_size.ID)
 203
 204 /* 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 gboolean. */
 211 extern DevicePropertyBase device_property_appendable;
 212 #define PROPERTY_APPENDABLE (device_property_appendable.ID)
 213
 214 /* Value is a string. */
 215 extern DevicePropertyBase device_property_canonical_name;
 216 #define PROPERTY_CANONICAL_NAME (device_property_canonical_name.ID)
 217
 218 /* Value is MediaAccessMode. */
 219 extern DevicePropertyBase device_property_medium_access_type;
 220 #define PROPERTY_MEDIUM_TYPE (device_property_medium_access_type.ID)
 221
 222 /* Value is a gboolean. */
 223 extern DevicePropertyBase device_property_partial_deletion;
 224 #define PROPERTY_PARTIAL_DELETION (device_property_partial_deletion.ID)
 225
 226 /* Value is a QualifiedSize, though the accuracy may be SIZE_ACCURACY_NONE. */
 227 extern DevicePropertyBase device_property_free_space;
 228 #define PROPERTY_FREE_SPACE (device_property_free_space.ID)
 229
 230 /* Value is a guint64. On devices that support it, this property will
 231    limit the total amount of data written to a volume; attempts to
 232    write beyond this point will cause the device to simulate "out of
 233    space". Zero means no limit. */
 234 extern DevicePropertyBase device_property_max_volume_usage;
 235 #define PROPERTY_MAX_VOLUME_USAGE (device_property_max_volume_usage.ID)
 236
 237 /* Tape device properties. These properties do not exist on non-linear
 238    devices. All of them have a value type of FeatureSupportFlags. */
 239 extern DevicePropertyBase device_property_fsf;
 240 #define PROPERTY_FSF (device_property_fsf.ID)
 241
 242 extern DevicePropertyBase device_property_bsf;
 243 #define PROPERTY_BSF (device_property_bsf.ID)
 244
 245 extern DevicePropertyBase device_property_fsr;
 246 #define PROPERTY_FSR (device_property_fsr.ID)
 247
 248 extern DevicePropertyBase device_property_bsr;
 249 #define PROPERTY_BSR (device_property_bsr.ID)
 250
 251 /* Is EOM supported? Must be able to read file number afterwards as
 252    well. */
 253 extern DevicePropertyBase device_property_eom;
 254 #define PROPERTY_EOM (device_property_eom.ID)
 255
 256 /* Is it necessary to perform a BSF after EOM? */
 257 extern DevicePropertyBase device_property_bsf_after_eom;
 258 #define PROPERTY_BSF_AFTER_EOM (device_property_bsf_after_eom.ID)
 259
 260 /* How many filemarks to write at EOD? (Default is 2).
 261  * This property is a G_TYPE_UINT, but can only really be set to 1 or 2. */
 262 extern DevicePropertyBase device_property_final_filemarks;
 263 #define PROPERTY_FINAL_FILEMARKS (device_property_final_filemarks.ID)
 264
 265 /* What buffer size is used for reading? */
 266 extern DevicePropertyBase device_property_read_buffer_size;
 267 #define PROPERTY_READ_BUFFER_SIZE (device_property_read_buffer_size.ID)
 268
 269 /* Authentication information for Amazon S3. Both of these are strings. */
 270 extern DevicePropertyBase device_property_s3_secret_key;
 271 extern DevicePropertyBase device_property_s3_access_key;
 272 #define PROPERTY_S3_SECRET_KEY (device_property_s3_secret_key.ID)
 273 #define PROPERTY_S3_ACCESS_KEY (device_property_s3_access_key.ID)
 274
 275 #ifdef WANT_DEVPAY
 276 /* Same, but for S3 with DevPay. This directory can be relative to the
 277  * config director, or absolute. */
 278 extern DevicePropertyBase device_property_s3_user_token;
 279 #define PROPERTY_S3_USER_TOKEN (device_property_s3_user_token.ID)
 280 #endif
 281
 282 /* Should the device produce verbose output?  Value is a gboolean.  Not
 283  * recognized by all devices. */
 284 extern DevicePropertyBase device_property_verbose;
 285 #define PROPERTY_VERBOSE (device_property_verbose.ID)
 286
 287 #endif