2 * Copyright (c) 2005-2008 Zmanda Inc. All Rights Reserved.
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.
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.
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.
17 * Contact information: Zmanda Inc., 465 S Mathlida Ave, Suite 300
18 * Sunnyvale, CA 94086, USA, or: http://www.zmanda.com
21 #ifndef DEVICE_PROPERTY_H
22 #define DEVICE_PROPERTY_H
25 #include <glib-object.h>
26 #include "queueing.h" /* for StreamingRequirement */
28 /* The properties interface defines define capabilities and other interesting
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)
40 #define PROPERTY_PHASE_MASK (PROPERTY_PHASE_MAX-1)
41 #define PROPERTY_PHASE_SHIFT 8
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),
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;
64 #define PROPERTY_ACCESS_GET_MASK (PROPERTY_PHASE_MASK)
65 #define PROPERTY_ACCESS_SET_MASK (PROPERTY_PHASE_MASK << PROPERTY_PHASE_SHIFT)
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. */
72 /* Support is not based on conclusive evidence. */
74 /* Support is based on conclusive evidence. */
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). */
91 /* This should be called exactly once from device_api_init(). */
92 extern void device_property_init(void);
94 /* This structure is usually statically allocated. It holds information about
95 * a property that is common across all devices.
97 typedef guint DevicePropertyId;
99 DevicePropertyId ID; /* Set by device_property_register() */
102 const char *description;
103 } DevicePropertyBase;
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*);
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,
119 /* Gets a DevicePropertyBase from its ID. */
120 DevicePropertyBase* device_property_get_by_id(DevicePropertyId);
121 DevicePropertyBase* device_property_get_by_name(const char*);
124 * Class-level Property Information
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)(
133 DevicePropertyBase *base,
135 PropertySurety surety,
136 PropertySource source);
137 typedef gboolean (*PropertyGetFn)(
139 DevicePropertyBase *base,
141 PropertySurety *surety,
142 PropertySource *source);
145 DevicePropertyBase *base;
146 PropertyAccessFlags access;
147 PropertySetFn setter;
148 PropertyGetFn getter;
152 * Property-specific Types, etc.
155 /* Standard property value types here.
156 * Important: see property.c for the other half of type declarations.*/
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);
165 #define STREAMING_REQUIREMENT_TYPE streaming_requirement_get_type()
166 GType streaming_requirement_get_type (void);
169 MEDIA_ACCESS_MODE_READ_ONLY,
170 MEDIA_ACCESS_MODE_WORM,
171 MEDIA_ACCESS_MODE_READ_WRITE,
172 MEDIA_ACCESS_MODE_WRITE_ONLY
174 #define MEDIA_ACCESS_MODE_TYPE media_access_mode_get_type()
175 GType media_access_mode_get_type (void);
177 /* This one is not a Glibified enum */
179 SIZE_ACCURACY_UNKNOWN,
180 SIZE_ACCURACY_ESTIMATE,
184 /* But SizeAccuracy does apear in this Glibified (gBoxed) struct. */
186 SizeAccuracy accuracy;
189 #define QUALIFIED_SIZE_TYPE qualified_size_get_type()
190 GType qualified_size_get_type (void);
192 /* Standard property definitions follow. See also property.c. */
194 /* Value is a ConcurrencyParadigm */
195 extern DevicePropertyBase device_property_concurrency;
196 #define PROPERTY_CONCURRENCY (device_property_concurrency.ID)
198 /* Value is a StreamingRequirement */
199 extern DevicePropertyBase device_property_streaming;
200 #define PROPERTY_STREAMING (device_property_streaming.ID)
202 /* Value is a gboolean. */
203 extern DevicePropertyBase device_property_compression;
204 #define PROPERTY_COMPRESSION (device_property_compression.ID)
206 /* Value is a gdouble, representing (compressed size)/(original
207 size). The period over which this value is measured is undefined. */
208 extern DevicePropertyBase device_property_compression_rate;
209 #define PROPERTY_COMPRESSION_RATE (device_property_compression_rate.ID)
211 /* Value is a gint; gives the write block size. */
212 extern DevicePropertyBase device_property_block_size;
213 #define PROPERTY_BLOCK_SIZE (device_property_block_size.ID)
215 /* Read-only. Value is a guint. */
216 extern DevicePropertyBase device_property_min_block_size;
217 extern DevicePropertyBase device_property_max_block_size;
218 #define PROPERTY_MIN_BLOCK_SIZE (device_property_min_block_size.ID)
219 #define PROPERTY_MAX_BLOCK_SIZE (device_property_max_block_size.ID)
221 /* Value is a guint; gives the minimum buffer size for reads. Only
222 * the tape device implements this, but it corresponds to the tapetype
223 * readblocksize parameter, so it's a global property*/
224 extern DevicePropertyBase device_property_read_buffer_size;
225 #define PROPERTY_READ_BUFFER_SIZE (device_property_read_buffer_size.ID)
227 /* Value is a gboolean. */
228 extern DevicePropertyBase device_property_appendable;
229 #define PROPERTY_APPENDABLE (device_property_appendable.ID)
231 /* Value is a string. */
232 extern DevicePropertyBase device_property_canonical_name;
233 #define PROPERTY_CANONICAL_NAME (device_property_canonical_name.ID)
235 /* Value is MediaAccessMode. */
236 extern DevicePropertyBase device_property_medium_access_type;
237 #define PROPERTY_MEDIUM_ACCESS_TYPE (device_property_medium_access_type.ID)
239 /* Value is a gboolean. */
240 extern DevicePropertyBase device_property_partial_deletion;
241 #define PROPERTY_PARTIAL_DELETION (device_property_partial_deletion.ID)
243 /* Value is a QualifiedSize, though the accuracy may be SIZE_ACCURACY_NONE. */
244 extern DevicePropertyBase device_property_free_space;
245 #define PROPERTY_FREE_SPACE (device_property_free_space.ID)
247 /* Value is a guint64. On devices that support it, this property will
248 limit the total amount of data written to a volume; attempts to
249 write beyond this point will cause the device to simulate "out of
250 space". Zero means no limit. */
251 extern DevicePropertyBase device_property_max_volume_usage;
252 #define PROPERTY_MAX_VOLUME_USAGE (device_property_max_volume_usage.ID)
254 /* Should the device produce verbose output? Value is a gboolean. Not
255 * present in all devices. */
256 extern DevicePropertyBase device_property_verbose;
257 #define PROPERTY_VERBOSE (device_property_verbose.ID)