generator: Optional arguments, add-drive-opts (RHBZ#642934,CVE-2010-3851).

This large commit changes the generator so that optional arguments
can be supported for functions.

The model for arguments (known as the "style") is changed from
(ret, args) to (ret, args, optargs) where optargs is a more limited
list of arguments.

One function has been added which takes optional arguments, it is
"add-drive-opts", modelled as:

  (RErr, [String "filename"], #required
         [Bool "readonly"; String "format"; String "iface"]) #optional

Note that this function is processed in the library (does not go over
the RPC protocol to the daemon).  This has allowed us to simplify
the current implementation by omitting changes related to RPC or the
daemon, although we plan to add these at some point in the future.

From C this function can be called in 3 different ways as in these
examples:

  guestfs_add_drive_opts (g, filename,
                          GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
			  GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
                          -1);

(the argument(s) between 'filename' and '-1' are the optional ones).

  guestfs_add_drive_opts_va (g, filename, args);

where 'args' is a va_list.  This works like the first version.

  struct guestfs_add_drive_opts_argv optargs = {
    .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK,
    .readonly = 1,
  }
  guestfs_add_drive_opts_argv (g, filename, &optargs);

This last form lets you construct lists of optional arguments, and
is used by guestfish and the language bindings.

In guestfish optional arguments are used like this:

  add-drive-opts filename readonly:true

In OCaml these are mapped naturally to OCaml optional arguments, eg:

  g#add_drive_opts ~readonly:true filename;

In Perl these are mapped to extra arguments, eg:

  $g->add_drive_opts ($filename, readonly => 1);

In Python these are mapped to optional arguments, eg:

  g.add_drive_opts ("file", readonly = 1, format = "qcow2")

In Ruby these are mapped to a final hash argument, eg:

  g.add_drive_opts("file", {})
  g.add_drive_opts("file", :readonly => 1)
  g.add_drive_opts("file", :readonly => 1, :iface => "virtio")

In PHP these are mapped to extra parameters.  This is not quite
accurate since you cannot omit arbitrary optional parameters, but
there's not much than can be done within the limitations of PHP
as a language.

Unimplemented in: Haskell, C#, Java.

1 files changed, 44 insertions, 18 deletions

diff --git a/generator/generator_java.ml b/generator/generator_java.ml
index 2ccb1b6c..b5517408 100644
--- a/generator/generator_java.ml
+++ b/generator/generator_java.ml
@@ -100,10 +100,14 @@ public class GuestFS {
 ";
 
   List.iter (
-    fun (name, style, _, flags, _, shortdesc, longdesc) ->
+    fun (name, (ret, args, optargs as style), _, flags, _, shortdesc, longdesc) ->
       if not (List.mem NotInDocs flags); then (
         let doc = replace_str longdesc "C<guestfs_" "C<g." in
         let doc =
+          if optargs <> [] then
+            doc ^ "\n\nOptional arguments are supplied in the final Map<String,Object> parameter, which is a hash of the argument name to its value (cast to Object).  Pass an empty Map for no optional arguments."
+          else doc in
+        let doc =
           if List.mem ProtocolLimitWarning flags then
             doc ^ "\n\n" ^ protocol_limit_warning
           else doc in
@@ -138,9 +142,9 @@ public class GuestFS {
       pr "      throw new LibGuestFSException (\"%s: handle is closed\");\n"
         name;
       pr "    ";
-      if fst style <> RErr then pr "return ";
+      if ret <> RErr then pr "return ";
       pr "_%s " name;
-      generate_java_call_args ~handle:"g" (snd style);
+      generate_java_call_args ~handle:"g" style;
       pr ";\n";
       pr "  }\n";
       pr "  ";
@@ -152,19 +156,20 @@ public class GuestFS {
   pr "}\n"
 
 (* Generate Java call arguments, eg "(handle, foo, bar)" *)
-and generate_java_call_args ~handle args =
+and generate_java_call_args ~handle (_, args, optargs) =
   pr "(%s" handle;
   List.iter (fun arg -> pr ", %s" (name_of_argt arg)) args;
+  if optargs <> [] then pr ", optargs";
   pr ")"
 
 and generate_java_prototype ?(public=false) ?(privat=false) ?(native=false)
-    ?(semicolon=true) name style =
+    ?(semicolon=true) name (ret, args, optargs) =
   if privat then pr "private ";
   if public then pr "public ";
   if native then pr "native ";
 
   (* return type *)
-  (match fst style with
+  (match ret with
    | RErr -> pr "void ";
    | RInt _ -> pr "int ";
    | RInt64 _ -> pr "long ";
@@ -214,7 +219,13 @@ and generate_java_prototype ?(public=false) ?(privat=false) ?(native=false)
           pr "int %s" n
       | Int64 n ->
           pr "long %s" n
-  ) (snd style);
+  ) args;
+
+  if optargs <> [] then (
+    if !needs_comma then pr ", ";
+    needs_comma := true;
+    pr "HashMap optargs"
+  );
 
   pr ")\n";
   pr "    throws LibGuestFSException";
@@ -299,9 +310,9 @@ Java_com_redhat_et_libguestfs_GuestFS__1close
 ";
 
   List.iter (
-    fun (name, style, _, _, _, _, _) ->
+    fun (name, (ret, args, optargs as style), _, _, _, _, _) ->
       pr "JNIEXPORT ";
-      (match fst style with
+      (match ret with
        | RErr -> pr "void ";
        | RInt _ -> pr "jint ";
        | RInt64 _ -> pr "jlong ";
@@ -338,12 +349,14 @@ Java_com_redhat_et_libguestfs_GuestFS__1close
             pr ", jint j%s" n
         | Int64 n ->
             pr ", jlong j%s" n
-      ) (snd style);
+      ) args;
+      if optargs <> [] then
+        pr ", jobject joptargs";
       pr ")\n";
       pr "{\n";
       pr "  guestfs_h *g = (guestfs_h *) (long) jg;\n";
       let error_code, no_ret =
-        match fst style with
+        match ret with
         | RErr -> pr "  int r;\n"; "-1", ""
         | RBool _
         | RInt _ -> pr "  int r;\n"; "-1", "0"
@@ -397,10 +410,10 @@ Java_com_redhat_et_libguestfs_GuestFS__1close
             pr "  int %s;\n" n
         | Int64 n ->
             pr "  int64_t %s;\n" n
-      ) (snd style);
+      ) args;
 
       let needs_i =
-        (match fst style with
+        (match ret with
          | RStringList _ | RStructList _ -> true
          | RErr | RBool _ | RInt _ | RInt64 _ | RConstString _
          | RConstOptString _
@@ -408,7 +421,7 @@ Java_com_redhat_et_libguestfs_GuestFS__1close
           List.exists (function
                        | StringList _ -> true
                        | DeviceList _ -> true
-                       | _ -> false) (snd style) in
+                       | _ -> false) args in
       if needs_i then
         pr "  size_t i;\n";
 
@@ -445,10 +458,20 @@ Java_com_redhat_et_libguestfs_GuestFS__1close
         | Int n
         | Int64 n ->
             pr "  %s = j%s;\n" n n
-      ) (snd style);
+      ) args;
+
+      if optargs <> [] then (
+        (* XXX *)
+        pr "  throw_exception (env, \"%s: internal error: please let us know how to read a Java HashMap parameter from JNI bindings!\");\n" name;
+        pr "  return NULL;\n";
+        pr "  /*\n";
+      );
 
       (* Make the call. *)
-      pr "  r = guestfs_%s " name;
+      if optargs = [] then
+        pr "  r = guestfs_%s " name
+      else
+        pr "  r = guestfs_%s_argv " name;
       generate_c_call_args ~handle:"g" style;
       pr ";\n";
 
@@ -477,7 +500,7 @@ Java_com_redhat_et_libguestfs_GuestFS__1close
         | Bool n
         | Int n
         | Int64 n -> ()
-      ) (snd style);
+      ) args;
 
       (* Check for errors. *)
       pr "  if (r == %s) {\n" error_code;
@@ -486,7 +509,7 @@ Java_com_redhat_et_libguestfs_GuestFS__1close
       pr "  }\n";
 
       (* Return value. *)
-      (match fst style with
+      (match ret with
        | RErr -> ()
        | RInt _ -> pr "  return (jint) r;\n"
        | RBool _ -> pr "  return (jboolean) r;\n"
@@ -528,6 +551,9 @@ Java_com_redhat_et_libguestfs_GuestFS__1close
            pr "  return jr;\n"
       );
 
+      if optargs <> [] then
+        pr "  */\n";
+
       pr "}\n";
       pr "\n"
   ) all_functions