VirtualBox

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

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

VBoxManage: Document DECLARE_TRANSLATION_CONTEXT and fixed prefix mixup. bugref:1909
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 13.2 KB
Line 
1/* $Id: VBoxManage.h 92533 2021-11-21 14:18:55Z vboxsync $ */
2/** @file
3 * VBoxManage - VirtualBox command-line interface, internal header file.
4 */
5
6/*
7 * Copyright (C) 2006-2020 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/** @name Syntax diagram category, i.e. the command.
80 * @{ */
81typedef enum
82{
83 USAGE_INVALID = 0,
84 USAGE_LIST,
85 USAGE_SHOWVMINFO,
86 USAGE_REGISTERVM,
87 USAGE_UNREGISTERVM,
88 USAGE_CREATEVM,
89 USAGE_MODIFYVM,
90 USAGE_STARTVM,
91 USAGE_CONTROLVM,
92 USAGE_DISCARDSTATE,
93 USAGE_CLOSEMEDIUM,
94 USAGE_SHOWMEDIUMINFO,
95 USAGE_CREATEMEDIUM,
96 USAGE_MODIFYMEDIUM,
97 USAGE_CLONEMEDIUM,
98 USAGE_MOVEVM,
99 USAGE_CREATEHOSTIF,
100 USAGE_REMOVEHOSTIF,
101 USAGE_GETEXTRADATA,
102 USAGE_SETEXTRADATA,
103 USAGE_SETPROPERTY,
104 USAGE_USBFILTER,
105 USAGE_I_LOADSYMS,
106 USAGE_I_LOADMAP,
107 USAGE_I_SETHDUUID,
108 USAGE_CONVERTFROMRAW,
109 USAGE_I_LISTPARTITIONS,
110 USAGE_I_CREATERAWVMDK,
111 USAGE_ADOPTSTATE,
112 USAGE_I_MODINSTALL,
113 USAGE_I_MODUNINSTALL,
114 USAGE_I_RENAMEVMDK,
115#ifdef VBOX_WITH_GUEST_PROPS
116 USAGE_GUESTPROPERTY,
117#endif /* VBOX_WITH_GUEST_PROPS defined */
118 USAGE_I_CONVERTTORAW,
119 USAGE_METRICS,
120 USAGE_I_CONVERTHD,
121 USAGE_IMPORTAPPLIANCE,
122 USAGE_EXPORTAPPLIANCE,
123 USAGE_HOSTONLYIFS,
124 USAGE_I_DUMPHDINFO,
125 USAGE_STORAGEATTACH,
126 USAGE_STORAGECONTROLLER,
127#ifdef VBOX_WITH_GUEST_CONTROL
128 USAGE_GUESTCONTROL,
129#endif /* VBOX_WITH_GUEST_CONTROL defined */
130 USAGE_I_DEBUGLOG,
131 USAGE_I_SETHDPARENTUUID,
132 USAGE_I_PASSWORDHASH,
133 USAGE_BANDWIDTHCONTROL,
134 USAGE_I_GUESTSTATS,
135 USAGE_I_REPAIRHD,
136 USAGE_NATNETWORK,
137 USAGE_MEDIUMPROPERTY,
138 USAGE_ENCRYPTMEDIUM,
139 USAGE_MEDIUMENCCHKPWD,
140 USAGE_USBDEVSOURCE,
141 USAGE_CLOUDPROFILE,
142 /* Insert new entries before this line, but only if it is not an option
143 * to go for the new style command and help handling (see e.g. extpack,
144 * unattend or mediumio. */
145 USAGE_S_NEWCMD = 10000, /**< new style command with no old help support */
146 USAGE_S_ALL,
147 USAGE_S_DUMPOPTS
148} USAGECATEGORY;
149/** @} */
150
151
152#define HELP_SCOPE_USBFILTER_ADD RT_BIT_64(0)
153#define HELP_SCOPE_USBFILTER_MODIFY RT_BIT_64(1)
154#define HELP_SCOPE_USBFILTER_REMOVE RT_BIT_64(2)
155
156#ifdef VBOX_WITH_GUEST_CONTROL
157# define HELP_SCOPE_GSTCTRL_RUN RT_BIT(0)
158# define HELP_SCOPE_GSTCTRL_START RT_BIT(1)
159# define HELP_SCOPE_GSTCTRL_COPYFROM RT_BIT(2)
160# define HELP_SCOPE_GSTCTRL_COPYTO RT_BIT(3)
161# define HELP_SCOPE_GSTCTRL_MKDIR RT_BIT(4)
162# define HELP_SCOPE_GSTCTRL_RMDIR RT_BIT(5)
163# define HELP_SCOPE_GSTCTRL_RM RT_BIT(6)
164# define HELP_SCOPE_GSTCTRL_MV RT_BIT(7)
165# define HELP_SCOPE_GSTCTRL_MKTEMP RT_BIT(8)
166# define HELP_SCOPE_GSTCTRL_LIST RT_BIT(9)
167# define HELP_SCOPE_GSTCTRL_CLOSEPROCESS RT_BIT(10)
168# define HELP_SCOPE_GSTCTRL_CLOSESESSION RT_BIT(11)
169# define HELP_SCOPE_GSTCTRL_STAT RT_BIT(12)
170# define HELP_SCOPE_GSTCTRL_UPDATEGA RT_BIT(13)
171# define HELP_SCOPE_GSTCTRL_WATCH RT_BIT(14)
172# define HELP_SCOPE_GSTCTRL_WAITRUNLEVEL RT_BIT(15)
173#endif
174
175/** command handler argument */
176struct HandlerArg
177{
178 int argc;
179 char **argv;
180
181#ifndef VBOX_ONLY_DOCS
182 ComPtr<IVirtualBox> virtualBox;
183 ComPtr<ISession> session;
184#endif
185};
186
187/** flag whether we're in internal mode */
188extern bool g_fInternalMode;
189
190/** showVMInfo details */
191typedef enum
192{
193 VMINFO_NONE = 0,
194 VMINFO_STANDARD = 1, /**< standard details */
195 VMINFO_FULL = 2, /**< both */
196 VMINFO_MACHINEREADABLE = 3, /**< both, and make it machine readable */
197 VMINFO_COMPACT = 4
198} VMINFO_DETAILS;
199
200
201////////////////////////////////////////////////////////////////////////////////
202//
203// global variables
204//
205////////////////////////////////////////////////////////////////////////////////
206
207extern bool g_fDetailedProgress; // in VBoxManage.cpp
208
209
210////////////////////////////////////////////////////////////////////////////////
211//
212// prototypes
213//
214////////////////////////////////////////////////////////////////////////////////
215
216/* VBoxManageHelp.cpp */
217
218/* Legacy help infrastructure, to be replaced by new one using generated help. */
219void printUsage(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm);
220RTEXITCODE errorSyntax(USAGECATEGORY enmCommand, const char *pszFormat, ...);
221RTEXITCODE errorSyntaxEx(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, const char *pszFormat, ...);
222RTEXITCODE errorGetOpt(USAGECATEGORY enmCommand, int rc, union RTGETOPTUNION const *pValueUnion);
223RTEXITCODE errorGetOptEx(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, int rc, union RTGETOPTUNION const *pValueUnion);
224RTEXITCODE errorArgument(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
225
226void printUsageInternal(USAGECATEGORY enmCommand, PRTSTREAM pStrm);
227
228#ifndef VBOX_ONLY_DOCS
229void setCurrentCommand(enum HELP_CMD_VBOXMANAGE enmCommand);
230void setCurrentSubcommand(uint64_t fCurSubcommandScope);
231
232void printUsage(PRTSTREAM pStrm);
233void printHelp(PRTSTREAM pStrm);
234RTEXITCODE errorNoSubcommand(void);
235RTEXITCODE errorUnknownSubcommand(const char *pszSubCmd);
236RTEXITCODE errorTooManyParameters(char **papszArgs);
237RTEXITCODE errorGetOpt(int rcGetOpt, union RTGETOPTUNION const *pValueUnion);
238RTEXITCODE errorFetchValue(int iValueNo, const char *pszOption, int rcGetOptFetchValue, union RTGETOPTUNION const *pValueUnion);
239RTEXITCODE errorSyntax(const char *pszFormat, ...);
240
241
242#define SHOW_PROGRESS_NONE 0
243#define SHOW_PROGRESS_DESC (1u << 0)
244#define SHOW_PROGRESS (1u << 1)
245#define SHOW_PROGRESS_DETAILS (1u << 2)
246HRESULT showProgress(ComPtr<IProgress> progress, unsigned int fFlags = SHOW_PROGRESS);
247#endif
248
249/* VBoxManage.cpp */
250void showLogo(PRTSTREAM pStrm);
251
252#ifndef VBOX_ONLY_DOCS
253RTEXITCODE handleInternalCommands(HandlerArg *a);
254#endif /* !VBOX_ONLY_DOCS */
255
256/* VBoxManageControlVM.cpp */
257RTEXITCODE handleControlVM(HandlerArg *a);
258
259/* VBoxManageModifyVM.cpp */
260#ifndef VBOX_ONLY_DOCS
261void parseGroups(const char *pcszGroups, com::SafeArray<BSTR> *pGroups);
262#endif
263RTEXITCODE handleModifyVM(HandlerArg *a);
264
265/* VBoxManageDebugVM.cpp */
266RTEXITCODE handleDebugVM(HandlerArg *a);
267
268/* VBoxManageGuestProp.cpp */
269extern void usageGuestProperty(PRTSTREAM pStrm, const char *pcszSep1, const char *pcszSep2);
270
271/* VBoxManageGuestCtrl.cpp */
272extern void usageGuestControl(PRTSTREAM pStrm, const char *pcszSep1, const char *pcszSep2, uint64_t fSubcommandScope);
273
274#ifndef VBOX_ONLY_DOCS
275/* VBoxManageGuestProp.cpp */
276RTEXITCODE handleGuestProperty(HandlerArg *a);
277
278/* VBoxManageGuestCtrl.cpp */
279RTEXITCODE handleGuestControl(HandlerArg *a);
280
281/* VBoxManageVMInfo.cpp */
282HRESULT showSnapshots(ComPtr<ISnapshot> &rootSnapshot,
283 ComPtr<ISnapshot> &currentSnapshot,
284 VMINFO_DETAILS details,
285 const com::Utf8Str &prefix = "",
286 int level = 0);
287RTEXITCODE handleShowVMInfo(HandlerArg *a);
288HRESULT showVMInfo(ComPtr<IVirtualBox> pVirtualBox,
289 ComPtr<IMachine> pMachine,
290 ComPtr<ISession> pSession,
291 VMINFO_DETAILS details = VMINFO_NONE);
292const char *machineStateToName(MachineState_T machineState, bool fShort);
293HRESULT showBandwidthGroups(ComPtr<IBandwidthControl> &bwCtrl,
294 VMINFO_DETAILS details);
295void outputMachineReadableString(const char *pszName, const char *pszValue);
296void outputMachineReadableString(const char *pszName, com::Bstr const *pbstrValue);
297void outputMachineReadableBool(const char *pszName, BOOL const *pfValue);
298void outputMachineReadableBool(const char *pszName, bool const *pfValue);
299void outputMachineReadableULong(const char *pszName, ULONG *uValue);
300void outputMachineReadableLong64(const char *pszName, LONG64 *uValue);
301
302/* VBoxManageList.cpp */
303RTEXITCODE handleList(HandlerArg *a);
304
305/* VBoxManageMetrics.cpp */
306RTEXITCODE handleMetrics(HandlerArg *a);
307
308/* VBoxManageMisc.cpp */
309RTEXITCODE handleRegisterVM(HandlerArg *a);
310RTEXITCODE handleUnregisterVM(HandlerArg *a);
311RTEXITCODE handleCreateVM(HandlerArg *a);
312RTEXITCODE handleCloneVM(HandlerArg *a);
313RTEXITCODE handleStartVM(HandlerArg *a);
314RTEXITCODE handleDiscardState(HandlerArg *a);
315RTEXITCODE handleAdoptState(HandlerArg *a);
316RTEXITCODE handleGetExtraData(HandlerArg *a);
317RTEXITCODE handleSetExtraData(HandlerArg *a);
318RTEXITCODE handleSetProperty(HandlerArg *a);
319RTEXITCODE handleSharedFolder(HandlerArg *a);
320RTEXITCODE handleExtPack(HandlerArg *a);
321RTEXITCODE handleUnattended(HandlerArg *a);
322RTEXITCODE handleMoveVM(HandlerArg *a);
323RTEXITCODE handleCloudProfile(HandlerArg *a);
324
325/* VBoxManageDisk.cpp */
326HRESULT openMedium(HandlerArg *a, const char *pszFilenameOrUuid,
327 DeviceType_T enmDevType, AccessMode_T enmAccessMode,
328 ComPtr<IMedium> &pMedium, bool fForceNewUuidOnOpen,
329 bool fSilent);
330RTEXITCODE handleCreateMedium(HandlerArg *a);
331RTEXITCODE handleModifyMedium(HandlerArg *a);
332RTEXITCODE handleCloneMedium(HandlerArg *a);
333RTEXITCODE handleMediumProperty(HandlerArg *a);
334RTEXITCODE handleEncryptMedium(HandlerArg *a);
335RTEXITCODE handleCheckMediumPassword(HandlerArg *a);
336RTEXITCODE handleConvertFromRaw(HandlerArg *a);
337HRESULT showMediumInfo(const ComPtr<IVirtualBox> &pVirtualBox,
338 const ComPtr<IMedium> &pMedium,
339 const char *pszParentUUID,
340 bool fOptLong);
341RTEXITCODE handleShowMediumInfo(HandlerArg *a);
342RTEXITCODE handleCloseMedium(HandlerArg *a);
343RTEXITCODE handleMediumIO(HandlerArg *a);
344int parseMediumType(const char *psz, MediumType_T *penmMediumType);
345int parseBool(const char *psz, bool *pb);
346
347/* VBoxManageStorageController.cpp */
348RTEXITCODE handleStorageAttach(HandlerArg *a);
349RTEXITCODE handleStorageController(HandlerArg *a);
350
351// VBoxManageAppliance.cpp
352RTEXITCODE handleImportAppliance(HandlerArg *a);
353RTEXITCODE handleExportAppliance(HandlerArg *a);
354RTEXITCODE handleSignAppliance(HandlerArg *a);
355
356// VBoxManageSnapshot.cpp
357RTEXITCODE handleSnapshot(HandlerArg *a);
358
359/* VBoxManageUSB.cpp */
360RTEXITCODE handleUSBFilter(HandlerArg *a);
361RTEXITCODE handleUSBDevSource(HandlerArg *a);
362
363/* VBoxManageHostonly.cpp */
364RTEXITCODE handleHostonlyIf(HandlerArg *a);
365#ifdef VBOX_WITH_VMNET
366RTEXITCODE handleHostonlyNet(HandlerArg *a);
367#endif /* VBOX_WITH_VMNET */
368
369/* VBoxManageDHCPServer.cpp */
370RTEXITCODE handleDHCPServer(HandlerArg *a);
371
372/* VBoxManageNATNetwork.cpp */
373RTEXITCODE handleNATNetwork(HandlerArg *a);
374
375
376/* VBoxManageBandwidthControl.cpp */
377RTEXITCODE handleBandwidthControl(HandlerArg *a);
378
379/* VBoxManageCloud.cpp */
380RTEXITCODE handleCloud(HandlerArg *a);
381
382/* VBoxManageCloudMachine.cpp */
383RTEXITCODE handleCloudMachine(HandlerArg *a, int iFirst,
384 const char *pcszProviderName,
385 const char *pcszProfileName);
386RTEXITCODE listCloudMachines(HandlerArg *a, int iFirst,
387 const char *pcszProviderName,
388 const char *pcszProfileName);
389RTEXITCODE handleCloudShowVMInfo(HandlerArg *a, int iFirst,
390 const char *pcszProviderName,
391 const char *pcszProfileName);
392
393/* VBoxManageUpdateCheck.cpp */
394RTEXITCODE handleUpdateCheck(HandlerArg *a);
395
396/* VBoxManageModifyNvram.cpp */
397RTEXITCODE handleModifyNvram(HandlerArg *a);
398
399#endif /* !VBOX_ONLY_DOCS */
400
401#endif /* !VBOX_INCLUDED_SRC_VBoxManage_VBoxManage_h */
Note: See TracBrowser for help on using the repository browser.

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