device.h

开源备份软件源码 AMANDA, the Advanced Maryland Automatic Network Disk Archiver, is a backup system that a

 * passed timestamp may be NULL, in which case it will be filled in with 
 * the current time. */
gboolean 	device_start	(Device * self,
                                 DeviceAccessMode mode, char * label,
                                 char * timestamp);

/* This undoes device_start, returning you to the NULL state. Do this
 * if you want to (for example) change access mode.
 * 
 * Note to subclass implementors: Call this function first from your
 * finalization function. */
gboolean 	device_finish	(Device * self);

/* But you can't write any data until you call this function, too.
 * This function does not take ownership of the passed dumpfile_t; you must
 * free it yourself. */
gboolean        device_start_file       (Device * self,
                                         const dumpfile_t * jobInfo);

guint           device_write_min_size   (Device * self);
guint           device_write_max_size   (Device * self);
guint           device_read_max_size   (Device * self);

/* Does what you expect. size had better be inside the block size
 * range, or this function will write nothing.
 *
 * The short_block parameter needs some additional explanation: If
 * short_block is set to TRUE, then this function will accept a write
 * smaller than the minimum block size, subject to the following
 * caveats:
 * % The block may be padded with NULL bytes, which will be present on
 *   restore.
 * % device_write_block will automatically call device_finish_file()
 *   after writing this short block.
 * It is permitted to use short_block with a block that is not short;
 * in this case, it is equivalent to calling device_write() and then
 * calling device_finish_file(). */
gboolean 	device_write_block	(Device * self,
                                         guint size,
                                         gpointer data,
                                         gboolean short_block);

/* This will drain the given fd (reading until EOF), and write the
 * resulting data out to the device using maximally-sized blocks. */
gboolean 	device_write_from_fd	(Device * self,
					int fd);

/* Call this when you are finished writing a file. This function will
 * write a filemark or the local equivalent, flush the buffers, and do
 * whatever dirty work needs to be done at such a point in time. */
gboolean 	device_finish_file	(Device * self);

/* For reading only: Seeks to the beginning of a particular
 * filemark. Only do this when reading; opening in
 * ACCESS_WRITE will start you out at the first file, and opening in
 * ACCESS_APPEND will automatically seek to the end of the medium.
 * 
 * If the requested file doesn't exist, this function will seek to the
 * next-numbered valid file. You can check where this function seeked to
 * by examining the file field of the Device structure. If the requested
 * file number is exactly one more than the last valid file, this
 * function returns a TAPEEND header.
 *
 * If an error occurs or if the requested file is two or more beyond the
 * last valid file, this function returns NULL.
 *
 * Example results for a volume that has only files 1 and 3:
 * 1 -> Seeks to file 1
 * 2 -> Seeks to file 3
 * 3 -> Seeks to file 3
 * 4 -> Returns TAPEEND
 * 5 -> Returns NULL
 *
 * The returned dumpfile_t is yours to keep, at no extra charge. */
dumpfile_t* 	device_seek_file	(Device * self,
					guint file);

/* After you have called device_seek_file (and /only/ after having
 * called device_seek_file), you can call this to seek to a particular
 * block inside the file. It works like SEEK_SET, only in blocks. */
gboolean 	device_seek_block	(Device * self,
					guint64 block);

/* After you have called device_seek_file and/or device_seek_block,
 * you can start calling this function. It always reads exactly one whole
 * block at a time, however big that might be. You must pass in a buffer and
 * specify its size. If the buffer is big enough, the read is
 * performed, and both *size and the return value are equal to the
 * number of bytes actually read. If the buffer is not big enough, then
 * no read is performed, the function returns 0, and *size is set
 * to the minimum buffer size required to read the next block. If an
 * error occurs, the function returns -1  and *size is left unchanged.
 * 
 * It is not an error if buffer == NULL and *size == 0. This should be
 * treated as a query as to the possible size of the next block. */
int 	device_read_block	(Device * self,
                                 gpointer buffer,
                                 int * size);

/* This is the reading equivalent of device_write_from_fd(). It will
 * read from the device from the current location until end of file,
 * and drains the results out into the specified fd. Returns FALSE if
 * there is a problem writing to the fd. */
gboolean 	device_read_to_fd	(Device * self,
					int fd);

/* This function tells you what properties are supported by this
 * device, and when you are allowed to get and set them. The return
 * value is an array of DeviceProperty structs. The last struct in
 * the array is zeroed, so you know when the end is (check the
 * pointer element "base"). The return value from this function on any
 * given object (or physical device) should be invariant. */
const DeviceProperty * 	device_property_get_list	(Device * self);

/* These functions get or set a particular property. The val should be
 * compatible with the DevicePropertyBase associated with the given
 * DevicePropertyId, and this function should only be called when
 * DeviceProperty.access says it is OK. Otherwise you will get an
 * error and not the tasty property action you wanted. */
gboolean 	device_property_get	(Device * self,
                                         DevicePropertyId id,
                                         GValue * val);
gboolean 	device_property_set	(Device * self,
                                         DevicePropertyId id,
                                         GValue * val);

/* On devices that support it (check PROPERTY_PARTIAL_DELETION),
 * this will free only the space associated with a particular file. 
 * This way, you can apply a different retention policy to every file
 * on the volume, appending new data at the end and recycling anywhere
 * in the middle -- even simultaneously (via different Device
 * handles)! Note that you generally can't recycle a file that is presently in
 * use (being read or written).
 *
 * To use this, open the device as DEVICE_MODE_APPEND. But you don't
 * have to call device_start_file(), unless you want to write some
 * data, too. */
gboolean 	device_recycle_file	(Device * self,
					guint filenum);

/* Protected methods. Don't call these except in subclass implementations. */

/* Registers a new device / property pair. Every superclass of Device
 * should call this in its init() function. At the moment, any
 * particular property Id can only be registered once per object.
 *
 * If you want to register a standard response to a property (e.g.,
 * whether or not the device supports compression), you can pass a
 * non-NULL response. Then the default implementation of
 * device_get_property (which you may override) will return this
 * response.
 * The contents of prop and response are copied into a private array, so the
 * calling function retains ownership of all arguments.
 */
void            device_add_property(Device * self, DeviceProperty * prop,
                                    GValue * response);

/* This method provides post-construction initalization once the
 * device name is known. It should only be used by Device
 * factories. It is provided here as a virtual method (instead of
 * a static function) because some devices may want to chain
 * initilization to their parents. */
gboolean device_open_device (Device * self,
                             char * device_name);

/* Builds a proper header based on device block size possibilities.
 * If non-null, size is filled in with the number of bytes that should
 * be written.
 * If non-null, oneblock is filled in with TRUE if the header will fit
 * in a single Device block (FALSE otherwise). */
char * device_build_amanda_header(Device * self, const dumpfile_t * jobinfo,
                                  int * size, gboolean * oneblock);

/* Does what you expect. You have to free the returned header. Ensures
   that self->volume_time matches the header written to tape. */
dumpfile_t * make_tapestart_header(Device * self, char * label,
                                   char * timestamp);

/* Does what you expect. Uses the current time. */
dumpfile_t * make_tapeend_header(void);

/* Set up first-run properties from loaded configuration file, including
 * DEVICE_MAX_VOLUME_USAGE property based on the tapetype. */
void device_set_startup_properties_from_config(Device * device);

/* Erase any stored volume information. Use this if something happens (e.g.,
 * a property is set) that voids previously-read volume details.
 * This function is a NOOP unless the device is in the NULL state. */
void device_clear_volume_details(Device * device);

#endif /* DEVICE_H */