[pve-devel] [PATCH] Document PVE::Storage::Plugin public methods

[Dmitry Petuhov]

Add comments for base class's methods to be reloaded in custom
storage plugins. Also add comment at end of file with exmaples of methods
that must be in child classes, but not present in base class.

Signed-off-by: Dmitry Petuhov <mityapetuhov at gmail.com>
---
Described returning values where they're matter. Argumeths have self-explainig
names, so did not explained them, except special $size in alloc_image()

 PVE/Storage/Plugin.pm | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/PVE/Storage/Plugin.pm b/PVE/Storage/Plugin.pm
index 6e73547..4bd9ff8 100644
--- a/PVE/Storage/Plugin.pm
+++ b/PVE/Storage/Plugin.pm
@@ -362,6 +362,9 @@ sub parse_name_dir {
     die "unable to parse volume filename '$name'\n";
 }
 
+# public
+# returns array ($vtype, $name, $vmid, $basename, $basedvmid, $isBase, $format)
+# Only first 2 fields are mandatory, others may be undefined if they're meaningless for storage.
 sub parse_volname {
     my ($class, $volname) = @_;
 
@@ -434,12 +437,16 @@ sub filesystem_path {
     return wantarray ? ($path, $vmid, $vtype) : $path;
 }
 
+# public
+# returns $path to image/directory to be passed to qemu/lxc.
 sub path {
     my ($class, $scfg, $volname, $storeid, $snapname) = @_;
 
     return $class->filesystem_path($scfg, $volname, $snapname);
 }
 
+# public, may just die if storage does not supports base image and its cloning.
+# returns name of new volume.
 sub create_base {
     my ($class, $storeid, $scfg, $volname) = @_;
 
@@ -505,6 +512,8 @@ my $find_free_diskname = sub {
     die "unable to allocate a new image name for VM $vmid in '$imgdir'\n";
 };
 
+# public, may just die if storage does not supports base image and its cloning.
+# returns name of new volume.
 sub clone_image {
     my ($class, $scfg, $storeid, $volname, $vmid, $snap) = @_;
 
@@ -551,6 +560,9 @@ sub clone_image {
     return $newvol;
 }
 
+# public
+# returns name of new volume.
+# WARNING: unlike other places, $size here is in kibibytes (bytes*1024)
 sub alloc_image {
     my ($class, $storeid, $scfg, $vmid, $fmt, $name, $size) = @_;
 
@@ -592,6 +604,7 @@ sub alloc_image {
     return "$vmid/$name";
 }
 
+# public
 sub free_image {
     my ($class, $storeid, $scfg, $volname, $isBase, $format) = @_;
 
@@ -658,6 +671,8 @@ sub file_size_info {
     return wantarray ? ($size, $format, $used, $parent) : $size;
 }
 
+# public
+# returns wantarray ? ($size, $format, $used, $parent) : $size; in bytes.
 sub volume_size_info {
     my ($class, $scfg, $storeid, $volname, $timeout) = @_;
     my $path = $class->filesystem_path($scfg, $volname);
@@ -665,6 +680,9 @@ sub volume_size_info {
 
 }
 
+# public, may just die if storage does not support image resizing.
+# returns true if $running and qemu shall resize image itself, or false
+# if volume has been resized and need just to notify qemu about it.
 sub volume_resize {
     my ($class, $scfg, $storeid, $volname, $size, $running) = @_;
 
@@ -683,6 +701,7 @@ sub volume_resize {
     return undef;
 }
 
+# public, may just die if storage does not support snapshots.
 sub volume_snapshot {
     my ($class, $scfg, $storeid, $volname, $snap) = @_;
 
@@ -697,12 +716,15 @@ sub volume_snapshot {
     return undef;
 }
 
+# public
+# returns true if volume can be rolled back to specified snapshot, false otherwise
 sub volume_rollback_is_possible {
     my ($class, $scfg, $storeid, $volname, $snap) = @_; 
 
     return 1; 
 }
 
+# public, may just die if storage does not support snapshots.
 sub volume_snapshot_rollback {
     my ($class, $scfg, $storeid, $volname, $snap) = @_;
 
@@ -717,6 +739,7 @@ sub volume_snapshot_rollback {
     return undef;
 }
 
+# public, may just die if storage does not support snapshots.
 sub volume_snapshot_delete {
     my ($class, $scfg, $storeid, $volname, $snap, $running) = @_;
 
@@ -735,6 +758,8 @@ sub volume_snapshot_delete {
     return undef;
 }
 
+# public, return true if $feature is supported on $volname/$snapname.
+# current features: snapshot clone template copy sparseinit
 sub volume_has_feature {
     my ($class, $scfg, $feature, $storeid, $volname, $snapname, $running) = @_;
 
@@ -764,6 +789,11 @@ sub volume_has_feature {
     return undef;
 }
 
+# public
+# returns reference to array of hashrefs
+# $ref->[]->{volid, format, size, vmid, used, parent}
+# 'size' and 'used' in byes; 'parent' is optional (for storages that
+# support cloning).
 sub list_images {
     my ($class, $storeid, $scfg, $vmid, $vollist, $cache) = @_;
 
@@ -809,6 +839,8 @@ sub list_images {
     return $res;
 }
 
+# public
+# returns list of storage space in bytes and status ($total, $avail, $used, $active)
 sub status {
     my ($class, $storeid, $scfg, $cache) = @_;
 
@@ -824,6 +856,7 @@ sub status {
     return ($res->{total}, $res->{avail}, $res->{used}, 1);
 }
 
+# public
 sub activate_storage {
     my ($class, $storeid, $scfg, $cache) = @_;
 
@@ -848,12 +881,14 @@ sub activate_storage {
     }
 }
 
+# public
 sub deactivate_storage {
     my ($class, $storeid, $scfg, $cache) = @_;
 
     # do nothing by default
 }
 
+# public
 sub activate_volume {
     my ($class, $storeid, $scfg, $volname, $snapname, $cache) = @_;
 
@@ -867,17 +902,82 @@ sub activate_volume {
     }
 }
 
+# public
 sub deactivate_volume {
     my ($class, $storeid, $scfg, $volname, $snapname, $cache) = @_;
 
     # do nothing by default
 }
 
+# public
 sub check_connection {
     my ($class, $storeid, $scfg) = @_;
     # do nothing by default
     return 1;
 }
 
+# Additional public functions for custom plugins
+# Here are just examples, actual contents of these functions depends
+# on your plugin.
+
+# Must return API version, for which module designed
+# see /usr/share/perl5/PVE/Storage.pm APIVER constant for current value.
+#sub api {
+#    return 1;
+#}
+
+# Storage type name. Will be used in storage configuration.
+#sub type {
+#    return 'mystor';
+#}
+
+# List of supported volume content types ($vtype) and formats.
+# 2nd value in each array is suggested default.
+#sub plugindata {
+#    return {
+#	content => [ { images => 1, vztmpl => 1, iso => 1, backup => 1},
+#		     { images => 1 }],
+#	format => [ { raw => 1, qcow2 => 1, vmdk => 1 } , 'raw' ],
+#    };
+#}
+
+# returns hashref to deifinions of additional config options for plugin
+# For every option keys 'description' and 'type' are mandatory. Others may
+# present if needed.
+#sub properties {
+#    return {
+#	adminserver => {
+#	    description => "Management IP or DNS name of storage.",
+#	    type => 'string',
+#	    format => 'pve-storage-server',
+#	},
+#	login => {
+#	    description => "login",
+#	    type => 'string',
+#	},
+#	media => {
+#	    description => "iscsi/multipath",
+#	    type => 'string',
+#	    default => 'multipath',
+#	    enum => ['iscsi', 'multipath'],
+#	},
+#    };
+#}
+
+# returns hashref of options thay must/may present in config
+# file /etc/pve/storage.cfg
+# here must present options from sub properties() above, plus may be some
+# standard options from $defaultData->{propertyList}.
+#sub options {
+#    return {
+#	adminserver => { fixed => 1 },
+#	login => { fixed => 1 },
+#	nodes => { optional => 1 },
+#	disable => { optional => 1 },
+#	content => { optional => 1 },
+#	media => { optional => 1 },
+#	shared => { optional => 1 },
+#    }
+#}
 
 1;
-- 
2.1.4