Changeset 94181 in vbox for trunk

Timestamp:

Mar 11, 2022 4:55:03 PM (3 years ago)

Author:

vboxsync

Message:

doc/manual,FE/VBoxManage: Convert bandwidthctl command to refentry documentation, bugref:9186

Location:

trunk

Files:

• doc/manual/Config.kmk (modified) (1 diff)
• doc/manual/en_US/man_VBoxManage-bandwidthctl.xml (modified) (2 diffs)
• doc/manual/en_US/user_VBoxManage.xml (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManage.cpp (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManage.h (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManageBandwidthControl.cpp (modified) (9 diffs)
• src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp (modified) (1 diff)

trunk/doc/manual/Config.kmk

@@ -65 +65 @@
         man_VBoxManage-adoptstate.xml \
         man_VBoxManage-closemedium.xml \
-        man_VBoxManage-storagectl.xml
+        man_VBoxManage-storagectl.xml \
+        man_VBoxManage-bandwidthctl.xml
 
 ## List of user manual XML files.

trunk/doc/manual/en_US/man_VBoxManage-bandwidthctl.xml

@@ -20 +20 @@
 <refentry id="vboxmanage-bandwidthctl" lang="en">
   <refentryinfo>
-    <pubdate>September 2019</pubdate>
+    <pubdate>$Date$</pubdate>
     <title>VBoxManage bandwidthctl</title>
   </refentryinfo>
@@ -32 +32 @@
     <refname>VBoxManage-bandwidthctl</refname>
     <refpurpose>manage bandwidth groups</refpurpose>
-    <refclass>Oracle VM VirtualBox</refclass>
+    <refclass>&product-name;</refclass>
   </refnamediv>
 

trunk/doc/manual/en_US/user_VBoxManage.xml

@@ -927 +927 @@
   <xi:include href="user_man_VBoxManage-storagectl.xml"    xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <sect1 id="vboxmanage-bandwidthctl">
-
-    <title>VBoxManage bandwidthctl</title>
-
-    <para>
-      This command creates, deletes, modifies, and shows bandwidth
-      groups of the given virtual machine.
-    </para>
-
-<screen>VBoxManage bandwidthctl    &lt;uuid|vmname&gt;
-                           add &lt;name&gt; --type disk|network --limit &lt;MBps&gt;[k|m|g|K|M|G] |
-                           set &lt;name&gt; --limit &lt;MBps&gt;[k|m|g|K|M|G] |
-                           remove &lt;name&gt; |
-                           list [--machinereadable]</screen>
-
-    <para>
-      The following subcommands are available:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          <command>add</command>: Creates a new bandwidth group of a
-          given type.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <command>set</command>: Modifies the limit for an existing
-          bandwidth group.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <command>remove</command>: Deletes a bandwidth group.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <command>list</command>: Shows all bandwidth groups defined
-          for the given VM. Use the
-          <computeroutput>--machinereadable</computeroutput> option to
-          produce the same output, but in machine readable format. This
-          is of the form: name="value" on a line by line basis.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-    <para>
-      The parameters are as follows:
-    </para>
-
-    <variablelist>
-
-      <varlistentry>
-        <term>
-          <computeroutput>uuid|vmname</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            The VM UUID or VM Name. Mandatory.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--name</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Name of the bandwidth group. Mandatory.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--type</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Type of the bandwidth group. Mandatory. Two types are
-            supported: <computeroutput>disk</computeroutput> and
-            <computeroutput>network</computeroutput>. See
-            <xref linkend="storage-bandwidth-limit" /> or
-            <xref linkend="network_bandwidth_limit" /> for the
-            description of a particular type.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--limit</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Specifies the limit for the given bandwidth group. This can
-            be changed while the VM is running. The default unit is
-            megabytes per second. The unit can be changed by specifying
-            one of the following suffixes:
-            <computeroutput>k</computeroutput> for kilobits per second,
-            <computeroutput>m</computeroutput> for megabits per second,
-            <computeroutput>g</computeroutput> for gigabits per second,
-            <computeroutput>K</computeroutput> for kilobytes per second,
-            <computeroutput>M</computeroutput> for megabytes per second,
-            <computeroutput>G</computeroutput> for gigabytes per second.
-          </para>
-        </listitem>
-      </varlistentry>
-
-    </variablelist>
-
-    <note>
-      <para>
-        The network bandwidth limits apply only to the traffic being
-        sent by virtual machines. The traffic being received by VMs is
-        unlimited.
-      </para>
-    </note>
-
-    <note>
-      <para>
-        To remove a bandwidth group it must not be referenced by any
-        disks or adapters in the running VM.
-      </para>
-    </note>
-
-  </sect1>
+  <xi:include href="user_man_VBoxManage-bandwidthctl.xml"  xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <sect1 id="vboxmanage-showmediuminfo">

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp

@@ -252 +252 @@
 #endif
     { "extpack",            USAGE_S_NEWCMD,      HELP_CMD_EXTPACK, handleExtPack,              0 },
-    { "bandwidthctl",       USAGE_BANDWIDTHCONTROL, VBMG_CMD_TODO, handleBandwidthControl,     0 },
+    { "bandwidthctl",       USAGE_S_NEWCMD, HELP_CMD_BANDWIDTHCTL, handleBandwidthControl,     0 },
     { "debugvm",            USAGE_S_NEWCMD,      HELP_CMD_DEBUGVM, handleDebugVM,              0 },
     { "convertfromraw",     USAGE_CONVERTFROMRAW,   VBMG_CMD_TODO, handleConvertFromRaw,       VBMG_CMD_F_NO_COM },

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.h

@@ -132 +132 @@
     USAGE_I_SETHDPARENTUUID,
     USAGE_I_PASSWORDHASH,
-    USAGE_BANDWIDTHCONTROL,
     USAGE_I_GUESTSTATS,
     USAGE_I_REPAIRHD,

trunk/src/VBox/Frontends/VBoxManage/VBoxManageBandwidthControl.cpp

@@ -109 +109 @@
         };
 
+    setCurrentSubcommand(HELP_SCOPE_BANDWIDTHCTL_ADD);
 
     Bstr name(a->argv[2]);
@@ -158 +159 @@
             default:
             {
-                errorGetOpt(USAGE_BANDWIDTHCONTROL, c, &ValueUnion);
+                errorGetOpt(c, &ValueUnion);
                 rc = E_FAIL;
                 break;
@@ -196 +197 @@
         };
 
+    setCurrentSubcommand(HELP_SCOPE_BANDWIDTHCTL_SET);
 
     Bstr name(a->argv[2]);
@@ -229 +231 @@
             default:
             {
-                errorGetOpt(USAGE_BANDWIDTHCONTROL, c, &ValueUnion);
+                errorGetOpt(c, &ValueUnion);
                 rc = E_FAIL;
                 break;
@@ -258 +260 @@
 static RTEXITCODE handleBandwidthControlRemove(HandlerArg *a, ComPtr<IBandwidthControl> &bwCtrl)
 {
+    setCurrentSubcommand(HELP_SCOPE_BANDWIDTHCTL_REMOVE);
+
     Bstr name(a->argv[2]);
     CHECK_ERROR2I_RET(bwCtrl, DeleteBandwidthGroup(name.raw()), RTEXITCODE_FAILURE);
@@ -276 +280 @@
     };
 
+    setCurrentSubcommand(HELP_SCOPE_BANDWIDTHCTL_LIST);
     VMINFO_DETAILS enmDetails = VMINFO_STANDARD;
 
@@ -290 +295 @@
                 break;
             default:
-                return errorGetOpt(USAGE_BANDWIDTHCONTROL, c, &ValueUnion);
+                return errorGetOpt(c, &ValueUnion);
         }
     }
@@ -313 +318 @@
 
     if (a->argc < 2)
-        return errorSyntax(USAGE_BANDWIDTHCONTROL, BWControl::tr("Too few parameters"));
+        return errorSyntax(BWControl::tr("Too few parameters"));
     else if (a->argc > 7)
-        return errorSyntax(USAGE_BANDWIDTHCONTROL, BWControl::tr("Too many parameters"));
+        return errorSyntax(BWControl::tr("Too many parameters"));
 
     /* try to find the given machine */
@@ -356 +361 @@
     else
     {
-        errorSyntax(USAGE_BANDWIDTHCONTROL, BWControl::tr("Invalid parameter '%s'"), a->argv[1]);
+        errorSyntax(BWControl::tr("Invalid parameter '%s'"), a->argv[1]);
         rc = E_FAIL;
     }

trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp

@@ -625 +625 @@
                      "\n", SEP);
 
-    if (enmCommand == USAGE_BANDWIDTHCONTROL || enmCommand == USAGE_S_ALL)
-        RTStrmPrintf(pStrm,
-                           "%s bandwidthctl %s    <uuid|vmname>\n"
-                     "                            add <name> --type disk|network\n"
-                     "                                --limit <megabytes per second>[k|m|g|K|M|G] |\n"
-                     "                            set <name>\n"
-                     "                                --limit <megabytes per second>[k|m|g|K|M|G] |\n"
-                     "                            remove <name> |\n"
-                     "                            list [--machinereadable]\n"
-                     "                            (limit units: k=kilobit, m=megabit, g=gigabit,\n"
-                     "                                          K=kilobyte, M=megabyte, G=gigabyte)\n"
-                     "\n", SEP);
-
     if (enmCommand == USAGE_SHOWMEDIUMINFO || enmCommand == USAGE_S_ALL)
         RTStrmPrintf(pStrm,