VirtualBox

source: vbox/trunk/src/VBox/Frontends/VBoxManage/VBoxManage.h@ 93842

Last change on this file since 93842 was 93708, checked in by vboxsync, 3 years ago

include/iprt/message.h: Max out the available bits for the scope, we need a lot for the VBoxManage controlvm docs.

docs, VBoxManage: Integrate refman (and fix some content) for VBoxManage startvm and VBoxManage controlvm. Needs about 60 scopes (do RT_BIT_64 is a must have), and for protection against exceeding the limit there are now checks (as AssertCompile).
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 14.5 KB
Line 
1/* $Id: VBoxManage.h 93708 2022-02-11 20:46:11Z vboxsync $ */
2/** @file
3 * VBoxManage - VirtualBox command-line interface, internal header file.
4 */
5
6/*
7 * Copyright (C) 2006-2022 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#ifndef VBOX_INCLUDED_SRC_VBoxManage_VBoxManage_h
19#define VBOX_INCLUDED_SRC_VBoxManage_VBoxManage_h
20#ifndef RT_WITHOUT_PRAGMA_ONCE
21# pragma once
22#endif
23
24#ifndef VBOX_ONLY_DOCS
25#include <VBox/com/com.h>
26#include <VBox/com/ptr.h>
27#include <VBox/com/VirtualBox.h>
28#include <VBox/com/string.h>
29#include <VBox/com/array.h>
30#endif /* !VBOX_ONLY_DOCS */
31
32#include <iprt/types.h>
33#include <iprt/message.h>
34#include <iprt/stream.h>
35#include <iprt/getopt.h>
36
37#ifndef VBOX_ONLY_DOCS
38# include "VBoxManageBuiltInHelp.h"
39# include "PasswordInput.h"
40#endif
41
42#ifdef VBOX_WITH_VBOXMANAGE_NLS
43# include "VirtualBoxTranslator.h"
44#endif
45
46
47////////////////////////////////////////////////////////////////////////////////
48//
49// definitions
50//
51////////////////////////////////////////////////////////////////////////////////
52
53/**
54 * This defines a a_CtxName::tr function that gives the translator context as
55 * well as providing a shorter way to call VirtualBoxTranslator::translate.
56 */
57#ifdef VBOX_WITH_VBOXMANAGE_NLS
58# define DECLARE_TRANSLATION_CONTEXT(a_CtxName) \
59struct a_CtxName \
60{ \
61 static const char *tr(const char *pszSource, const char *pszComment = NULL, const size_t uNum = ~(size_t)0) \
62 { \
63 return VirtualBoxTranslator::translate(NULL, #a_CtxName, pszSource, pszComment, uNum); \
64 } \
65}
66#else
67# define DECLARE_TRANSLATION_CONTEXT(a_CtxName) \
68struct a_CtxName \
69{ \
70 static const char *tr(const char *pszSource, const char *pszComment = NULL, const size_t uNum = ~(size_t)0) \
71 { \
72 RT_NOREF(pszComment, uNum); \
73 return pszSource; \
74 } \
75}
76#endif
77
78/**
79 * Defines an option with two variants, producing two RTGETOPTDEF entries.
80 *
81 * This is mainly for replacing character-soup option names like
82 * --natlocalhostreachable and --biossystemtimeoffset with more easily parsed
83 * ones, like --nat-localhost-reachable and --bios-system-time-offset, without
84 * removing the legacy name.
85 */
86#define OPT2(a_pszWordDashWord, a_pszWordSoup, a_chOptOrValue, a_fFlags) \
87 { a_pszWordDashWord, a_chOptOrValue, a_fFlags }, \
88 { a_pszWordSoup, a_chOptOrValue, a_fFlags }
89
90/** A single option variant of OPT2 for better looking tables. */
91#define OPT1(a_pszOption, a_chOptOrValue, a_fFlags) \
92 { a_pszOption, a_chOptOrValue, a_fFlags }
93
94
95/** @name Syntax diagram category, i.e. the command.
96 * @{ */
97typedef enum
98{
99 USAGE_INVALID = 0,
100 USAGE_DISCARDSTATE,
101 USAGE_CLOSEMEDIUM,
102 USAGE_SHOWMEDIUMINFO,
103 USAGE_CREATEMEDIUM,
104 USAGE_MODIFYMEDIUM,
105 USAGE_CLONEMEDIUM,
106 USAGE_CREATEHOSTIF,
107 USAGE_REMOVEHOSTIF,
108 USAGE_GETEXTRADATA,
109 USAGE_SETEXTRADATA,
110 USAGE_SETPROPERTY,
111 USAGE_USBFILTER,
112 USAGE_I_LOADSYMS,
113 USAGE_I_LOADMAP,
114 USAGE_I_SETHDUUID,
115 USAGE_CONVERTFROMRAW,
116 USAGE_I_LISTPARTITIONS,
117 USAGE_I_CREATERAWVMDK,
118 USAGE_ADOPTSTATE,
119 USAGE_I_MODINSTALL,
120 USAGE_I_MODUNINSTALL,
121 USAGE_I_RENAMEVMDK,
122#ifdef VBOX_WITH_GUEST_PROPS
123 USAGE_GUESTPROPERTY,
124#endif /* VBOX_WITH_GUEST_PROPS defined */
125 USAGE_I_CONVERTTORAW,
126 USAGE_METRICS,
127 USAGE_I_CONVERTHD,
128 USAGE_HOSTONLYIFS,
129 USAGE_I_DUMPHDINFO,
130 USAGE_STORAGEATTACH,
131 USAGE_STORAGECONTROLLER,
132#ifdef VBOX_WITH_GUEST_CONTROL
133 USAGE_GUESTCONTROL,
134#endif /* VBOX_WITH_GUEST_CONTROL defined */
135 USAGE_I_DEBUGLOG,
136 USAGE_I_SETHDPARENTUUID,
137 USAGE_I_PASSWORDHASH,
138 USAGE_BANDWIDTHCONTROL,
139 USAGE_I_GUESTSTATS,
140 USAGE_I_REPAIRHD,
141 USAGE_NATNETWORK,
142 USAGE_MEDIUMPROPERTY,
143 USAGE_ENCRYPTMEDIUM,
144 USAGE_MEDIUMENCCHKPWD,
145 USAGE_USBDEVSOURCE,
146 /* Insert new entries before this line, but only if it is not an option
147 * to go for the new style command and help handling (see e.g. extpack,
148 * unattend or mediumio. */
149 USAGE_S_NEWCMD = 10000, /**< new style command with no old help support */
150 USAGE_S_ALL,
151 USAGE_S_DUMPOPTS
152} USAGECATEGORY;
153/** @} */
154
155
156#define HELP_SCOPE_USBFILTER_ADD RT_BIT_64(0)
157#define HELP_SCOPE_USBFILTER_MODIFY RT_BIT_64(1)
158#define HELP_SCOPE_USBFILTER_REMOVE RT_BIT_64(2)
159
160#ifdef VBOX_WITH_GUEST_CONTROL
161# define HELP_SCOPE_GSTCTRL_RUN RT_BIT(0)
162# define HELP_SCOPE_GSTCTRL_START RT_BIT(1)
163# define HELP_SCOPE_GSTCTRL_COPYFROM RT_BIT(2)
164# define HELP_SCOPE_GSTCTRL_COPYTO RT_BIT(3)
165# define HELP_SCOPE_GSTCTRL_MKDIR RT_BIT(4)
166# define HELP_SCOPE_GSTCTRL_RMDIR RT_BIT(5)
167# define HELP_SCOPE_GSTCTRL_RM RT_BIT(6)
168# define HELP_SCOPE_GSTCTRL_MV RT_BIT(7)
169# define HELP_SCOPE_GSTCTRL_MKTEMP RT_BIT(8)
170# define HELP_SCOPE_GSTCTRL_LIST RT_BIT(9)
171# define HELP_SCOPE_GSTCTRL_CLOSEPROCESS RT_BIT(10)
172# define HELP_SCOPE_GSTCTRL_CLOSESESSION RT_BIT(11)
173# define HELP_SCOPE_GSTCTRL_STAT RT_BIT(12)
174# define HELP_SCOPE_GSTCTRL_UPDATEGA RT_BIT(13)
175# define HELP_SCOPE_GSTCTRL_WATCH RT_BIT(14)
176# define HELP_SCOPE_GSTCTRL_WAITRUNLEVEL RT_BIT(15)
177#endif
178
179/** command handler argument */
180struct HandlerArg
181{
182 int argc;
183 char **argv;
184
185#ifndef VBOX_ONLY_DOCS
186 ComPtr<IVirtualBox> virtualBox;
187 ComPtr<ISession> session;
188#endif
189};
190
191/** flag whether we're in internal mode */
192extern bool g_fInternalMode;
193
194/** showVMInfo details */
195typedef enum
196{
197 VMINFO_NONE = 0,
198 VMINFO_STANDARD = 1, /**< standard details */
199 VMINFO_FULL = 2, /**< both */
200 VMINFO_MACHINEREADABLE = 3, /**< both, and make it machine readable */
201 VMINFO_COMPACT = 4
202} VMINFO_DETAILS;
203
204
205////////////////////////////////////////////////////////////////////////////////
206//
207// global variables
208//
209////////////////////////////////////////////////////////////////////////////////
210
211extern bool g_fDetailedProgress; // in VBoxManage.cpp
212
213
214////////////////////////////////////////////////////////////////////////////////
215//
216// prototypes
217//
218////////////////////////////////////////////////////////////////////////////////
219
220/* VBoxManageHelp.cpp */
221
222/* Legacy help infrastructure, to be replaced by new one using generated help. */
223void printUsage(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm);
224RTEXITCODE errorSyntax(USAGECATEGORY enmCommand, const char *pszFormat, ...);
225RTEXITCODE errorSyntaxEx(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, const char *pszFormat, ...);
226RTEXITCODE errorGetOpt(USAGECATEGORY enmCommand, int rc, union RTGETOPTUNION const *pValueUnion);
227RTEXITCODE errorGetOptEx(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, int rc, union RTGETOPTUNION const *pValueUnion);
228
229void printUsageInternal(USAGECATEGORY enmCommand, PRTSTREAM pStrm);
230
231#ifndef VBOX_ONLY_DOCS
232void setCurrentCommand(enum HELP_CMD_VBOXMANAGE enmCommand);
233void setCurrentSubcommand(uint64_t fCurSubcommandScope);
234
235void printUsage(PRTSTREAM pStrm);
236void printHelp(PRTSTREAM pStrm);
237RTEXITCODE errorNoSubcommand(void);
238RTEXITCODE errorUnknownSubcommand(const char *pszSubCmd);
239RTEXITCODE errorTooManyParameters(char **papszArgs);
240RTEXITCODE errorGetOpt(int rcGetOpt, union RTGETOPTUNION const *pValueUnion);
241RTEXITCODE errorFetchValue(int iValueNo, const char *pszOption, int rcGetOptFetchValue, union RTGETOPTUNION const *pValueUnion);
242RTEXITCODE errorSyntax(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
243RTEXITCODE errorSyntaxV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
244HRESULT errorSyntaxHr(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
245RTEXITCODE errorArgument(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
246HRESULT errorArgumentHr(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
247
248# define SHOW_PROGRESS_NONE 0
249# define SHOW_PROGRESS_DESC RT_BIT_32(0)
250# define SHOW_PROGRESS RT_BIT_32(1)
251# define SHOW_PROGRESS_DETAILS RT_BIT_32(2)
252HRESULT showProgress(ComPtr<IProgress> progress, uint32_t fFlags = SHOW_PROGRESS);
253#endif
254
255/* VBoxManage.cpp */
256void showLogo(PRTSTREAM pStrm);
257
258#ifndef VBOX_ONLY_DOCS
259RTEXITCODE handleInternalCommands(HandlerArg *a);
260#endif /* !VBOX_ONLY_DOCS */
261
262/* VBoxManageControlVM.cpp */
263RTEXITCODE handleControlVM(HandlerArg *a);
264
265/* VBoxManageModifyVM.cpp */
266#ifndef VBOX_ONLY_DOCS
267void parseGroups(const char *pcszGroups, com::SafeArray<BSTR> *pGroups);
268# ifdef VBOX_WITH_RECORDING
269int parseScreens(const char *pcszScreens, com::SafeArray<BOOL> *pScreens);
270# endif
271#endif
272RTEXITCODE handleModifyVM(HandlerArg *a);
273
274/* VBoxManageDebugVM.cpp */
275RTEXITCODE handleDebugVM(HandlerArg *a);
276
277/* VBoxManageGuestProp.cpp */
278extern void usageGuestProperty(PRTSTREAM pStrm, const char *pcszSep1, const char *pcszSep2);
279
280/* VBoxManageGuestCtrl.cpp */
281extern void usageGuestControl(PRTSTREAM pStrm, const char *pcszSep1, const char *pcszSep2, uint64_t fSubcommandScope);
282
283#ifndef VBOX_ONLY_DOCS
284/* VBoxManageGuestProp.cpp */
285RTEXITCODE handleGuestProperty(HandlerArg *a);
286
287/* VBoxManageGuestCtrl.cpp */
288RTEXITCODE handleGuestControl(HandlerArg *a);
289
290/* VBoxManageVMInfo.cpp */
291HRESULT showSnapshots(ComPtr<ISnapshot> &rootSnapshot,
292 ComPtr<ISnapshot> &currentSnapshot,
293 VMINFO_DETAILS details,
294 const com::Utf8Str &prefix = "",
295 int level = 0);
296RTEXITCODE handleShowVMInfo(HandlerArg *a);
297HRESULT showVMInfo(ComPtr<IVirtualBox> pVirtualBox,
298 ComPtr<IMachine> pMachine,
299 ComPtr<ISession> pSession,
300 VMINFO_DETAILS details = VMINFO_NONE);
301const char *machineStateToName(MachineState_T machineState, bool fShort);
302HRESULT showBandwidthGroups(ComPtr<IBandwidthControl> &bwCtrl,
303 VMINFO_DETAILS details);
304void outputMachineReadableString(const char *pszName, const char *pszValue, bool fQuoteName = false, bool fNewline = true);
305void outputMachineReadableString(const char *pszName, com::Bstr const *pbstrValue, bool fQuoteName = false, bool fNewline = true);
306void outputMachineReadableStringWithFmtName(const char *pszValue, bool fQuoteName, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
307void outputMachineReadableStringWithFmtName(com::Bstr const *pbstrValue, bool fQuoteName, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
308void outputMachineReadableBool(const char *pszName, BOOL const *pfValue);
309void outputMachineReadableBool(const char *pszName, bool const *pfValue);
310void outputMachineReadableULong(const char *pszName, ULONG *uValue);
311void outputMachineReadableLong64(const char *pszName, LONG64 *uValue);
312
313/* VBoxManageList.cpp */
314RTEXITCODE handleList(HandlerArg *a);
315
316/* VBoxManageMetrics.cpp */
317RTEXITCODE handleMetrics(HandlerArg *a);
318
319/* VBoxManageMisc.cpp */
320RTEXITCODE handleRegisterVM(HandlerArg *a);
321RTEXITCODE handleUnregisterVM(HandlerArg *a);
322RTEXITCODE handleCreateVM(HandlerArg *a);
323RTEXITCODE handleCloneVM(HandlerArg *a);
324RTEXITCODE handleStartVM(HandlerArg *a);
325RTEXITCODE handleDiscardState(HandlerArg *a);
326RTEXITCODE handleAdoptState(HandlerArg *a);
327RTEXITCODE handleGetExtraData(HandlerArg *a);
328RTEXITCODE handleSetExtraData(HandlerArg *a);
329RTEXITCODE handleSetProperty(HandlerArg *a);
330RTEXITCODE handleSharedFolder(HandlerArg *a);
331RTEXITCODE handleExtPack(HandlerArg *a);
332RTEXITCODE handleUnattended(HandlerArg *a);
333RTEXITCODE handleMoveVM(HandlerArg *a);
334RTEXITCODE handleCloudProfile(HandlerArg *a);
335
336/* VBoxManageDisk.cpp */
337HRESULT openMedium(HandlerArg *a, const char *pszFilenameOrUuid,
338 DeviceType_T enmDevType, AccessMode_T enmAccessMode,
339 ComPtr<IMedium> &pMedium, bool fForceNewUuidOnOpen,
340 bool fSilent);
341RTEXITCODE handleCreateMedium(HandlerArg *a);
342RTEXITCODE handleModifyMedium(HandlerArg *a);
343RTEXITCODE handleCloneMedium(HandlerArg *a);
344RTEXITCODE handleMediumProperty(HandlerArg *a);
345RTEXITCODE handleEncryptMedium(HandlerArg *a);
346RTEXITCODE handleCheckMediumPassword(HandlerArg *a);
347RTEXITCODE handleConvertFromRaw(HandlerArg *a);
348HRESULT showMediumInfo(const ComPtr<IVirtualBox> &pVirtualBox,
349 const ComPtr<IMedium> &pMedium,
350 const char *pszParentUUID,
351 bool fOptLong);
352RTEXITCODE handleShowMediumInfo(HandlerArg *a);
353RTEXITCODE handleCloseMedium(HandlerArg *a);
354RTEXITCODE handleMediumIO(HandlerArg *a);
355int parseMediumType(const char *psz, MediumType_T *penmMediumType);
356int parseBool(const char *psz, bool *pb);
357
358/* VBoxManageStorageController.cpp */
359RTEXITCODE handleStorageAttach(HandlerArg *a);
360RTEXITCODE handleStorageController(HandlerArg *a);
361
362// VBoxManageAppliance.cpp
363RTEXITCODE handleImportAppliance(HandlerArg *a);
364RTEXITCODE handleExportAppliance(HandlerArg *a);
365RTEXITCODE handleSignAppliance(HandlerArg *a);
366
367// VBoxManageSnapshot.cpp
368RTEXITCODE handleSnapshot(HandlerArg *a);
369
370/* VBoxManageUSB.cpp */
371RTEXITCODE handleUSBFilter(HandlerArg *a);
372RTEXITCODE handleUSBDevSource(HandlerArg *a);
373
374/* VBoxManageHostonly.cpp */
375RTEXITCODE handleHostonlyIf(HandlerArg *a);
376#ifdef VBOX_WITH_VMNET
377RTEXITCODE handleHostonlyNet(HandlerArg *a);
378#endif /* VBOX_WITH_VMNET */
379
380/* VBoxManageDHCPServer.cpp */
381RTEXITCODE handleDHCPServer(HandlerArg *a);
382
383/* VBoxManageNATNetwork.cpp */
384RTEXITCODE handleNATNetwork(HandlerArg *a);
385RTEXITCODE listNATNetworks(bool fLong, bool fSorted,
386 const ComPtr<IVirtualBox> &pVirtualBox);
387
388/* VBoxManageBandwidthControl.cpp */
389RTEXITCODE handleBandwidthControl(HandlerArg *a);
390
391/* VBoxManageCloud.cpp */
392RTEXITCODE handleCloud(HandlerArg *a);
393
394/* VBoxManageCloudMachine.cpp */
395RTEXITCODE handleCloudMachine(HandlerArg *a, int iFirst,
396 const char *pcszProviderName,
397 const char *pcszProfileName);
398RTEXITCODE listCloudMachines(HandlerArg *a, int iFirst,
399 const char *pcszProviderName,
400 const char *pcszProfileName);
401RTEXITCODE handleCloudShowVMInfo(HandlerArg *a, int iFirst,
402 const char *pcszProviderName,
403 const char *pcszProfileName);
404
405/* VBoxManageUpdateCheck.cpp */
406RTEXITCODE handleUpdateCheck(HandlerArg *a);
407
408/* VBoxManageModifyNvram.cpp */
409RTEXITCODE handleModifyNvram(HandlerArg *a);
410
411#endif /* !VBOX_ONLY_DOCS */
412
413#endif /* !VBOX_INCLUDED_SRC_VBoxManage_VBoxManage_h */
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