Libguestfs - Jul 2020 - [PATCH nbdkit] PROPOSED: server: Implement list_exports.

See also:
https://www.redhat.com/archives/libguestfs/2020-July/msg00090.html
---
 docs/nbdkit-plugin.pod   | 49 ++++++++++++++++++++++++++++++++++++----
 docs/nbdkit-protocol.pod |  7 ++++--
 2 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod
index f8e9962a..6553d186 100644
--- a/docs/nbdkit-plugin.pod
+++ b/docs/nbdkit-plugin.pod
@@ -152,6 +152,9 @@ the plugin:
  │ preconnect │                  │
  └──────┬─────┘                  │
  ┌──────┴─────┐                  │
+ │list_exports│                  │
+ └──────┬─────┘                  │
+ ┌──────┴─────┐                  │
  │ open       │                  │
  └──────┬─────┘                  │
  ┌──────┴─────┐  NBD option      │
@@ -160,10 +163,10 @@ the plugin:
  ┌──────┴─────┐           ┌──────┴─────┐ client #2
  │ get_size   │           │ preconnect │
  └──────┬─────┘           └──────┬─────┘
- ┌──────┴─────┐ data      ┌──────┴─────┐
- │ pread      │ serving   │ open       │
- └──────┬─────┘↺          └──────┬─────┘
- ┌──────┴─────┐                 ...
+ ┌──────┴─────┐ data
+ │ pread      │ serving
+ └──────┬─────┘↺                ...
+ ┌──────┴─────┐
  │ pwrite     │
  └──────┬─────┘↺          ┌──────┴─────┐
  ┌──────┴─────┐           │ close      │
@@ -236,6 +239,12 @@ L<getpid(2)>.
 Called when a TCP connection has been made to the server.  This
 happens early, before NBD or TLS negotiation.
 
+=item C<.list_exports>
+
+Early in option negotiation the client may try to list the exports
+served by the plugin, and plugins can optionally implement this
+callback to answer the client.  See L</EXPORT NAME> below.
+
 =item C<.open>
 
 A new client has connected and finished the NBD handshake.  TLS
@@ -652,6 +661,38 @@ Returning C<0> will allow the connection to continue.
If there is an
 error or you want to deny the connection, call C<nbdkit_error> with an
 error message and return C<-1>.
 
+=head2 C<.list_exports>
+
+ int list_exports (int readonly, struct nbdkit_exports *exports);
+
+This optional callback is called if the client tries to list the
+exports served by the plugin (using C<NBD_OPT_LIST>).  If the plugin
+does not supply this callback then a single export called C<"">
is
+returned.  The NBD protocol defines C<""> as the default
export, so
+this is suitable for plugins which ignore the export name and always
+serve the same content.  See also L</EXPORT NAME> below.
+
+The C<exports> parameter is an opaque object for collecting the list
+of exports.  Call C<nbdkit_add_export> to add a single export to the
+list:
+
+ int nbdkit_add_export (struct nbdkit_export *exports,
+                        const char *name, const char *description);
+
+The C<name> must be a non-NULL, UTF-8 string no longer than 4096
+bytes.  C<description> is an optional description of the export which
+some clients can display but which is otherwise unused (if you don't
+want a description, you can pass this parameter as C<NULL>).  The
+string(s) are copied into the exports list so you may free them
+immediately after calling this function.
+
+The C<readonly> flag informs the plugin that the server was started
+with the I<-r> flag on the command line.
+
+Returning C<0> will send the list of exports back to the client.  If
+there is an error, C<.list_exports> should call C<nbdkit_error>
with
+an error message and return C<-1>.
+
 =head2 C<.open>
 
  void *open (int readonly);
diff --git a/docs/nbdkit-protocol.pod b/docs/nbdkit-protocol.pod
index e0e4042b..39b9481a 100644
--- a/docs/nbdkit-protocol.pod
+++ b/docs/nbdkit-protocol.pod
@@ -99,12 +99,15 @@ Supported in nbdkit E<ge> 1.1.12, and the default in
nbdkit E<ge> 1.3.
 =item export names
 
 Partially supported in nbdkit E<ge> 1.1.12.  Support for plugins to
-read the client export name added in nbdkit E<ge> 1.15.2.
+read the client export name added in nbdkit E<ge> 1.15.2.  Support for
+C<NBD_OPT_LIST> was added in nbdkit E<ge> 1.21.20.
 
 Versions of nbdkit before 1.16 could advertise a single export name to
 clients, specified through the now deprecated I<-e> option.  In nbdkit
 1.15.2, plugins could read the client requested export name using
-C<nbdkit_export_name()> and serve different content.
+C<nbdkit_export_name()> and serve different content.  In nbdkit
+1.21.20, plugins could implement C<.list_exports> to answer
+C<NBD_OPT_LIST> queries.
 
 =item C<NBD_FLAG_NO_ZEROES>
 
-- 
2.27.0