VirtualBox

Changeset 33456 in vbox for trunk


Ignore:
Timestamp:
Oct 26, 2010 10:51:02 AM (14 years ago)
Author:
vboxsync
Message:

VBoxManage: remove openmedium command which no longer does anything useful; storageattach with medium path works fine; documentation

Location:
trunk
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/en_US/user_VBoxManage.xml

    r33386 r33456  
    103103
    104104        <para>For details, see <xref linkend="vboxmanage-modifyvm" />.</para>
     105      </listitem>
     106
     107      <listitem>
     108        <para>To change the storage configuration (e.g. to add a storage
     109        controller and then a virtual disk), use <computeroutput>VBoxManage
     110        storagectl</computeroutput> and <computeroutput>VBoxManage
     111        storageattach</computeroutput>; see <xref
     112        linkend="vboxmanage-storage" /> for details.</para>
    105113      </listitem>
    106114
    … …  
    493501
    494502          <listitem>
    495             <para><computeroutput>--hwvirtex on|off</computeroutput>:
    496             This enables or disables the use of hardware virtualization
    497             extensions (Intel VT-x or AMD-V) in the processor of your host
    498             system; see <xref linkend="hwvirt" />.</para>
     503            <para><computeroutput>--hwvirtex on|off</computeroutput>: This
     504            enables or disables the use of hardware virtualization extensions
     505            (Intel VT-x or AMD-V) in the processor of your host system; see
     506            <xref linkend="hwvirt" />.</para>
    499507          </listitem>
    500508
    … …  
    13941402  </sect1>
    13951403
    1396   <sect1 id="vboxmanage-registerimage">
    1397     <title>VBoxManage openmedium / closemedium</title>
    1398 
    1399     <para>These commands register or unregister hard disk, DVD or floppy
    1400     images in VirtualBox. This is the command-line equivalent of the Virtual
    1401     Media Manager; see <xref linkend="vdis" /> for more information.<note>
    1402         <para>For compatibility with earlier versions of VirtualBox, the
    1403         "registerimage" and "unregisterimage" commands are also supported and
    1404         mapped internally to the "openmedium" and "closemedium" commands,
    1405         respectively.</para>
    1406       </note></para>
    1407 
    1408     <para>When you register an images you can optionally specify a new UUID
    1409     for the image. For hard disk images the parent UUID can be changed as
    1410     well. You can also specify the type of the medium, see <xref
    1411     linkend="hdimagewrites" /> for details.</para>
    1412 
    1413     <para>When you unregister an image, you can optionally specify that the
    1414     image should be deleted. You will get appropriate diagnostics that the
    1415     deletion failed, however the image will become unregistered in any
    1416     case.</para>
    1417   </sect1>
    1418 
    14191404  <sect1 id="vboxmanage-storage">
    14201405    <title>VBoxManage storagectl / storageattach</title>
    … …  
    15851570
    15861571            <glossdef>
    1587               <para>Allows to specify if the DVD/Floppy drive or Harddisk is
    1588               to be completely detached (none) or just an empty DVD/Floppy
    1589               drive needs to be attached (emptydrive). If uuid, filename or
    1590               host:&lt;drive&gt; is specified then it is attached to the
    1591               storage controller at the specified port and device
    1592               number.</para>
     1572              <para>Specifies what is to be attached. The following values are
     1573              supported:<itemizedlist>
     1574                  <listitem>
     1575                    <para>"none": Any existing device should be removed from
     1576                    the given slot.</para>
     1577
     1578                    <note>
     1579                      <para>DVD/floppy drives or harddisks cannot be removed
     1580                      while the VM is running.</para>
     1581                    </note>
     1582                  </listitem>
     1583
     1584                  <listitem>
     1585                    <para>"emptydrive": This is only allowed if the given slot
     1586                    is a DVD or floppy drive. In this case, the slot behaves
     1587                    like a removeable drive into which no media has been
     1588                    inserted.</para>
     1589                  </listitem>
     1590
     1591                  <listitem>
     1592                    <para>If a UUID is specified, it must be the UUID of a
     1593                    storage medium that is already known to VirtualBox (e.g.
     1594                    because it has been attached to another virtual machine).
     1595                    This medium is then attached to the given device
     1596                    slot.</para>
     1597                  </listitem>
     1598
     1599                  <listitem>
     1600                    <para>If a filename is specified, it must be the full path
     1601                    of an existing disk image (ISO, RAW, VDI, VMDK or other),
     1602                    which is then attached to the given device slot.</para>
     1603                  </listitem>
     1604
     1605                  <listitem>
     1606                    <para>"host:&lt;drive&gt;: This is only allowed if the
     1607                    given slot is a DVD or floppy drive, in which case the
     1608                    device slot is attached to the specified DVD or floppy
     1609                    drive on the host computer.</para>
     1610                  </listitem>
     1611                </itemizedlist></para>
    15931612            </glossdef>
    15941613          </glossentry>
    … …  
    16131632          </glossentry>
    16141633        </glosslist></para>
    1615 
    1616       <note>
    1617         <para>The option "--medium none" doesn't work when the VM is running
    1618         because you can't remove DVD/Floppy Drives or Harddisks when the VM is
    1619         running.</para>
    1620       </note>
    16211634    </sect2>
    16221635  </sect1>
    … …  
    19481961  </sect1>
    19491962
     1963  <sect1 id="vboxmanage-closemedium">
     1964    <title>VBoxManage closemedium</title>
     1965
     1966    <para>This commands removes a hard disk, DVD or floppy image from a
     1967    VirtualBox media registry.<footnote>
     1968        <para>Before VirtualBox 4.0, it was necessary to call VBoxManage
     1969        openmedium before a medium could be attached to a virtual machine;
     1970        that call "registered" the medium with the global VirtualBox media
     1971        registry. With VirtualBox 4.0 this is no longer necessary; media are
     1972        added to media registries automatically. The "closemedium" call has
     1973        been retained, however, to allow for explicitly removing a medium from
     1974        a registry.</para>
     1975      </footnote></para>
     1976
     1977    <para>Optionally, you can request that the image be deleted. You will get
     1978    appropriate diagnostics that the deletion failed, however the image will
     1979    become unregistered in any case.</para>
     1980  </sect1>
     1981
    19501982  <sect1>
    19511983    <title>VBoxManage getextradata/setextradata</title>
    … …  
    20262058
    20272059          <glossdef>
    2028             <para>This specifies which library implements the VirtualBox Remote Desktop
    2029             Extension.</para>
     2060            <para>This specifies which library implements the VirtualBox
     2061            Remote Desktop Extension.</para>
    20302062          </glossdef>
    20312063        </glossentry>

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

    r32709 r33456  
    375375        { "adoptstate",       USAGE_ADOPTSTATE,        handleAdoptState },
    376376        { "snapshot",         USAGE_SNAPSHOT,          handleSnapshot },
    377         { "openmedium",       USAGE_OPENMEDIUM,        handleOpenMedium },
    378         { "registerimage",    USAGE_OPENMEDIUM,        handleOpenMedium }, /* backward compatiblity */
    379377        { "closemedium",      USAGE_CLOSEMEDIUM,       handleCloseMedium },
    380         { "unregisterimage",  USAGE_CLOSEMEDIUM,       handleCloseMedium }, /* backward compatiblity */
    381378        { "storageattach",    USAGE_STORAGEATTACH,     handleStorageAttach },
    382379        { "storagectl",       USAGE_STORAGECONTROLLER, handleStorageController },

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

    r33228 r33456  
    4949#define USAGE_DISCARDSTATE          RT_BIT_64(8)
    5050#define USAGE_SNAPSHOT              RT_BIT_64(9)
    51 #define USAGE_OPENMEDIUM            RT_BIT_64(10)
    5251#define USAGE_CLOSEMEDIUM           RT_BIT_64(11)
    5352#define USAGE_SHOWHDINFO            RT_BIT_64(12)
    … …  
    218217int handleAddiSCSIDisk(HandlerArg *a);
    219218int handleShowHardDiskInfo(HandlerArg *a);
    220 int handleOpenMedium(HandlerArg *a);
    221219int handleCloseMedium(HandlerArg *a);
    222220

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

    r33294 r33456  
    13411341}
    13421342
    1343 static const RTGETOPTDEF g_aOpenMediumOptions[] =
    1344 {
    1345     { "disk",           'd', RTGETOPT_REQ_NOTHING },
    1346     { "dvd",            'D', RTGETOPT_REQ_NOTHING },
    1347     { "floppy",         'f', RTGETOPT_REQ_NOTHING },
    1348     { "--type",         't', RTGETOPT_REQ_STRING },
    1349     { "-type",          't', RTGETOPT_REQ_STRING },     // deprecated
    1350     { "--uuid",         'u', RTGETOPT_REQ_UUID },
    1351     { "--parentuuid",   'p', RTGETOPT_REQ_UUID },
    1352 };
    1353 
    1354 int handleOpenMedium(HandlerArg *a)
    1355 {
    1356     HRESULT rc = S_OK;
    1357     int vrc;
    1358     DeviceType_T devType = DeviceType_Null;
    1359     const char *Filename = NULL;
    1360     MediumType_T DiskType = MediumType_Normal;
    1361     bool fDiskType = false;
    1362     bool fSetImageId = false;
    1363     bool fSetParentId = false;
    1364     Guid ImageId;
    1365     ImageId.clear();
    1366     Guid ParentId;
    1367     ParentId.clear();
    1368 
    1369     int c;
    1370     RTGETOPTUNION ValueUnion;
    1371     RTGETOPTSTATE GetState;
    1372     // start at 0 because main() has hacked both the argc and argv given to us
    1373     RTGetOptInit(&GetState, a->argc, a->argv, g_aOpenMediumOptions, RT_ELEMENTS(g_aOpenMediumOptions),
    1374                  0, RTGETOPTINIT_FLAGS_NO_STD_OPTS);
    1375     while ((c = RTGetOpt(&GetState, &ValueUnion)))
    1376     {
    1377         switch (c)
    1378         {
    1379             case 'd':   // disk
    1380                 if (devType != DeviceType_Null)
    1381                     return errorSyntax(USAGE_OPENMEDIUM, "Only one command can be specified: '%s'", ValueUnion.psz);
    1382                 devType = DeviceType_HardDisk;
    1383                 break;
    1384 
    1385             case 'D':   // DVD
    1386                 if (devType != DeviceType_Null)
    1387                     return errorSyntax(USAGE_OPENMEDIUM, "Only one command can be specified: '%s'", ValueUnion.psz);
    1388                 devType = DeviceType_DVD;
    1389                 break;
    1390 
    1391             case 'f':   // floppy
    1392                 if (devType != DeviceType_Null)
    1393                     return errorSyntax(USAGE_OPENMEDIUM, "Only one command can be specified: '%s'", ValueUnion.psz);
    1394                 devType = DeviceType_Floppy;
    1395                 break;
    1396 
    1397             case 't':   // --type
    1398                 vrc = parseDiskType(ValueUnion.psz, &DiskType);
    1399                 if (RT_FAILURE(vrc))
    1400                     return errorArgument("Invalid hard disk type '%s'", ValueUnion.psz);
    1401                 fDiskType = true;
    1402                 break;
    1403 
    1404             case 'u':   // --uuid
    1405                 ImageId = ValueUnion.Uuid;
    1406                 fSetImageId = true;
    1407                 break;
    1408 
    1409             case 'p':   // --parentuuid
    1410                 ParentId = ValueUnion.Uuid;
    1411                 fSetParentId = true;
    1412                 break;
    1413 
    1414             case VINF_GETOPT_NOT_OPTION:
    1415                 if (!Filename)
    1416                     Filename = ValueUnion.psz;
    1417                 else
    1418                     return errorSyntax(USAGE_OPENMEDIUM, "Invalid parameter '%s'", ValueUnion.psz);
    1419                 break;
    1420 
    1421             default:
    1422                 if (c > 0)
    1423                 {
    1424                     if (RT_C_IS_PRINT(c))
    1425                         return errorSyntax(USAGE_OPENMEDIUM, "Invalid option -%c", c);
    1426                     else
    1427                         return errorSyntax(USAGE_OPENMEDIUM, "Invalid option case %i", c);
    1428                 }
    1429                 else if (c == VERR_GETOPT_UNKNOWN_OPTION)
    1430                     return errorSyntax(USAGE_OPENMEDIUM, "unknown option: %s\n", ValueUnion.psz);
    1431                 else if (ValueUnion.pDef)
    1432                     return errorSyntax(USAGE_OPENMEDIUM, "%s: %Rrs", ValueUnion.pDef->pszLong, c);
    1433                 else
    1434                     return errorSyntax(USAGE_OPENMEDIUM, "error: %Rrs", c);
    1435         }
    1436     }
    1437 
    1438     /* check for required options */
    1439     if (devType == DeviceType_Null)
    1440         return errorSyntax(USAGE_OPENMEDIUM, "Command variant disk/dvd/floppy required");
    1441     if (!Filename)
    1442         return errorSyntax(USAGE_OPENMEDIUM, "Disk name required");
    1443 
    1444     /** @todo remove this hack!
    1445      * First try opening the image as is (using the regular API semantics for
    1446      * images with relative path or without path), and if that fails with a
    1447      * file related error then try it again with what the client thinks the
    1448      * relative path would mean. Requires doing the command twice in certain
    1449      * cases. This is an ugly hack and needs to be removed whevever we have a
    1450      * chance to clean up the API semantics. */
    1451 
    1452     ComPtr<IMedium> pMedium;
    1453     rc = a->virtualBox->OpenMedium(Bstr(Filename).raw(), devType,
    1454                                    AccessMode_ReadWrite, pMedium.asOutParam());
    1455     if (rc == VBOX_E_FILE_ERROR)
    1456     {
    1457         char szFilenameAbs[RTPATH_MAX] = "";
    1458         int irc = RTPathAbs(Filename, szFilenameAbs, sizeof(szFilenameAbs));
    1459         if (RT_FAILURE(irc))
    1460         {
    1461             RTMsgError("Cannot convert filename \"%s\" to absolute path", Filename);
    1462             return 1;
    1463         }
    1464         CHECK_ERROR(a->virtualBox, OpenMedium(Bstr(szFilenameAbs).raw(),
    1465                                               devType, AccessMode_ReadWrite,
    1466                                               pMedium.asOutParam()));
    1467     }
    1468     if (SUCCEEDED(rc) && pMedium)
    1469     {
    1470         if (devType == DeviceType_HardDisk)
    1471         {
    1472             if (DiskType != MediumType_Normal)
    1473             {
    1474                 CHECK_ERROR(pMedium, COMSETTER(Type)(DiskType));
    1475             }
    1476         }
    1477         else
    1478         {
    1479             // DVD or floppy image
    1480             if (fDiskType || fSetParentId)
    1481                 return errorSyntax(USAGE_OPENMEDIUM, "Invalid option for DVD and floppy images");
    1482         }
    1483         if (fSetImageId || fSetParentId)
    1484         {
    1485             Bstr ImageIdStr = BstrFmt("%RTuuid", &ImageId);
    1486             Bstr ParentIdStr = BstrFmt("%RTuuid", &ParentId);
    1487             CHECK_ERROR(pMedium, SetIDs(fSetImageId, ImageIdStr.raw(),
    1488                                         fSetParentId, ParentIdStr.raw()));
    1489         }
    1490     }
    1491 
    1492     return SUCCEEDED(rc) ? 0 : 1;
    1493 }
    1494 
    14951343static const RTGETOPTDEF g_aCloseMediumOptions[] =
    14961344{

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

    r33408 r33456  
    451451    }
    452452
    453     if (u64Cmd & USAGE_OPENMEDIUM)
    454     {
    455         RTStrmPrintf(pStrm,
    456                      "VBoxManage openmedium       disk|dvd|floppy <filename>\n"
    457                      "                            [--type normal|immutable|writethrough|\n"
    458                      "                                    shareable] (disk only)\n"
    459                      "                            [--uuid <uuid>]\n"
    460                      "                            [--parentuuid <uuid>] (disk only)\n"
    461                      "\n");
    462     }
    463 
    464453    if (u64Cmd & USAGE_CLOSEMEDIUM)
    465454    {
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette