VirtualBox

source: vbox/trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp@ 37671

Last change on this file since 37671 was 37172, checked in by vboxsync, 14 years ago

VBoxManage: help commands
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.5 KB
Line 
1/* $Id: VBoxManage.cpp 37172 2011-05-20 17:15:55Z vboxsync $ */
2/** @file
3 * VBoxManage - VirtualBox's command-line interface.
4 */
5
6/*
7 * Copyright (C) 2006-2010 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18
19/*******************************************************************************
20* Header Files *
21*******************************************************************************/
22#ifndef VBOX_ONLY_DOCS
23# include <VBox/com/com.h>
24# include <VBox/com/string.h>
25# include <VBox/com/Guid.h>
26# include <VBox/com/array.h>
27# include <VBox/com/ErrorInfo.h>
28# include <VBox/com/errorprint.h>
29# include <VBox/com/EventQueue.h>
30
31# include <VBox/com/VirtualBox.h>
32#endif /* !VBOX_ONLY_DOCS */
33
34#include <VBox/err.h>
35#include <VBox/version.h>
36
37#include <iprt/asm.h>
38#include <iprt/buildconfig.h>
39#include <iprt/initterm.h>
40#include <iprt/stream.h>
41#include <iprt/string.h>
42
43#include <signal.h>
44
45#include "VBoxManage.h"
46
47
48/*******************************************************************************
49* Global Variables *
50*******************************************************************************/
51/*extern*/ bool g_fDetailedProgress = false;
52
53#ifndef VBOX_ONLY_DOCS
54/** Set by the signal handler. */
55static volatile bool g_fCanceled = false;
56
57
58/**
59 * Signal handler that sets g_fCanceled.
60 *
61 * This can be executed on any thread in the process, on Windows it may even be
62 * a thread dedicated to delivering this signal. Do not doing anything
63 * unnecessary here.
64 */
65static void showProgressSignalHandler(int iSignal)
66{
67 NOREF(iSignal);
68 ASMAtomicWriteBool(&g_fCanceled, true);
69}
70
71/**
72 * Print out progress on the console.
73 *
74 * This runs the main event queue every now and then to prevent piling up
75 * unhandled things (which doesn't cause real problems, just makes things
76 * react a little slower than in the ideal case).
77 */
78HRESULT showProgress(ComPtr<IProgress> progress)
79{
80 using namespace com;
81
82 BOOL fCompleted = FALSE;
83 ULONG ulCurrentPercent = 0;
84 ULONG ulLastPercent = 0;
85
86 ULONG ulLastOperationPercent = (ULONG)-1;
87
88 ULONG ulLastOperation = (ULONG)-1;
89 Bstr bstrOperationDescription;
90
91 EventQueue::getMainEventQueue()->processEventQueue(0);
92
93 ULONG cOperations = 1;
94 HRESULT hrc = progress->COMGETTER(OperationCount)(&cOperations);
95 if (FAILED(hrc))
96 {
97 RTStrmPrintf(g_pStdErr, "Progress object failure: %Rhrc\n", hrc);
98 RTStrmFlush(g_pStdErr);
99 return hrc;
100 }
101
102 if (!g_fDetailedProgress)
103 {
104 RTStrmPrintf(g_pStdErr, "0%%...");
105 RTStrmFlush(g_pStdErr);
106 }
107
108 /* setup signal handling if cancelable */
109 bool fCanceledAlready = false;
110 BOOL fCancelable;
111 hrc = progress->COMGETTER(Cancelable)(&fCancelable);
112 if (FAILED(hrc))
113 fCancelable = FALSE;
114 if (fCancelable)
115 {
116 signal(SIGINT, showProgressSignalHandler);
117#ifdef SIGBREAK
118 signal(SIGBREAK, showProgressSignalHandler);
119#endif
120 }
121
122 hrc = progress->COMGETTER(Completed(&fCompleted));
123 while (SUCCEEDED(hrc))
124 {
125 progress->COMGETTER(Percent(&ulCurrentPercent));
126
127 if (g_fDetailedProgress)
128 {
129 ULONG ulOperation = 1;
130 hrc = progress->COMGETTER(Operation)(&ulOperation);
131 if (FAILED(hrc))
132 break;
133 ULONG ulCurrentOperationPercent = 0;
134 hrc = progress->COMGETTER(OperationPercent(&ulCurrentOperationPercent));
135 if (FAILED(hrc))
136 break;
137
138 if (ulLastOperation != ulOperation)
139 {
140 hrc = progress->COMGETTER(OperationDescription(bstrOperationDescription.asOutParam()));
141 if (FAILED(hrc))
142 break;
143 ulLastPercent = (ULONG)-1; // force print
144 ulLastOperation = ulOperation;
145 }
146
147 if ( ulCurrentPercent != ulLastPercent
148 || ulCurrentOperationPercent != ulLastOperationPercent
149 )
150 {
151 LONG lSecsRem = 0;
152 progress->COMGETTER(TimeRemaining)(&lSecsRem);
153
154 RTStrmPrintf(g_pStdErr, "(%u/%u) %ls %02u%% => %02u%% (%d s remaining)\n", ulOperation + 1, cOperations, bstrOperationDescription.raw(), ulCurrentOperationPercent, ulCurrentPercent, lSecsRem);
155 ulLastPercent = ulCurrentPercent;
156 ulLastOperationPercent = ulCurrentOperationPercent;
157 }
158 }
159 else
160 {
161 /* did we cross a 10% mark? */
162 if (ulCurrentPercent / 10 > ulLastPercent / 10)
163 {
164 /* make sure to also print out missed steps */
165 for (ULONG curVal = (ulLastPercent / 10) * 10 + 10; curVal <= (ulCurrentPercent / 10) * 10; curVal += 10)
166 {
167 if (curVal < 100)
168 {
169 RTStrmPrintf(g_pStdErr, "%u%%...", curVal);
170 RTStrmFlush(g_pStdErr);
171 }
172 }
173 ulLastPercent = (ulCurrentPercent / 10) * 10;
174 }
175 }
176 if (fCompleted)
177 break;
178
179 /* process async cancelation */
180 if (g_fCanceled && !fCanceledAlready)
181 {
182 hrc = progress->Cancel();
183 if (SUCCEEDED(hrc))
184 fCanceledAlready = true;
185 else
186 g_fCanceled = false;
187 }
188
189 /* make sure the loop is not too tight */
190 progress->WaitForCompletion(100);
191
192 EventQueue::getMainEventQueue()->processEventQueue(0);
193 hrc = progress->COMGETTER(Completed(&fCompleted));
194 }
195
196 /* undo signal handling */
197 if (fCancelable)
198 {
199 signal(SIGINT, SIG_DFL);
200#ifdef SIGBREAK
201 signal(SIGBREAK, SIG_DFL);
202#endif
203 }
204
205 /* complete the line. */
206 LONG iRc = E_FAIL;
207 hrc = progress->COMGETTER(ResultCode)(&iRc);
208 if (SUCCEEDED(hrc))
209 {
210 if (SUCCEEDED(iRc))
211 RTStrmPrintf(g_pStdErr, "100%%\n");
212 else if (g_fCanceled)
213 RTStrmPrintf(g_pStdErr, "CANCELED\n");
214 else
215 {
216 if (!g_fDetailedProgress)
217 RTStrmPrintf(g_pStdErr, "\n");
218 RTStrmPrintf(g_pStdErr, "Progress state: %Rhrc\n", iRc);
219 }
220 hrc = iRc;
221 }
222 else
223 {
224 if (!g_fDetailedProgress)
225 RTStrmPrintf(g_pStdErr, "\n");
226 RTStrmPrintf(g_pStdErr, "Progress object failure: %Rhrc\n", hrc);
227 }
228 RTStrmFlush(g_pStdErr);
229 return hrc;
230}
231
232#endif /* !VBOX_ONLY_DOCS */
233
234#ifdef RT_OS_WINDOWS
235// Required for ATL
236static CComModule _Module;
237#endif
238
239
240int main(int argc, char *argv[])
241{
242 /*
243 * Before we do anything, init the runtime without loading
244 * the support driver.
245 */
246 RTR3Init();
247
248 /*
249 * Parse the global options
250 */
251 bool fShowLogo = false;
252 bool fShowHelp = false;
253 int iCmd = 1;
254 int iCmdArg;
255
256 for (int i = 1; i < argc || argc <= iCmd; i++)
257 {
258 if ( argc <= iCmd
259 || !strcmp(argv[i], "help")
260 || !strcmp(argv[i], "-?")
261 || !strcmp(argv[i], "-h")
262 || !strcmp(argv[i], "-help")
263 || !strcmp(argv[i], "--help"))
264 {
265 if (i >= argc - 1)
266 {
267 showLogo(g_pStdOut);
268 printUsage(USAGE_ALL, g_pStdOut);
269 return 0;
270 }
271 fShowLogo = true;
272 fShowHelp = true;
273 iCmd++;
274 continue;
275 }
276
277 if ( !strcmp(argv[i], "-v")
278 || !strcmp(argv[i], "-version")
279 || !strcmp(argv[i], "-Version")
280 || !strcmp(argv[i], "--version"))
281 {
282 /* Print version number, and do nothing else. */
283 RTPrintf("%sr%d\n", VBOX_VERSION_STRING, RTBldCfgRevision());
284 return 0;
285 }
286
287 if ( !strcmp(argv[i], "--dumpopts")
288 || !strcmp(argv[i], "-dumpopts"))
289 {
290 /* Special option to dump really all commands,
291 * even the ones not understood on this platform. */
292 printUsage(USAGE_DUMPOPTS, g_pStdOut);
293 return 0;
294 }
295
296 if ( !strcmp(argv[i], "--nologo")
297 || !strcmp(argv[i], "-nologo")
298 || !strcmp(argv[i], "-q"))
299 {
300 /* suppress the logo */
301 fShowLogo = false;
302 iCmd++;
303 }
304 else if ( !strcmp(argv[i], "--detailed-progress")
305 || !strcmp(argv[i], "-d"))
306 {
307 /* detailed progress report */
308 g_fDetailedProgress = true;
309 iCmd++;
310 }
311 else
312 {
313 break;
314 }
315 }
316
317 iCmdArg = iCmd + 1;
318
319 if (fShowLogo)
320 showLogo(g_pStdOut);
321
322
323#ifndef VBOX_ONLY_DOCS
324 /*
325 * Initialize COM.
326 */
327 using namespace com;
328 HRESULT hrc = com::Initialize();
329 if (FAILED(hrc))
330 return RTMsgErrorExit(RTEXITCODE_FAILURE, "Failed to initialize COM!");
331
332 /*
333 * The input is ASSUMED to be in the current process codeset (NT guarantees
334 * ACP, unixy systems doesn't guarantee anything). This loop converts all
335 * the argv[*] strings to UTF-8, which is a tad ugly but who cares.
336 * (As a rule all strings in VirtualBox are UTF-8.)
337 */
338 for (int i = iCmdArg; i < argc; i++)
339 {
340 char *pszConverted;
341 int rc = RTStrCurrentCPToUtf8(&pszConverted, argv[i]);
342 if (RT_SUCCESS(rc))
343 argv[i] = pszConverted;
344 else
345 /* Conversion was not possible,probably due to invalid characters.
346 * Keep in mind that we do RTStrFree on the whole array below. */
347 argv[i] = RTStrDup(argv[i]);
348 }
349
350 RTEXITCODE rcExit = RTEXITCODE_FAILURE;
351 do
352 {
353 ///////////////////////////////////////////////////////////////////////////
354 // scopes all the stuff till shutdown
355 /*
356 * convertfromraw: does not need a VirtualBox instantiation.
357 */
358 if (argc >= iCmdArg && ( !strcmp(argv[iCmd], "convertfromraw")
359 || !strcmp(argv[iCmd], "convertdd")))
360 {
361 rcExit = handleConvertFromRaw(argc - iCmdArg, argv + iCmdArg);
362 break;
363 }
364
365 /*
366 * Get the remote VirtualBox object and create a local session object.
367 */
368 ComPtr<IVirtualBox> virtualBox;
369 ComPtr<ISession> session;
370
371 hrc = virtualBox.createLocalObject(CLSID_VirtualBox);
372 if (FAILED(hrc))
373 RTMsgError("Failed to create the VirtualBox object!");
374 else
375 {
376 hrc = session.createInprocObject(CLSID_Session);
377 if (FAILED(hrc))
378 RTMsgError("Failed to create a session object!");
379 }
380 if (FAILED(hrc))
381 {
382 com::ErrorInfo info;
383 if (!info.isFullAvailable() && !info.isBasicAvailable())
384 {
385 com::GluePrintRCMessage(hrc);
386 RTMsgError("Most likely, the VirtualBox COM server is not running or failed to start.");
387 }
388 else
389 com::GluePrintErrorInfo(info);
390 break;
391 }
392
393 /*
394 * All registered command handlers
395 */
396 static const struct
397 {
398 const char *command;
399 USAGECATEGORY help;
400 int (*handler)(HandlerArg *a);
401 } s_commandHandlers[] =
402 {
403 { "internalcommands", 0, handleInternalCommands },
404 { "list", USAGE_LIST, handleList },
405 { "showvminfo", USAGE_SHOWVMINFO, handleShowVMInfo },
406 { "registervm", USAGE_REGISTERVM, handleRegisterVM },
407 { "unregistervm", USAGE_UNREGISTERVM, handleUnregisterVM },
408 { "clonevm", USAGE_CLONEVM, handleCloneVM },
409 { "createhd", USAGE_CREATEHD, handleCreateHardDisk },
410 { "createvdi", USAGE_CREATEHD, handleCreateHardDisk }, /* backward compatibility */
411 { "modifyhd", USAGE_MODIFYHD, handleModifyHardDisk },
412 { "modifyvdi", USAGE_MODIFYHD, handleModifyHardDisk }, /* backward compatibility */
413 { "clonehd", USAGE_CLONEHD, handleCloneHardDisk },
414 { "clonevdi", USAGE_CLONEHD, handleCloneHardDisk }, /* backward compatibility */
415 { "createvm", USAGE_CREATEVM, handleCreateVM },
416 { "modifyvm", USAGE_MODIFYVM, handleModifyVM },
417 { "startvm", USAGE_STARTVM, handleStartVM },
418 { "controlvm", USAGE_CONTROLVM, handleControlVM },
419 { "discardstate", USAGE_DISCARDSTATE, handleDiscardState },
420 { "adoptstate", USAGE_ADOPTSTATE, handleAdoptState },
421 { "snapshot", USAGE_SNAPSHOT, handleSnapshot },
422 { "closemedium", USAGE_CLOSEMEDIUM, handleCloseMedium },
423 { "storageattach", USAGE_STORAGEATTACH, handleStorageAttach },
424 { "storagectl", USAGE_STORAGECONTROLLER, handleStorageController },
425 { "showhdinfo", USAGE_SHOWHDINFO, handleShowHardDiskInfo },
426 { "showvdiinfo", USAGE_SHOWHDINFO, handleShowHardDiskInfo }, /* backward compatibility */
427 { "getextradata", USAGE_GETEXTRADATA, handleGetExtraData },
428 { "setextradata", USAGE_SETEXTRADATA, handleSetExtraData },
429 { "setproperty", USAGE_SETPROPERTY, handleSetProperty },
430 { "usbfilter", USAGE_USBFILTER, handleUSBFilter },
431 { "sharedfolder", USAGE_SHAREDFOLDER, handleSharedFolder },
432#ifdef VBOX_WITH_GUEST_PROPS
433 { "guestproperty", USAGE_GUESTPROPERTY, handleGuestProperty },
434#endif
435#ifdef VBOX_WITH_GUEST_CONTROL
436 { "guestcontrol", USAGE_GUESTCONTROL, handleGuestControl },
437#endif
438 { "metrics", USAGE_METRICS, handleMetrics },
439 { "import", USAGE_IMPORTAPPLIANCE, handleImportAppliance },
440 { "export", USAGE_EXPORTAPPLIANCE, handleExportAppliance },
441#ifdef VBOX_WITH_NETFLT
442 { "hostonlyif", USAGE_HOSTONLYIFS, handleHostonlyIf },
443#endif
444 { "dhcpserver", USAGE_DHCPSERVER, handleDHCPServer},
445 { "extpack", USAGE_EXTPACK, handleExtPack},
446 { "bandwidthctl", USAGE_BANDWIDTHCONTROL, handleBandwidthControl},
447 { "debugvm", USAGE_DEBUGVM, handleDebugVM},
448 { NULL, 0, NULL }
449 };
450
451 HandlerArg handlerArg = { 0, NULL, virtualBox, session };
452 int commandIndex;
453 for (commandIndex = 0; s_commandHandlers[commandIndex].command != NULL; commandIndex++)
454 {
455 if (!strcmp(s_commandHandlers[commandIndex].command, argv[iCmd]))
456 {
457 handlerArg.argc = argc - iCmdArg;
458 handlerArg.argv = &argv[iCmdArg];
459
460 if ( fShowHelp
461 || ( argc - iCmdArg == 0
462 && s_commandHandlers[commandIndex].help))
463 {
464 printUsage(s_commandHandlers[commandIndex].help, g_pStdOut);
465 rcExit = RTEXITCODE_FAILURE; /* error */
466 }
467 else
468 rcExit = (RTEXITCODE)s_commandHandlers[commandIndex].handler(&handlerArg); /** @todo Change to return RTEXITCODE. */
469 break;
470 }
471 }
472 if (!s_commandHandlers[commandIndex].command)
473 {
474 /* Help topics. */
475 if (fShowHelp && !strcmp(argv[iCmd], "commands"))
476 {
477 RTPrintf("commands:\n");
478 for (unsigned i = 0; i < RT_ELEMENTS(s_commandHandlers) - 1; i++)
479 if ( i == 0 /* skip backwards compatibility entries */
480 || s_commandHandlers[i].help != s_commandHandlers[i - 1].help)
481 RTPrintf(" %s\n", s_commandHandlers[i].command);
482 }
483 else
484 rcExit = errorSyntax(USAGE_ALL, "Invalid command '%s'", Utf8Str(argv[iCmd]).c_str());
485 }
486
487 /* Although all handlers should always close the session if they open it,
488 * we do it here just in case if some of the handlers contains a bug --
489 * leaving the direct session not closed will turn the machine state to
490 * Aborted which may have unwanted side effects like killing the saved
491 * state file (if the machine was in the Saved state before). */
492 session->UnlockMachine();
493
494 EventQueue::getMainEventQueue()->processEventQueue(0);
495
496 // end "all-stuff" scope
497 ///////////////////////////////////////////////////////////////////////////
498 } while (0);
499
500 com::Shutdown();
501
502 /*
503 * Free converted argument vector
504 */
505 for (int i = iCmdArg; i < argc; i++)
506 {
507 RTStrFree(argv[i]);
508 argv[i] = NULL;
509 }
510
511 return rcExit;
512#else /* VBOX_ONLY_DOCS */
513 return RTEXITCODE_SUCCESS;
514#endif /* VBOX_ONLY_DOCS */
515}
Note: See TracBrowser for help on using the repository browser.

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