2 * Copyright (c) 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
6 * as 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., 505 N Mathlida Ave, Suite 120
18 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
21 %module "Amanda::Device"
22 %include "amglue/amglue.swg"
23 %include "exception.i"
28 #include "fileheader.h"
31 /* import dumptype_t, among others */
32 %import "Amanda/Types.swg";
37 Amanda::Device - interact with Amanda data-storage devices
41 use Amanda::Device qw( :constants );
43 my $dev = Amanda::Device->new($device_name);
44 $dev->set_startup_properties_from_config();
45 if ($dev->read_label() == $READ_LABEL_STATUS_SUCCESS) {
46 print "Label on $device_name is '$dev->volume_label'\n";
49 See http://wiki.zmanda.com/index.php/Device_API for details on how Devices are used.
55 =head1 Amanda::Device Objects
57 =head2 Instance Variables
73 =item C<$volume_label>
81 See the wiki for descriptions of these functions
87 =item C<start($mode, $label, $timestamp)>
91 =item C<start_file($jobinfo)>
93 where C<$jobinfo> is a C<dumpfile_t> (see L<Amanda::Datatypes>)
95 =item C<write_min_size()>
97 =item C<write_max_size()>
99 =item C<read_max_size()>
101 =item C<write_block($size, $data, $short_block)>
103 Note that Perl code is not expected to handle on-device data, so there
104 is currently no way to provide data to this function from Perl. This may
105 change in future revisions.
107 =item C<write_from_fd($fd)>
109 where C<$fd> is an integer file descriptor, not a filehandle
111 =item C<finish_file()>
113 =item C<seek_file($file)>
115 =item C<seek_block($block)>
117 =item C<read_block($size)>
119 =item C<read_to_fd($fd)>
121 where C<$fd> is an integer file descriptor, not a filehandle
123 Note that Perl code is not expected to handle on-device data, so there
124 is currently no way to access the data this function returns. This may
125 change in future revisions.
127 =item C<property_list()>
129 returns a list of property names.
131 =item C<property_get($property_name)>
133 returns the property as the appropriate Perl type.
135 =item C<property_set($property_name, $value)>
137 where $value is of an appropriate type for the given property
139 =item C<recycle_file($filenum)>
141 =item C<set_startup_properties_from_config()>
147 This module defines a large number of constants. Again, consult the
148 wiki or C<device.h> for the details on their meaning. These constants
149 are available from the package namespace (e.g.,
150 C<Amanda::Device::ACCESS_WRITE>), of imported with the C<:constant>
157 /* Initialize the Device API on load */
163 /* Utility functions for typemaps, below */
166 set_sv_from_gvalue(GValue *value)
168 GType fundamental = G_TYPE_FUNDAMENTAL(G_VALUE_TYPE(value));
171 /* complex reference types */
172 switch (fundamental) {
174 sv = sv_2mortal(amglue_newSVi64(g_value_get_long(value)));
178 sv = sv_2mortal(amglue_newSVu64(g_value_get_ulong(value)));
182 sv = sv_2mortal(amglue_newSVi64(g_value_get_int64(value)));
186 sv = sv_2mortal(amglue_newSVu64(g_value_get_uint64(value)));
190 GType boxed_type = G_VALUE_TYPE(value);
194 if (boxed_type == QUALIFIED_SIZE_TYPE) {
195 qs = *(QualifiedSize*)(g_value_get_boxed(value));
198 hv = (HV *)sv_2mortal((SV *)newHV());
199 hv_store(hv, "accuracy", 8, newSViv(qs.accuracy), 0);
200 hv_store(hv, "bytes", 5, amglue_newSVi64(qs.bytes), 0);
202 sv = newRV((SV *)hv);
203 return newRV((SV *)hv);
205 warn("Unsupported boxed property type #%d", boxed_type);
208 sv_setsv(sv, &PL_sv_undef);
214 /* simple types that can be constructed with sv_set*v */
216 switch (fundamental) {
218 sv_setiv(sv, g_value_get_char(value));
222 sv_setuv(sv, g_value_get_uchar(value));
226 sv_setiv(sv, g_value_get_boolean(value));
230 sv_setiv(sv, g_value_get_int(value));
234 sv_setuv(sv, g_value_get_uint(value));
238 sv_setnv(sv, g_value_get_float(value));
242 sv_setnv(sv, g_value_get_double(value));
246 sv_setpv(sv, g_value_get_string(value));
250 sv_setiv(sv, g_value_get_enum(value));
254 sv_setiv(sv, g_value_get_flags(value));
260 case G_TYPE_INTERFACE:
263 warn("Unsupported fundamental property type #%d", fundamental);
264 sv_setsv(sv, &PL_sv_undef);
272 set_gvalue_from_sv(SV *sv, GValue *value)
274 GType fundamental = G_TYPE_FUNDAMENTAL(G_VALUE_TYPE(value));
275 switch (fundamental) {
277 if (!SvIOK(sv)) return FALSE;
278 g_value_set_char(value, SvIV(sv));
282 if (!SvIOK(sv)) return FALSE;
283 g_value_set_uchar(value, SvUV(sv));
287 if (!SvIOK(sv)) return FALSE;
288 g_value_set_boolean(value, SvIV(sv));
292 g_value_set_int(value, amglue_SvI32(sv));
296 g_value_set_uint(value, amglue_SvU32(sv));
300 g_value_set_int64(value, amglue_SvI64(sv));
304 g_value_set_uint64(value, amglue_SvU64(sv));
308 g_value_set_int64(value, amglue_SvI64(sv));
312 g_value_set_uint64(value, amglue_SvU64(sv));
316 if (!SvNOK(sv)) return FALSE;
317 g_value_set_float(value, SvNV(sv));
321 if (!SvNOK(sv)) return FALSE;
322 g_value_set_double(value, SvNV(sv));
326 if (!SvPOK(sv)) return FALSE;
327 g_value_set_string(value, SvPV_nolen(sv));
331 if (!SvIOK(sv)) return FALSE;
332 g_value_set_enum(value, SvIV(sv));
336 if (!SvIOK(sv)) return FALSE;
337 g_value_set_flags(value, SvIV(sv));
343 case G_TYPE_INTERFACE:
344 case G_TYPE_BOXED: /* note: *getting* boxed values is supported */
356 * Device struct, %extend-ed into a Perl class
359 typedef struct Device {
360 /* Instance variables -- all readonly */
366 DeviceAccessMode access_mode;
375 Device(char *device_name) {
376 return device_open(device_name);
380 g_object_unref(self);
385 return device_read_label(self);
389 start(DeviceAccessMode mode, char *label, char *timestamp) {
390 return device_start(self, mode, label, timestamp);
395 return device_finish(self);
399 start_file(const dumpfile_t *jobInfo) {
400 return device_start_file(self, jobInfo);
405 return device_write_min_size(self);
410 return device_write_max_size(self);
415 return device_read_max_size(self);
419 write_block(guint size, gpointer data, gboolean short_block) {
420 return device_write_block(self, size, data, short_block);
424 write_from_fd(int fd) {
425 return device_write_from_fd(self, fd);
430 return device_finish_file(self);
434 seek_file(guint file) {
435 return device_seek_file(self, file);
439 seek_block(guint64 block) {
440 return device_seek_block(self, block);
444 read_block(gpointer buffer, int *size) {
445 return device_read_block(self, buffer, size);
448 gboolean read_to_fd(int fd) {
449 return device_read_to_fd(self, fd);
452 %typemap(out) const DeviceProperty * {
456 /* Count the DeviceProperties */
457 while ($1[len].base) len++;
458 EXTEND(SP, len); /* make room for return values */
460 /* Note that we set $result several times. the nature of
461 * SWIG's wrapping is such that incrementing argvi points
462 * $result to the next location in perl's argument stack.
465 for (i = 0; i < len ; i++) {
466 $result = sv_newmortal();
467 sv_setpv($result, $1[i].base->name);
471 const DeviceProperty * property_list(void) {
472 return device_property_get_list(self);
475 %typemap(out) const DeviceProperty *; /* remove typemap */
477 /* A typemap to convert a property name to a DevicePropertyBase. */
478 %typemap(in) DevicePropertyBase * {
482 pname = SvPV_nolen($input);
484 if (pname) $1 = (DevicePropertyBase *)device_property_get_by_name(pname);
486 SWIG_exception_fail(SWIG_ValueError, "Invalid property name");
490 /* A typemap to convert the GValue in property_get to a return value. The
491 * (in) typemap sets up storage for the parameters, while the (argout) converts
492 * them to a perl SV. */
493 %typemap(in,numinputs=0) (GValue *out_val, gboolean *val_found)
494 (GValue val, gboolean found) {
495 memset(&val, 0, sizeof(val));
499 %typemap(argout) (GValue *out_val, gboolean *val_found) {
500 /* if the result is valid */
502 /* move data from $1 to $result, somehow */
503 $result = set_sv_from_gvalue($1);
505 /* free any memory for the GValue */
508 /* silently return 'undef', the sentinel for "undefined" */
509 $result = sv_newmortal();
510 sv_setsv($result, &PL_sv_undef);
516 property_get(DevicePropertyBase *pbase, GValue *out_val, gboolean *val_found) {
517 *val_found = device_property_get(self, pbase->ID, out_val);
520 /* delete typemaps */
521 %typemap(in) (GValue *out_val, gboolean *val_found);
522 %typemap(argout) (GValue *out_val, gboolean *val_found);
524 /* We cheat a little bit here and just pass the native Perl type in to
525 * the function. This is the easiest way to make sure we know the property
526 * information (in particular, its type) before trying to convert the SV. */
527 %typemap(in) SV *sv "$1 = $input;"
530 property_set(DevicePropertyBase *pbase, SV *sv) {
532 memset(&gval, 0, sizeof(gval));
533 g_value_init(&gval, pbase->type);
534 if (!set_gvalue_from_sv(sv, &gval))
537 if (!device_property_set(self, pbase->ID, &gval))
540 g_value_unset(&gval);
543 g_value_unset(&gval);
547 gboolean recycle_file(guint filenum) {
548 return device_recycle_file(self, filenum);
551 void set_startup_properties_from_config(void) {
552 device_set_startup_properties_from_config(self);
561 amglue_add_flag_tag_fns(DeviceAccessMode);
562 amglue_add_constant_short(ACCESS_NULL, "NULL", DeviceAccessMode);
563 amglue_add_constant_short(ACCESS_READ, "READ", DeviceAccessMode);
564 amglue_add_constant_short(ACCESS_WRITE, "WRITE", DeviceAccessMode);
565 amglue_add_constant_short(ACCESS_APPEND, "APPEND", DeviceAccessMode);
567 /* (this is really a macro, but SWIG will Do The Right Thing */
568 gboolean IS_WRITABLE_ACCESS_MODE(DeviceAccessMode mode);
569 amglue_export_tag(DeviceAccessMode, IS_WRITABLE_ACCESS_MODE);
570 amglue_copy_to_tag(DeviceAccessMode, constants);
572 amglue_add_flag_tag_fns(ReadLabelStatusFlags);
573 amglue_add_constant_short(READ_LABEL_STATUS_SUCCESS, "SUCCESS", ReadLabelStatusFlags);
574 amglue_add_constant_short(READ_LABEL_STATUS_DEVICE_MISSING, "DEVICE_MISSING", ReadLabelStatusFlags);
575 amglue_add_constant_short(READ_LABEL_STATUS_DEVICE_ERROR, "DEVICE_ERROR", ReadLabelStatusFlags);
576 amglue_add_constant_short(READ_LABEL_STATUS_VOLUME_MISSING, "VOLUME_MISSING", ReadLabelStatusFlags);
577 amglue_add_constant_short(READ_LABEL_STATUS_VOLUME_UNLABELED, "VOLUME_UNLABELED", ReadLabelStatusFlags);
578 amglue_add_constant_short(READ_LABEL_STATUS_VOLUME_ERROR, "VOLUME_ERROR", ReadLabelStatusFlags);
579 amglue_add_constant_noshort(READ_LABEL_STATUS_FLAGS_MAX, ReadLabelStatusFlags);
580 amglue_copy_to_tag(ReadLabelStatusFlags, constants);
582 amglue_add_flag_tag_fns(PropertyPhaseFlags);
583 amglue_add_constant_short(PROPERTY_PHASE_BEFORE_START, "BEFORE_START", PropertyPhaseFlags);
584 amglue_add_constant_short(PROPERTY_PHASE_BETWEEN_FILE_WRITE, "BETWEEN_FILE_WRITE", PropertyPhaseFlags);
585 amglue_add_constant_short(PROPERTY_PHASE_INSIDE_FILE_WRITE, "INSIDE_FILE_WRITE", PropertyPhaseFlags);
586 amglue_add_constant_short(PROPERTY_PHASE_BETWEEN_FILE_READ, "BETWEEN_FILE_READ", PropertyPhaseFlags);
587 amglue_add_constant_short(PROPERTY_PHASE_INSIDE_FILE_READ, "INSIDE_FILE_READ", PropertyPhaseFlags);
588 amglue_add_constant_noshort(PROPERTY_PHASE_MAX, PropertyPhaseFlags);
589 amglue_add_constant_noshort(PROPERTY_PHASE_MASK, PropertyPhaseFlags);
590 amglue_add_constant_noshort(PROPERTY_PHASE_SHIFT, PropertyPhaseFlags);
591 amglue_copy_to_tag(PropertyPhaseFlags, constants);
593 amglue_add_flag_tag_fns(PropertyAccessFlags);
594 amglue_add_constant_short(PROPERTY_ACCESS_GET_BEFORE_START,
595 "GET_BEFORE_START", PropertyAccessFlags);
596 amglue_add_constant_short(PROPERTY_ACCESS_GET_BETWEEN_FILE_WRITE,
597 "GET_BETWEEN_FILE_WRITE", PropertyAccessFlags);
598 amglue_add_constant_short(PROPERTY_ACCESS_GET_INSIDE_FILE_WRITE,
599 "GET_INSIDE_FILE_WRITE", PropertyAccessFlags);
600 amglue_add_constant_short(PROPERTY_ACCESS_GET_BETWEEN_FILE_READ,
601 "GET_BETWEEN_FILE_READ", PropertyAccessFlags);
602 amglue_add_constant_short(PROPERTY_ACCESS_GET_INSIDE_FILE_READ,
603 "GET_INSIDE_FILE_READ", PropertyAccessFlags);
604 amglue_add_constant_short(PROPERTY_ACCESS_SET_BEFORE_START,
605 "SET_BEFORE_START", PropertyAccessFlags);
606 amglue_add_constant_short(PROPERTY_ACCESS_SET_BETWEEN_FILE_WRITE,
607 "SET_BETWEEN_FILE_WRITE", PropertyAccessFlags);
608 amglue_add_constant_short(PROPERTY_ACCESS_SET_INSIDE_FILE_WRITE,
609 "SET_INSIDE_FILE_WRITE", PropertyAccessFlags);
610 amglue_add_constant_short(PROPERTY_ACCESS_SET_BETWEEN_FILE_READ,
611 "SET_BETWEEN_FILE_READ", PropertyAccessFlags);
612 amglue_add_constant_short(PROPERTY_ACCESS_SET_INSIDE_FILE_READ,
613 "SET_INSIDE_FILE_READ", PropertyAccessFlags);
614 amglue_add_constant_noshort(PROPERTY_ACCESS_GET_MASK, PropertyAccessFlags);
615 amglue_add_constant_noshort(PROPERTY_ACCESS_SET_MASK, PropertyAccessFlags);
616 amglue_copy_to_tag(PropertyAccessFlags, constants);
618 amglue_add_enum_tag_fns(ConcurrencyParadigm);
619 amglue_add_constant_short(CONCURRENCY_PARADIGM_EXCLUSIVE, "EXCLUSIVE", ConcurrencyParadigm);
620 amglue_add_constant_short(CONCURRENCY_PARADIGM_SHARED_READ, "SHARED_READ", ConcurrencyParadigm);
621 amglue_add_constant_short(CONCURRENCY_PARADIGM_RANDOM_ACCESS, "RANDOM_ACCESS", ConcurrencyParadigm);
622 amglue_copy_to_tag(ConcurrencyParadigm, constants);
624 amglue_add_enum_tag_fns(StreamingRequirement);
625 amglue_add_constant_short(STREAMING_REQUIREMENT_NONE, "NONE", StreamingRequirement);
626 amglue_add_constant_short(STREAMING_REQUIREMENT_DESIRED, "DESIRED", StreamingRequirement);
627 amglue_add_constant_short(STREAMING_REQUIREMENT_REQUIRED, "REQUIRED", StreamingRequirement);
628 amglue_copy_to_tag(StreamingRequirement, constants);
630 amglue_add_enum_tag_fns(MediaAccessMode);
631 amglue_add_constant_short(MEDIA_ACCESS_MODE_READ_ONLY, "READ_ONLY", MediaAccessMode);
632 amglue_add_constant_short(MEDIA_ACCESS_MODE_WORM, "WORM", MediaAccessMode);
633 amglue_add_constant_short(MEDIA_ACCESS_MODE_READ_WRITE, "READ_WRITE", MediaAccessMode);
634 amglue_add_constant_short(MEDIA_ACCESS_MODE_WRITE_ONLY, "WRITE_ONLY", MediaAccessMode);
635 amglue_copy_to_tag(MediaAccessMode, constants);
637 amglue_add_enum_tag_fns(SizeAccuracy);
638 amglue_add_constant_short(SIZE_ACCURACY_UNKNOWN, "UNKNOWN", SizeAccuracy);
639 amglue_add_constant_short(SIZE_ACCURACY_ESTIMATE, "ESTIMATE", SizeAccuracy);
640 amglue_add_constant_short(SIZE_ACCURACY_REAL, "REAL", SizeAccuracy);
641 amglue_copy_to_tag(SizeAccuracy, constants);
643 amglue_add_flag_tag_fns(FeatureSupportFlags);
644 amglue_add_constant_short(FEATURE_STATUS_ENABLED, "STATUS_ENABLED", FeatureSupportFlags);
645 amglue_add_constant_short(FEATURE_STATUS_DISABLED, "STATUS_DISABLED", FeatureSupportFlags);
646 amglue_add_constant_short(FEATURE_SURETY_BAD, "SURETY_BAD", FeatureSupportFlags);
647 amglue_add_constant_short(FEATURE_SURETY_GOOD, "SURETY_GOOD", FeatureSupportFlags);
648 amglue_add_constant_short(FEATURE_SOURCE_DEFAULT, "SOURCE_DEFAULT", FeatureSupportFlags);
649 amglue_add_constant_short(FEATURE_SOURCE_DETECTED, "SOURCE_DETECTED", FeatureSupportFlags);
650 amglue_add_constant_short(FEATURE_SOURCE_USER, "SOURCE_USER", FeatureSupportFlags);
651 amglue_add_constant_noshort(FEATURE_SUPPORT_FLAGS_MAX, FeatureSupportFlags);
652 amglue_add_constant_noshort(FEATURE_SUPPORT_FLAGS_MASK, FeatureSupportFlags);
653 amglue_add_constant_noshort(FEATURE_SUPPORT_FLAGS_STATUS_MASK, FeatureSupportFlags);
654 amglue_add_constant_noshort(FEATURE_SUPPORT_FLAGS_SURETY_MASK, FeatureSupportFlags);
655 amglue_add_constant_noshort(FEATURE_SUPPORT_FLAGS_SOURCE_MASK, FeatureSupportFlags);
657 gboolean feature_support_flags_is_valid(FeatureSupportFlags);
658 amglue_export_tag(FeatureSupportFlags, feature_support_flags_is_valid);
659 amglue_copy_to_tag(FeatureSupportFlags, constants);
663 # SWIG produces a sub-package for the Device "class", in this case named
664 # Amanda::Device::Device. For user convenience, we allow Amanda::Device->new(..) to
665 # do the same thing. This is a wrapper function, and not just a typeglob assignment,
666 # because we want to get the right blessing.
669 Amanda::Device::Device->new(@_);