Libguestfs - Nov 2009 - [PATCH FOR DISCUSSION ONLY] availability: Add guestfs_available.

For discussion only.

FWIW we have a similar API in libvirt, although in libvirt it's an
internal-only API.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
New in Fedora 11: Fedora Windows cross-compiler. Compile Windows
programs, test, and build Windows installers. Over 70 libraries supprt'd
http://fedoraproject.org/wiki/MinGW http://www.annexia.org/fedora_mingw
-------------- next part --------------
>From c19ed5ee7ef8a818b7bdf737e6651b30ab700e66 Mon Sep 17 00:00:00 2001
From: Richard Jones <rjones at redhat.com>
Date: Fri, 20 Nov 2009 13:06:49 +0000
Subject: [PATCH] availability: Add guestfs_available.

Start a new API allowing groups of functions to be tested for
availability.

There are two reasons for this:

(1) If libguestfs is built with missing dependencies (eg. no Augeas lib)
then the corresponding functions are disabled in the appliance.  Up till
now there has been no way to test for this except to speculatively
issue commands and check for errors.

(2) When we port the daemon to Win32 it is likely that major pieces of
functionality won't be available (eg. LVM support).  This API gives
a way to test for that.

There is no change for existing clients: you still have to check for
errors from individual API calls.

For new clients, you will be able to test for availability of particular
APIs.

Usage scenario (A): A partition + LVM editing tool which requires
both the partition API and the LVM API in order to function at all:

  char *apis[] = { "part", "lvm2", NULL };
  r = guestfs_available (g, apis);
  if (r == -1) {
    /* print an error and exit */
  }

Usage scenario (B): A general purpose tool which optionally provides
configuration file editing, but this can be disabled, the result
merely being reduced functionality:

  char *apis[] = { "augeas", NULL };
  r = guestfs_available (g, apis);
  enable_config_edit_menus = r == 0;
---
 daemon/Makefile.am |    1 +
 daemon/available.c |   38 ++++++++++++++++++++++++++++++++++++++
 po/POTFILES.in     |    1 +
 src/MAX_PROC_NR    |    2 +-
 src/generator.ml   |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 87 insertions(+), 1 deletions(-)
 create mode 100644 daemon/available.c

diff --git a/daemon/Makefile.am b/daemon/Makefile.am
index 1716c2f..d851e52 100644
--- a/daemon/Makefile.am
+++ b/daemon/Makefile.am
@@ -41,6 +41,7 @@ $(libsrcdir)/guestfs_protocol.o: force
 noinst_PROGRAMS = guestfsd
 guestfsd_SOURCES = \
 	actions.h \
+	available.c \
 	augeas.c \
 	blkid.c \
 	blockdev.c \
diff --git a/daemon/available.c b/daemon/available.c
new file mode 100644
index 0000000..b43d182
--- /dev/null
+++ b/daemon/available.c
@@ -0,0 +1,38 @@
+/* libguestfs - the guestfsd daemon
+ * Copyright (C) 2009 Red Hat Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program 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 General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#include <config.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "../src/guestfs_protocol.h"
+#include "daemon.h"
+#include "actions.h"
+
+int
+do_available (char *const *groups)
+{
+  if (groups[0] != NULL) {
+    reply_with_error ("%s: unknown group", groups[0]);
+    return -1;
+  }
+
+  return 0;
+}
diff --git a/po/POTFILES.in b/po/POTFILES.in
index cf632fc..2c7998d 100644
--- a/po/POTFILES.in
+++ b/po/POTFILES.in
@@ -1,4 +1,5 @@
 daemon/augeas.c
+daemon/available.c
 daemon/blkid.c
 daemon/blockdev.c
 daemon/checksum.c
diff --git a/src/MAX_PROC_NR b/src/MAX_PROC_NR
index c34a804..a817176 100644
--- a/src/MAX_PROC_NR
+++ b/src/MAX_PROC_NR
@@ -1 +1 @@
-215
+216
diff --git a/src/generator.ml b/src/generator.ml
index 6bc9b28..def9f8c 100755
--- a/src/generator.ml
+++ b/src/generator.ml
@@ -4102,6 +4102,52 @@ must be a number in the range C<[0..255]>.
 To fill a file with zero bytes (sparsely), it is
 much more efficient to use C<guestfs_truncate_size>.");
 
+  ("available", (RErr, [StringList "groups"]), 216, [],
+   [],
+   "test availability of some parts of the API",
+   "\
+This command is used to check the availability of some
+groups of libguestfs functions which not all builds of
+libguestfs will be able to provide.
+
+The precise libguestfs function groups that may be checked by this
+command are listed in L<guestfs(3)/AVAILABILITY>.
+
+The argument C<groups> is a list of API group names, eg:
+C<[\"inotify\", \"part\"]> would check for the
availability of
+the C<guestfs_inotify_*> functions and C<guestfs_part_*>
+(partition editing) functions.
+
+The command returns no error if I<all> requested groups are available.
+
+It returns an error if one or more of the requested
+groups is unavailable.
+
+If an unknown group name is included in the
+list of C<groups> then an error is always returned.
+
+I<Notes:>
+
+You must call C<guestfs_launch> before calling this function.
+The reason is because we don't know what function groups are
+supported by the appliance/daemon until it is running and can
+be queried.
+
+If a group of functions is available, this does not necessarily
+mean that they will work.  You still have to check for errors
+when calling individual API functions even if they are
+available.
+
+It is usually the job of distro packagers to build
+complete functionality into the libguestfs appliance.
+Upstream libguestfs, if built from source with all
+requirements satisfied, will support everything.
+
+This call was added in version C<1.0.80>.  In previous
+versions of libguestfs all you could do would be to speculatively
+execute a command to find out if the daemon implemented it.
+See also C<guestfs_version>.");
+
 ]
 
 let all_functions = non_daemon_functions @ daemon_functions
-- 
1.6.5.2