device.h

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

/*
 * Copyright (c) 2005 Zmanda, Inc.  All Rights Reserved.
 * 
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License version 2.1 as 
 * published by the Free Software Foundation.
 * 
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
 * License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA.
 * 
 * Contact information: Zmanda Inc., 505 N Mathlida Ave, Suite 120
 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
 */

/* The Device API abstracts device workings, interaction, properties, and
 * capabilities from the rest of the Amanda code base. It supports
 * pluggable modules for different kinds of devices. */

#ifndef DEVICE_H
#define DEVICE_H

#include <glib.h>
#include <glib-object.h>

#include "property.h"
#include "fileheader.h"

/* Device API version. */
#define DEVICE_API_VERSION 0

extern void device_api_init(void);

/* Different access modes */
typedef enum {
    ACCESS_NULL, /* Device is not yet opened. */
    ACCESS_READ,
    ACCESS_WRITE,
    ACCESS_APPEND
} DeviceAccessMode;

#define IS_WRITABLE_ACCESS_MODE(mode) ((mode) == ACCESS_WRITE || \
                                       (mode) == ACCESS_APPEND)

/* Device object definition follows. */

/*
 * Type checking and casting macros
 */
#define TYPE_DEVICE	(device_get_type())
#define DEVICE(obj)	G_TYPE_CHECK_INSTANCE_CAST((obj), device_get_type(), Device)
#define DEVICE_CONST(obj)	G_TYPE_CHECK_INSTANCE_CAST((obj), device_get_type(), Device const)
#define DEVICE_CLASS(klass)	G_TYPE_CHECK_CLASS_CAST((klass), device_get_type(), DeviceClass)
#define IS_DEVICE(obj)	G_TYPE_CHECK_INSTANCE_TYPE((obj), device_get_type ())

#define DEVICE_GET_CLASS(obj)	G_TYPE_INSTANCE_GET_CLASS((obj), device_get_type(), DeviceClass)

typedef struct DevicePrivate_s DevicePrivate;

/*
 * Main object structure
 */
typedef struct {
    GObject __parent__;

    /* You can peek at the stuff below, but only subclasses should
       change these values.*/

    /* What file, block are we at? (and are we in the middle of a
     * file?) This is automatically updated by
     * the default implementations of start_file, finish_file,
     * write_block, read_block, seek_file, and seek_block. */
    int file;
    guint64 block;
    gboolean in_file;
    /* Holds the user-specified device name. */
    char * device_name;
    /* Holds the user-specified access-mode. */
    DeviceAccessMode access_mode;
    /* In reading mode, FALSE unless all the data from the current file
     * was successfully read. */
    gboolean is_eof;
    /* Holds the label and time of the currently-inserted volume,
     * or NULL if it has not been read/written yet. */
    char * volume_label;
    char * volume_time;

    DevicePrivate * private;
} Device;

/* Pointer to factory function for device types. The factory functions
   take control of their arguments, which should be dynamically
   allocated. The factory should call open_device() with this
   device_name. */
typedef Device* (*DeviceFactory)(char * device_type,
                                 char * device_name);

/* This function registers a new device with the allocation system.
 * Call it after you register your type with the GLib type system.
 * This function takes ownership of the strings inside device_prefix_list,
 * but not the device_prefix_list itself. */
extern void register_device(DeviceFactory factory,
                            const char ** device_prefix_list);

/* This structure is a Flags (bitwise OR of values). Zero indicates success;
 * any other value indicates some kind of problem reading the label. If
 * multiple bits are set, it does not necessarily indicate that /all/ of
 * the specified issues occured, but rather that /at least one/ did. */
typedef enum {
    /* When changing, Also update read_label_status_flags_values in device.c */
    READ_LABEL_STATUS_SUCCESS          = 0,
    READ_LABEL_STATUS_DEVICE_MISSING   = (1 << 0),
    READ_LABEL_STATUS_DEVICE_ERROR     = (1 << 1),
    READ_LABEL_STATUS_VOLUME_MISSING   = (1 << 2),
    READ_LABEL_STATUS_VOLUME_UNLABELED = (1 << 3),
    READ_LABEL_STATUS_VOLUME_ERROR     = (1 << 4),
    READ_LABEL_STATUS_FLAGS_MAX              = (1 << 5)
} ReadLabelStatusFlags;

#define READ_LABEL_STATUS_FLAGS_MASK (READ_LABEL_STATUS_MAX-1)
#define READ_LABEL_STATUS_FLAGS_TYPE (read_label_status_flags_get_type())
GType read_label_status_flags_get_type(void);

/*
 * Class definition
 */
typedef struct _DeviceClass DeviceClass;
struct _DeviceClass {
    GObjectClass __parent__;
    gboolean (* open_device) (Device * self,
                              char * device_name); /* protected */
    ReadLabelStatusFlags (* read_label)(Device * self);
    gboolean (* start) (Device * self, DeviceAccessMode mode,
                        char * label, char * timestamp);
    gboolean (* start_file) (Device * self, const dumpfile_t * info);
    gboolean (* write_block) (Device * self, guint size, gpointer data,
                              gboolean last_block);
    gboolean (* write_from_fd) (Device * self, int fd);
    gboolean (* finish_file) (Device * self);
    dumpfile_t* (* seek_file) (Device * self, guint file);
    gboolean (* seek_block) (Device * self, guint64 block);
    gboolean (* read_block) (Device * self, gpointer buf, int * size);
    gboolean (* read_to_fd) (Device * self, int fd);
    gboolean (* property_get) (Device * self, DevicePropertyId id,
                               GValue * val);
    gboolean (* property_set) (Device * self, DevicePropertyId id,
                               GValue * val);
    gboolean (* recycle_file) (Device * self, guint filenum);
    gboolean (* finish) (Device * self);
};


/*
 * Public methods
 *
 * Note to implementors: The default implementation of many of these
 * methods does not follow the documentation. For example, the default
 * implementation of device_read_block will always return -1, but
 * nonetheless update the block index in the Device structure. In
 * general, it is OK to chain up to the default implmentation after
 * successfully implementing whatever appears below. The particulars
 * of what the default implementations do is documented in device.c.
 */
GType	device_get_type	(void);

/* This is how you get a new Device. Pass in a device name like
 * file:/path/to/storage, and (assuming everything goes OK) you will get
 * back a nice happy Device* that you can do operations on. Note that you
 * must device_start() it before you can do anything besides talk about
 * properties or read the label. device_name remains the responsibility
 * of the caller. */
Device* 	device_open	(char * device_name);

/* This instructs the device to read the label on the current
 * volume. device->volume_label will not be initalized until after this
 * is called. You are encouraged to read the label only after setting any
 * properties that may affect the label-reading process. */
ReadLabelStatusFlags        device_read_label (Device * self);

/* This tells the Device that it's OK to start reading and writing
 * data. Before you call this, you can only call
 * device_property_{get, set} and device_read_label. You can only call
 * this a second time if you call device_finish() first.
 *
 * You should pass a label and timestamp if and only if you are
 * opening in WRITE mode (not READ or APPEND). The label and timestamp
 * remain the caller's responsibility in terms of memory management. The