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): An LVM editing tool which requires
both the LVM API and inotify in order to function at all:

  char *apis[] = { "inotify", "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;

diff --git a/daemon/Makefile.am b/daemon/Makefile.am
index 1716c2f..d851e52 100644 (file)
--- 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 (file)
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 (file)
--- 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 (file)
--- 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..cceb191 100755 (executable)
--- a/src/generator.ml
+++ b/src/generator.ml
@@ -758,7 +758,8 @@ To construct the original version string:
 C<$major.$minor.$release$extra>
 
 I<Note:> Don't use this call to test for availability
-of features.  Distro backports makes this unreliable.");
+of features.  Distro backports makes this unreliable.  Use
+C<guestfs_available> instead.");
 
   ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"],
    [InitNone, Always, TestOutputTrue (
@@ -4102,6 +4103,64 @@ 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:>
+
+=over 4
+
+=item *
+
+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.
+
+=item *
+
+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.
+
+=item *
+
+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.
+
+=item *
+
+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>.
+
+=back");
+
 ]
 
 let all_functions = non_daemon_functions @ daemon_functions