VirtualBox

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

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

doc/manual,FE/VBoxManage: Convert metrics command to refentry documentation, ​bugref:9186
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.6 KB
Line 
1/* $Id: VBoxManage.h 94210 2022-03-13 20:25:00Z 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_MODIFYMEDIUM,
101 USAGE_CREATEHOSTIF,
102 USAGE_REMOVEHOSTIF,
103 USAGE_I_LOADSYMS,
104 USAGE_I_LOADMAP,
105 USAGE_I_SETHDUUID,
106 USAGE_I_LISTPARTITIONS,
107 USAGE_I_CREATERAWVMDK,
108 USAGE_I_MODINSTALL,
109 USAGE_I_MODUNINSTALL,
110 USAGE_I_RENAMEVMDK,
111 USAGE_I_CONVERTTORAW,
112 USAGE_I_CONVERTHD,
113 USAGE_HOSTONLYIFS,
114 USAGE_I_DUMPHDINFO,
115 USAGE_STORAGEATTACH,
116 USAGE_I_DEBUGLOG,
117 USAGE_I_SETHDPARENTUUID,
118 USAGE_I_PASSWORDHASH,
119 USAGE_I_GUESTSTATS,
120 USAGE_I_REPAIRHD,
121 USAGE_NATNETWORK,
122 USAGE_USBDEVSOURCE,
123 /* Insert new entries before this line, but only if it is not an option
124 * to go for the new style command and help handling (see e.g. extpack,
125 * unattend or mediumio. */
126 USAGE_S_NEWCMD = 10000, /**< new style command with no old help support */
127 USAGE_S_ALL,
128 USAGE_S_DUMPOPTS
129} USAGECATEGORY;
130/** @} */
131
132
133/** command handler argument */
134struct HandlerArg
135{
136 int argc;
137 char **argv;
138
139#ifndef VBOX_ONLY_DOCS
140 ComPtr<IVirtualBox> virtualBox;
141 ComPtr<ISession> session;
142#endif
143};
144
145/** flag whether we're in internal mode */
146extern bool g_fInternalMode;
147
148/** showVMInfo details */
149typedef enum
150{
151 VMINFO_NONE = 0,
152 VMINFO_STANDARD = 1, /**< standard details */
153 VMINFO_FULL = 2, /**< both */
154 VMINFO_MACHINEREADABLE = 3, /**< both, and make it machine readable */
155 VMINFO_COMPACT = 4
156} VMINFO_DETAILS;
157
158
159////////////////////////////////////////////////////////////////////////////////
160//
161// global variables
162//
163////////////////////////////////////////////////////////////////////////////////
164
165extern bool g_fDetailedProgress; // in VBoxManage.cpp
166
167
168////////////////////////////////////////////////////////////////////////////////
169//
170// prototypes
171//
172////////////////////////////////////////////////////////////////////////////////
173
174/* VBoxManageHelp.cpp */
175
176/* Legacy help infrastructure, to be replaced by new one using generated help. */
177void printUsage(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm);
178RTEXITCODE errorSyntax(USAGECATEGORY enmCommand, const char *pszFormat, ...);
179RTEXITCODE errorSyntaxEx(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, const char *pszFormat, ...);
180RTEXITCODE errorGetOpt(USAGECATEGORY enmCommand, int rc, union RTGETOPTUNION const *pValueUnion);
181RTEXITCODE errorGetOptEx(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, int rc, union RTGETOPTUNION const *pValueUnion);
182
183void printUsageInternal(USAGECATEGORY enmCommand, PRTSTREAM pStrm);
184
185#ifndef VBOX_ONLY_DOCS
186void setCurrentCommand(enum HELP_CMD_VBOXMANAGE enmCommand);
187void setCurrentSubcommand(uint64_t fCurSubcommandScope);
188
189void printUsage(PRTSTREAM pStrm);
190void printHelp(PRTSTREAM pStrm);
191RTEXITCODE errorNoSubcommand(void);
192RTEXITCODE errorUnknownSubcommand(const char *pszSubCmd);
193RTEXITCODE errorTooManyParameters(char **papszArgs);
194RTEXITCODE errorGetOpt(int rcGetOpt, union RTGETOPTUNION const *pValueUnion);
195RTEXITCODE errorFetchValue(int iValueNo, const char *pszOption, int rcGetOptFetchValue, union RTGETOPTUNION const *pValueUnion);
196RTEXITCODE errorSyntax(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
197RTEXITCODE errorSyntaxV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
198HRESULT errorSyntaxHr(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
199RTEXITCODE errorArgument(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
200HRESULT errorArgumentHr(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
201
202# define SHOW_PROGRESS_NONE 0
203# define SHOW_PROGRESS_DESC RT_BIT_32(0)
204# define SHOW_PROGRESS RT_BIT_32(1)
205# define SHOW_PROGRESS_DETAILS RT_BIT_32(2)
206HRESULT showProgress(ComPtr<IProgress> progress, uint32_t fFlags = SHOW_PROGRESS);
207#endif
208
209/* VBoxManage.cpp */
210void showLogo(PRTSTREAM pStrm);
211
212#ifndef VBOX_ONLY_DOCS
213RTEXITCODE handleInternalCommands(HandlerArg *a);
214#endif /* !VBOX_ONLY_DOCS */
215
216/* VBoxManageControlVM.cpp */
217RTEXITCODE handleControlVM(HandlerArg *a);
218
219/* VBoxManageModifyVM.cpp */
220#ifndef VBOX_ONLY_DOCS
221void parseGroups(const char *pcszGroups, com::SafeArray<BSTR> *pGroups);
222# ifdef VBOX_WITH_RECORDING
223int parseScreens(const char *pcszScreens, com::SafeArray<BOOL> *pScreens);
224# endif
225#endif
226RTEXITCODE handleModifyVM(HandlerArg *a);
227
228/* VBoxManageDebugVM.cpp */
229RTEXITCODE handleDebugVM(HandlerArg *a);
230
231#ifndef VBOX_ONLY_DOCS
232/* VBoxManageGuestProp.cpp */
233RTEXITCODE handleGuestProperty(HandlerArg *a);
234
235/* VBoxManageGuestCtrl.cpp */
236RTEXITCODE handleGuestControl(HandlerArg *a);
237
238/* VBoxManageVMInfo.cpp */
239HRESULT showSnapshots(ComPtr<ISnapshot> &rootSnapshot,
240 ComPtr<ISnapshot> &currentSnapshot,
241 VMINFO_DETAILS details,
242 const com::Utf8Str &prefix = "",
243 int level = 0);
244RTEXITCODE handleShowVMInfo(HandlerArg *a);
245HRESULT showVMInfo(ComPtr<IVirtualBox> pVirtualBox,
246 ComPtr<IMachine> pMachine,
247 ComPtr<ISession> pSession,
248 VMINFO_DETAILS details = VMINFO_NONE);
249const char *machineStateToName(MachineState_T machineState, bool fShort);
250HRESULT showBandwidthGroups(ComPtr<IBandwidthControl> &bwCtrl,
251 VMINFO_DETAILS details);
252void outputMachineReadableString(const char *pszName, const char *pszValue, bool fQuoteName = false, bool fNewline = true);
253void outputMachineReadableString(const char *pszName, com::Bstr const *pbstrValue, bool fQuoteName = false, bool fNewline = true);
254void outputMachineReadableStringWithFmtName(const char *pszValue, bool fQuoteName, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
255void outputMachineReadableStringWithFmtName(com::Bstr const *pbstrValue, bool fQuoteName, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
256void outputMachineReadableBool(const char *pszName, BOOL const *pfValue);
257void outputMachineReadableBool(const char *pszName, bool const *pfValue);
258void outputMachineReadableULong(const char *pszName, ULONG *uValue);
259void outputMachineReadableLong64(const char *pszName, LONG64 *uValue);
260
261/* VBoxManageList.cpp */
262RTEXITCODE handleList(HandlerArg *a);
263
264/* VBoxManageMetrics.cpp */
265RTEXITCODE handleMetrics(HandlerArg *a);
266
267/* VBoxManageMisc.cpp */
268RTEXITCODE handleRegisterVM(HandlerArg *a);
269RTEXITCODE handleUnregisterVM(HandlerArg *a);
270RTEXITCODE handleCreateVM(HandlerArg *a);
271RTEXITCODE handleCloneVM(HandlerArg *a);
272RTEXITCODE handleStartVM(HandlerArg *a);
273RTEXITCODE handleDiscardState(HandlerArg *a);
274RTEXITCODE handleAdoptState(HandlerArg *a);
275RTEXITCODE handleGetExtraData(HandlerArg *a);
276RTEXITCODE handleSetExtraData(HandlerArg *a);
277RTEXITCODE handleSetProperty(HandlerArg *a);
278RTEXITCODE handleSharedFolder(HandlerArg *a);
279RTEXITCODE handleExtPack(HandlerArg *a);
280RTEXITCODE handleUnattended(HandlerArg *a);
281RTEXITCODE handleMoveVM(HandlerArg *a);
282RTEXITCODE handleCloudProfile(HandlerArg *a);
283
284/* VBoxManageDisk.cpp */
285HRESULT openMedium(HandlerArg *a, const char *pszFilenameOrUuid,
286 DeviceType_T enmDevType, AccessMode_T enmAccessMode,
287 ComPtr<IMedium> &pMedium, bool fForceNewUuidOnOpen,
288 bool fSilent);
289RTEXITCODE handleCreateMedium(HandlerArg *a);
290RTEXITCODE handleModifyMedium(HandlerArg *a);
291RTEXITCODE handleCloneMedium(HandlerArg *a);
292RTEXITCODE handleMediumProperty(HandlerArg *a);
293RTEXITCODE handleEncryptMedium(HandlerArg *a);
294RTEXITCODE handleCheckMediumPassword(HandlerArg *a);
295RTEXITCODE handleConvertFromRaw(HandlerArg *a);
296HRESULT showMediumInfo(const ComPtr<IVirtualBox> &pVirtualBox,
297 const ComPtr<IMedium> &pMedium,
298 const char *pszParentUUID,
299 bool fOptLong);
300RTEXITCODE handleShowMediumInfo(HandlerArg *a);
301RTEXITCODE handleCloseMedium(HandlerArg *a);
302RTEXITCODE handleMediumIO(HandlerArg *a);
303int parseMediumType(const char *psz, MediumType_T *penmMediumType);
304int parseBool(const char *psz, bool *pb);
305
306/* VBoxManageStorageController.cpp */
307RTEXITCODE handleStorageAttach(HandlerArg *a);
308RTEXITCODE handleStorageController(HandlerArg *a);
309
310// VBoxManageAppliance.cpp
311RTEXITCODE handleImportAppliance(HandlerArg *a);
312RTEXITCODE handleExportAppliance(HandlerArg *a);
313RTEXITCODE handleSignAppliance(HandlerArg *a);
314
315// VBoxManageSnapshot.cpp
316RTEXITCODE handleSnapshot(HandlerArg *a);
317
318/* VBoxManageUSB.cpp */
319RTEXITCODE handleUSBFilter(HandlerArg *a);
320RTEXITCODE handleUSBDevSource(HandlerArg *a);
321
322/* VBoxManageHostonly.cpp */
323RTEXITCODE handleHostonlyIf(HandlerArg *a);
324#ifdef VBOX_WITH_VMNET
325RTEXITCODE handleHostonlyNet(HandlerArg *a);
326#endif /* VBOX_WITH_VMNET */
327
328/* VBoxManageDHCPServer.cpp */
329RTEXITCODE handleDHCPServer(HandlerArg *a);
330
331/* VBoxManageNATNetwork.cpp */
332RTEXITCODE handleNATNetwork(HandlerArg *a);
333RTEXITCODE listNATNetworks(bool fLong, bool fSorted,
334 const ComPtr<IVirtualBox> &pVirtualBox);
335
336/* VBoxManageBandwidthControl.cpp */
337RTEXITCODE handleBandwidthControl(HandlerArg *a);
338
339/* VBoxManageCloud.cpp */
340RTEXITCODE handleCloud(HandlerArg *a);
341
342/* VBoxManageCloudMachine.cpp */
343RTEXITCODE handleCloudMachine(HandlerArg *a, int iFirst,
344 const char *pcszProviderName,
345 const char *pcszProfileName);
346RTEXITCODE listCloudMachines(HandlerArg *a, int iFirst,
347 const char *pcszProviderName,
348 const char *pcszProfileName);
349RTEXITCODE handleCloudShowVMInfo(HandlerArg *a, int iFirst,
350 const char *pcszProviderName,
351 const char *pcszProfileName);
352
353/* VBoxManageUpdateCheck.cpp */
354RTEXITCODE handleUpdateCheck(HandlerArg *a);
355
356/* VBoxManageModifyNvram.cpp */
357RTEXITCODE handleModifyNvram(HandlerArg *a);
358
359#endif /* !VBOX_ONLY_DOCS */
360
361#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