VirtualBox

source: vbox/trunk/src/VBox/Frontends/VBoxAutostart/VBoxAutostart.h

Last change on this file was 99739, checked in by vboxsync, 14 months ago

*: doxygen corrections (mostly about removing @returns from functions returning void).

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.3 KB
Line 
1/* $Id: VBoxAutostart.h 99739 2023-05-11 01:01:08Z vboxsync $ */
2/** @file
3 * VBoxAutostart - VirtualBox Autostart service.
4 */
5
6/*
7 * Copyright (C) 2012-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * SPDX-License-Identifier: GPL-3.0-only
26 */
27
28#ifndef VBOX_INCLUDED_SRC_VBoxAutostart_VBoxAutostart_h
29#define VBOX_INCLUDED_SRC_VBoxAutostart_VBoxAutostart_h
30#ifndef RT_WITHOUT_PRAGMA_ONCE
31# pragma once
32#endif
33
34/*******************************************************************************
35* Header Files *
36*******************************************************************************/
37#include <iprt/getopt.h>
38#include <iprt/types.h>
39
40#include <VBox/cdefs.h>
41#include <VBox/types.h>
42
43#include <VBox/com/com.h>
44#include <VBox/com/VirtualBox.h>
45
46/*******************************************************************************
47* Constants And Macros, Structures and Typedefs *
48*******************************************************************************/
49
50/**
51 * Config AST node types.
52 */
53typedef enum CFGASTNODETYPE
54{
55 /** Invalid. */
56 CFGASTNODETYPE_INVALID = 0,
57 /** Key/Value pair. */
58 CFGASTNODETYPE_KEYVALUE,
59 /** Compound type. */
60 CFGASTNODETYPE_COMPOUND,
61 /** List type. */
62 CFGASTNODETYPE_LIST,
63 /** 32bit hack. */
64 CFGASTNODETYPE_32BIT_HACK = 0x7fffffff
65} CFGASTNODETYPE;
66/** Pointer to a config AST node type. */
67typedef CFGASTNODETYPE *PCFGASTNODETYPE;
68/** Pointer to a const config AST node type. */
69typedef const CFGASTNODETYPE *PCCFGASTNODETYPE;
70
71/**
72 * Config AST.
73 */
74typedef struct CFGAST
75{
76 /** AST node type. */
77 CFGASTNODETYPE enmType;
78 /** Key or scope id. */
79 char *pszKey;
80 /** Type dependent data. */
81 union
82 {
83 /** Key value pair. */
84 struct
85 {
86 /** Number of characters in the value - excluding terminator. */
87 size_t cchValue;
88 /** Value string - variable in size. */
89 char aszValue[1];
90 } KeyValue;
91 /** Compound type. */
92 struct
93 {
94 /** Number of AST node entries in the array. */
95 unsigned cAstNodes;
96 /** AST node array - variable in size. */
97 struct CFGAST *apAstNodes[1];
98 } Compound;
99 /** List type. */
100 struct
101 {
102 /** Number of entries in the list. */
103 unsigned cListEntries;
104 /** Array of list entries - variable in size. */
105 char *apszEntries[1];
106 } List;
107 } u;
108} CFGAST, *PCFGAST;
109
110/** Flag whether we are in verbose logging mode. */
111extern bool g_fVerbose;
112/** Handle to the VirtualBox interface. */
113extern ComPtr<IVirtualBox> g_pVirtualBox;
114/** Handle to the session interface. */
115extern ComPtr<ISession> g_pSession;
116/** handle to the VirtualBox interface. */
117extern ComPtr<IVirtualBoxClient> g_pVirtualBoxClient;
118/**
119 * System log type.
120 */
121typedef enum AUTOSTARTLOGTYPE
122{
123 /** Invalid log type. */
124 AUTOSTARTLOGTYPE_INVALID = 0,
125 /** Log info message. */
126 AUTOSTARTLOGTYPE_INFO,
127 /** Log error message. */
128 AUTOSTARTLOGTYPE_ERROR,
129 /** Log warning message. */
130 AUTOSTARTLOGTYPE_WARNING,
131 /** Log verbose message, only if verbose mode is activated. */
132 AUTOSTARTLOGTYPE_VERBOSE,
133 /** Famous 32bit hack. */
134 AUTOSTARTLOGTYPE_32BIT_HACK = 0x7fffffff
135} AUTOSTARTLOGTYPE;
136
137/**
138 * Prints the service header header (product name, version, ++) to stdout.
139 */
140DECLHIDDEN(void) autostartSvcShowHeader(void);
141
142/**
143 * Prints the service version information header to stdout.
144 *
145 * @param fBrief Whether to show brief information or not.
146 */
147DECLHIDDEN(void) autostartSvcShowVersion(bool fBrief);
148
149/**
150 * Log messages to the system and release log.
151 *
152 * @param pszMsg Message to log.
153 * @param enmLogType Log type to use.
154 */
155DECLHIDDEN(void) autostartSvcOsLogStr(const char *pszMsg, AUTOSTARTLOGTYPE enmLogType);
156
157/**
158 * Print out progress on the console.
159 *
160 * This runs the main event queue every now and then to prevent piling up
161 * unhandled things (which doesn't cause real problems, just makes things
162 * react a little slower than in the ideal case).
163 */
164DECLHIDDEN(HRESULT) showProgress(ComPtr<IProgress> progress);
165
166/**
167 * Converts the machine state to a human readable string.
168 *
169 * @returns Pointer to the human readable state.
170 * @param enmMachineState Machine state to convert.
171 * @param fShort Flag whether to return a short form.
172 */
173DECLHIDDEN(const char *) machineStateToName(MachineState_T enmMachineState, bool fShort);
174
175/**
176 * Parse the given configuration file and return the interesting config parameters.
177 *
178 * @returns VBox status code.
179 * @param pszFilename The config file to parse.
180 * @param ppCfgAst Where to store the pointer to the root AST node on success.
181 */
182DECLHIDDEN(int) autostartParseConfig(const char *pszFilename, PCFGAST *ppCfgAst);
183
184/**
185 * Destroys the config AST and frees all resources.
186 *
187 * @param pCfgAst The config AST.
188 */
189DECLHIDDEN(void) autostartConfigAstDestroy(PCFGAST pCfgAst);
190
191/**
192 * Return the config AST node with the given name or NULL if it doesn't exist.
193 *
194 * @returns Matching config AST node for the given name or NULL if not found.
195 * @param pCfgAst The config ASt to search.
196 * @param pszName The name to search for.
197 */
198DECLHIDDEN(PCFGAST) autostartConfigAstGetByName(PCFGAST pCfgAst, const char *pszName);
199
200/**
201 * Main routine for the autostart daemon.
202 *
203 * @returns VBox status code.
204 * @param pCfgAst Config AST for the startup part of the autostart daemon.
205 */
206DECLHIDDEN(int) autostartStartMain(PCFGAST pCfgAst);
207
208/**
209 * Main routine for the autostart daemon when stopping virtual machines
210 * during system shutdown.
211 *
212 * @returns VBox status code.
213 * @param pCfgAst Config AST for the shutdown part of the autostart daemon.
214 */
215DECLHIDDEN(int) autostartStopMain(PCFGAST pCfgAst);
216
217/**
218 * Logs a verbose message to the appropriate system log and stdout + release log (if configured).
219 *
220 * @param cVerbosity Verbosity level when logging should happen.
221 * @param pszFormat The log string. No trailing newline.
222 * @param ... Format arguments.
223 */
224DECLHIDDEN(void) autostartSvcLogVerboseV(unsigned cVerbosity, const char *pszFormat, va_list va);
225
226/**
227 * Logs a verbose message to the appropriate system log and stdout + release log (if configured).
228 *
229 * @param cVerbosity Verbosity level when logging should happen.
230 * @param pszFormat The log string. No trailing newline.
231 * @param ... Format arguments.
232 */
233DECLHIDDEN(void) autostartSvcLogVerbose(unsigned cVerbosity, const char *pszFormat, ...);
234
235/**
236 * Logs a warning message to the appropriate system log and stdout + release log (if configured).
237 *
238 * @param pszFormat The log string. No trailing newline.
239 * @param ... Format arguments.
240 */
241DECLHIDDEN(void) autostartSvcLogWarningV(const char *pszFormat, va_list va);
242
243/**
244 * Logs a warning message to the appropriate system log and stdout + release log (if configured).
245 *
246 * @param pszFormat The log string. No trailing newline.
247 * @param ... Format arguments.
248 */
249DECLHIDDEN(void) autostartSvcLogWarning(const char *pszFormat, ...);
250
251/**
252 * Logs a info message to the appropriate system log and stdout + release log (if configured).
253 *
254 * @param pszFormat The log string. No trailing newline.
255 * @param ... Format arguments.
256 */
257DECLHIDDEN(void) autostartSvcLogInfoV(const char *pszFormat, va_list va);
258
259/**
260 * Logs a info message to the appropriate system log and stdout + release log (if configured).
261 *
262 * @param pszFormat The log string. No trailing newline.
263 * @param ... Format arguments.
264 */
265DECLHIDDEN(void) autostartSvcLogInfo(const char *pszFormat, ...);
266
267/**
268 * Logs the message to the appropriate system log and stderr + release log (if configured).
269 *
270 * In debug builds this will also put it in the debug log.
271 *
272 * @returns VBox status code.
273 * @param pszFormat The log string. No trailing newline.
274 * @param ... Format arguments.
275 */
276DECLHIDDEN(int) autostartSvcLogErrorV(const char *pszFormat, va_list va);
277
278/**
279 * Logs the message to the appropriate system log and stderr + release log (if configured).
280 *
281 * In debug builds this will also put it in the debug log.
282 *
283 * @returns VBox status code.
284 * @param pszFormat The log string. No trailing newline.
285 * @param ... Format arguments.
286 */
287DECLHIDDEN(int) autostartSvcLogError(const char *pszFormat, ...);
288
289/**
290 * Logs the message to the appropriate system log.
291 *
292 * In debug builds this will also put it in the debug log.
293 *
294 * @returns VBox status code specified by \a rc.
295 * @param pszFormat The log string. No trailing newline.
296 * @param ... Format arguments.
297 *
298 * @note Convenience function to return directly with the specified \a rc.
299 */
300DECLHIDDEN(int) autostartSvcLogErrorRcV(int rc, const char *pszFormat, va_list va);
301
302/**
303 * Logs the error message to the appropriate system log.
304 *
305 * In debug builds this will also put it in the debug log.
306 *
307 * @returns VBox status code specified by \a rc.
308 * @param pszFormat The log string. No trailing newline.
309 * @param ... Format arguments.
310 *
311 * @note Convenience function to return directly with the specified \a rc.
312 */
313DECLHIDDEN(int) autostartSvcLogErrorRc(int rc, const char *pszFormat, ...);
314
315/**
316 * Deals with RTGetOpt failure, bitching in the system log.
317 *
318 * @returns VBox status code specified by \a rc.
319 * @param pszAction The action name.
320 * @param rc The RTGetOpt return value.
321 * @param argc The argument count.
322 * @param argv The argument vector.
323 * @param iArg The argument index.
324 * @param pValue The value returned by RTGetOpt.
325 */
326DECLHIDDEN(int) autostartSvcLogGetOptError(const char *pszAction, int rc, int argc, char **argv, int iArg, PCRTGETOPTUNION pValue);
327
328/**
329 * Bitch about too many arguments (after RTGetOpt stops) in the system log.
330 *
331 * @returns VERR_INVALID_PARAMETER
332 * @param pszAction The action name.
333 * @param argc The argument count.
334 * @param argv The argument vector.
335 * @param iArg The argument index.
336 */
337DECLHIDDEN(int) autostartSvcLogTooManyArgsError(const char *pszAction, int argc, char **argv, int iArg);
338
339/**
340 * Prints an error message to the screen.
341 *
342 * @returns RTEXITCODE
343 * @param pszFormat The message format string.
344 * @param va Format arguments.
345 */
346DECLHIDDEN(RTEXITCODE) autostartSvcDisplayErrorV(const char *pszFormat, va_list va);
347
348/**
349 * Prints an error message to the screen.
350 *
351 * @returns RTEXITCODE
352 * @param pszFormat The message format string.
353 * @param ... Format arguments.
354 */
355DECLHIDDEN(RTEXITCODE) autostartSvcDisplayError(const char *pszFormat, ...);
356
357/**
358 * Deals with RTGetOpt failure, i.e. an syntax error.
359 *
360 * @returns RTEXITCODE_SYNTAX
361 * @param pszAction The action name.
362 * @param rc The RTGetOpt return value.
363 * @param pValue The value returned by RTGetOpt.
364 */
365DECLHIDDEN(RTEXITCODE) autostartSvcDisplayGetOptError(const char *pszAction, int rc, PCRTGETOPTUNION pValue);
366
367/**
368 * Starts the autostart environment by initializing all needed (global) objects.
369 *
370 * @returns VBox status code.
371 *
372 * @note This currently does NOT support multiple instances, be aware of this!
373 */
374DECLHIDDEN(int) autostartSetup(void);
375
376/**
377 * Stops the autostart environment.
378 *
379 * @note This currently does NOT support multiple instances, be aware of this!
380 */
381DECLHIDDEN(void) autostartShutdown(void);
382
383#endif /* !VBOX_INCLUDED_SRC_VBoxAutostart_VBoxAutostart_h */
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
ContactPrivacy policyTerms of Use