VirtualBox

source: vbox/trunk/include/VBox/vmm/cfgm.h@ 93963

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

VMM,Main,HostServices: Use a function table for accessing the VBoxVMM.dll/so/dylib functionality, and load it dynamically when the Console object is initialized. Also converted a few drivers in Main to use device helpers to get config values and such. bugref:10074
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.9 KB
Line 
1/** @file
2 * CFGM - Configuration Manager.
3 */
4
5/*
6 * Copyright (C) 2006-2022 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef VBOX_INCLUDED_vmm_cfgm_h
27#define VBOX_INCLUDED_vmm_cfgm_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <VBox/types.h>
33#include <iprt/stdarg.h>
34
35/** @defgroup grp_cfgm The Configuration Manager API
36 * @ingroup grp_vmm
37 * @{
38 */
39
40/**
41 * Configuration manager value type.
42 */
43typedef enum CFGMVALUETYPE
44{
45 /** Integer value. */
46 CFGMVALUETYPE_INTEGER = 1,
47 /** String value. */
48 CFGMVALUETYPE_STRING,
49 /** Bytestring value. */
50 CFGMVALUETYPE_BYTES,
51 /** Password value, same as String but hides the content in dump. */
52 CFGMVALUETYPE_PASSWORD
53} CFGMVALUETYPE;
54/** Pointer to configuration manager property type. */
55typedef CFGMVALUETYPE *PCFGMVALUETYPE;
56
57
58
59RT_C_DECLS_BEGIN
60
61#ifdef IN_RING3
62/** @defgroup grp_cfgm_r3 The CFGM Host Context Ring-3 API
63 * @{
64 */
65
66typedef enum CFGMCONFIGTYPE
67{
68 /** pvConfig points to nothing, use defaults. */
69 CFGMCONFIGTYPE_NONE = 0,
70 /** pvConfig points to a IMachine interface. */
71 CFGMCONFIGTYPE_IMACHINE
72} CFGMCONFIGTYPE;
73
74
75/**
76 * CFGM init callback for constructing the configuration tree.
77 *
78 * This is called from the emulation thread, and the one interfacing the VM
79 * can make any necessary per-thread initializations at this point.
80 *
81 * @returns VBox status code.
82 * @param pUVM The user mode VM handle.
83 * @param pVM The cross context VM structure.
84 * @param pVMM The VMM R3 vtable.
85 * @param pvUser The argument supplied to VMR3Create().
86 */
87typedef DECLCALLBACKTYPE(int, FNCFGMCONSTRUCTOR,(PUVM pUVM, PVM pVM, PCVMMR3VTABLE pVMM, void *pvUser));
88/** Pointer to a FNCFGMCONSTRUCTOR(). */
89typedef FNCFGMCONSTRUCTOR *PFNCFGMCONSTRUCTOR;
90
91VMMR3DECL(int) CFGMR3Init(PVM pVM, PFNCFGMCONSTRUCTOR pfnCFGMConstructor, void *pvUser);
92VMMR3DECL(int) CFGMR3Term(PVM pVM);
93VMMR3DECL(int) CFGMR3ConstructDefaultTree(PVM pVM);
94
95VMMR3DECL(PCFGMNODE) CFGMR3CreateTree(PUVM pUVM);
96VMMR3DECL(int) CFGMR3DestroyTree(PCFGMNODE pRoot);
97VMMR3DECL(void) CFGMR3Dump(PCFGMNODE pRoot);
98VMMR3DECL(int) CFGMR3DuplicateSubTree(PCFGMNODE pRoot, PCFGMNODE *ppCopy);
99VMMR3DECL(int) CFGMR3ReplaceSubTree(PCFGMNODE pRoot, PCFGMNODE pNewRoot);
100VMMR3DECL(int) CFGMR3InsertSubTree(PCFGMNODE pNode, const char *pszName, PCFGMNODE pSubTree, PCFGMNODE *ppChild);
101VMMR3DECL(int) CFGMR3InsertNode(PCFGMNODE pNode, const char *pszName, PCFGMNODE *ppChild);
102VMMR3DECL(int) CFGMR3InsertNodeF(PCFGMNODE pNode, PCFGMNODE *ppChild,
103 const char *pszNameFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
104VMMR3DECL(int) CFGMR3InsertNodeFV(PCFGMNODE pNode, PCFGMNODE *ppChild,
105 const char *pszNameFormat, va_list Args) RT_IPRT_FORMAT_ATTR(3, 0);
106VMMR3DECL(void) CFGMR3SetRestrictedRoot(PCFGMNODE pNode);
107VMMR3DECL(void) CFGMR3RemoveNode(PCFGMNODE pNode);
108VMMR3DECL(int) CFGMR3InsertInteger(PCFGMNODE pNode, const char *pszName, uint64_t u64Integer);
109VMMR3DECL(int) CFGMR3InsertString(PCFGMNODE pNode, const char *pszName, const char *pszString);
110VMMR3DECL(int) CFGMR3InsertStringN(PCFGMNODE pNode, const char *pszName, const char *pszString, size_t cchString);
111VMMR3DECL(int) CFGMR3InsertStringF(PCFGMNODE pNode, const char *pszName,
112 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
113VMMR3DECL(int) CFGMR3InsertStringFV(PCFGMNODE pNode, const char *pszName,
114 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
115VMMR3DECL(int) CFGMR3InsertStringW(PCFGMNODE pNode, const char *pszName, PCRTUTF16 pwszValue);
116VMMR3DECL(int) CFGMR3InsertBytes(PCFGMNODE pNode, const char *pszName, const void *pvBytes, size_t cbBytes);
117VMMR3DECL(int) CFGMR3InsertPassword(PCFGMNODE pNode, const char *pszName, const char *pszString);
118VMMR3DECL(int) CFGMR3InsertPasswordN(PCFGMNODE pNode, const char *pszName, const char *pszString, size_t cchString);
119VMMR3DECL(int) CFGMR3InsertValue(PCFGMNODE pNode, PCFGMLEAF pValue);
120VMMR3DECL(int) CFGMR3RemoveValue(PCFGMNODE pNode, const char *pszName);
121
122/** @name CFGMR3CopyTree flags.
123 * @{ */
124/** Reserved value disposition \#0. */
125#define CFGM_COPY_FLAGS_RESERVED_VALUE_DISP_0 UINT32_C(0x00000000)
126/** Reserved value disposition \#1. */
127#define CFGM_COPY_FLAGS_RESERVED_VALUE_DISP_1 UINT32_C(0x00000001)
128/** Replace exiting values. */
129#define CFGM_COPY_FLAGS_REPLACE_VALUES UINT32_C(0x00000002)
130/** Ignore exiting values. */
131#define CFGM_COPY_FLAGS_IGNORE_EXISTING_VALUES UINT32_C(0x00000003)
132/** Value disposition mask. */
133#define CFGM_COPY_FLAGS_VALUE_DISP_MASK UINT32_C(0x00000003)
134
135/** Replace exiting keys. */
136#define CFGM_COPY_FLAGS_RESERVED_KEY_DISP UINT32_C(0x00000000)
137/** Replace exiting keys. */
138#define CFGM_COPY_FLAGS_MERGE_KEYS UINT32_C(0x00000010)
139/** Replace exiting keys. */
140#define CFGM_COPY_FLAGS_REPLACE_KEYS UINT32_C(0x00000020)
141/** Ignore existing keys. */
142#define CFGM_COPY_FLAGS_IGNORE_EXISTING_KEYS UINT32_C(0x00000030)
143/** Key disposition. */
144#define CFGM_COPY_FLAGS_KEY_DISP_MASK UINT32_C(0x00000030)
145/** @} */
146VMMR3DECL(int) CFGMR3CopyTree(PCFGMNODE pDstTree, PCFGMNODE pSrcTree, uint32_t fFlags);
147
148VMMR3DECL(bool) CFGMR3Exists( PCFGMNODE pNode, const char *pszName);
149VMMR3DECL(int) CFGMR3QueryType( PCFGMNODE pNode, const char *pszName, PCFGMVALUETYPE penmType);
150VMMR3DECL(int) CFGMR3QuerySize( PCFGMNODE pNode, const char *pszName, size_t *pcb);
151VMMR3DECL(int) CFGMR3QueryInteger( PCFGMNODE pNode, const char *pszName, uint64_t *pu64);
152VMMR3DECL(int) CFGMR3QueryIntegerDef( PCFGMNODE pNode, const char *pszName, uint64_t *pu64, uint64_t u64Def);
153VMMR3DECL(int) CFGMR3QueryString( PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString);
154VMMR3DECL(int) CFGMR3QueryStringDef( PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString, const char *pszDef);
155VMMR3DECL(int) CFGMR3QueryPassword( PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString);
156VMMR3DECL(int) CFGMR3QueryPasswordDef( PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString, const char *pszDef);
157VMMR3DECL(int) CFGMR3QueryBytes( PCFGMNODE pNode, const char *pszName, void *pvData, size_t cbData);
158
159
160/** @name Helpers
161 * @{
162 */
163VMMR3DECL(int) CFGMR3QueryU64( PCFGMNODE pNode, const char *pszName, uint64_t *pu64);
164VMMR3DECL(int) CFGMR3QueryU64Def( PCFGMNODE pNode, const char *pszName, uint64_t *pu64, uint64_t u64Def);
165VMMR3DECL(int) CFGMR3QueryS64( PCFGMNODE pNode, const char *pszName, int64_t *pi64);
166VMMR3DECL(int) CFGMR3QueryS64Def( PCFGMNODE pNode, const char *pszName, int64_t *pi64, int64_t i64Def);
167VMMR3DECL(int) CFGMR3QueryU32( PCFGMNODE pNode, const char *pszName, uint32_t *pu32);
168VMMR3DECL(int) CFGMR3QueryU32Def( PCFGMNODE pNode, const char *pszName, uint32_t *pu32, uint32_t u32Def);
169VMMR3DECL(int) CFGMR3QueryS32( PCFGMNODE pNode, const char *pszName, int32_t *pi32);
170VMMR3DECL(int) CFGMR3QueryS32Def( PCFGMNODE pNode, const char *pszName, int32_t *pi32, int32_t i32Def);
171VMMR3DECL(int) CFGMR3QueryU16( PCFGMNODE pNode, const char *pszName, uint16_t *pu16);
172VMMR3DECL(int) CFGMR3QueryU16Def( PCFGMNODE pNode, const char *pszName, uint16_t *pu16, uint16_t u16Def);
173VMMR3DECL(int) CFGMR3QueryS16( PCFGMNODE pNode, const char *pszName, int16_t *pi16);
174VMMR3DECL(int) CFGMR3QueryS16Def( PCFGMNODE pNode, const char *pszName, int16_t *pi16, int16_t i16Def);
175VMMR3DECL(int) CFGMR3QueryU8( PCFGMNODE pNode, const char *pszName, uint8_t *pu8);
176VMMR3DECL(int) CFGMR3QueryU8Def( PCFGMNODE pNode, const char *pszName, uint8_t *pu8, uint8_t u8Def);
177VMMR3DECL(int) CFGMR3QueryS8( PCFGMNODE pNode, const char *pszName, int8_t *pi8);
178VMMR3DECL(int) CFGMR3QueryS8Def( PCFGMNODE pNode, const char *pszName, int8_t *pi8, int8_t i8Def);
179VMMR3DECL(int) CFGMR3QueryBool( PCFGMNODE pNode, const char *pszName, bool *pf);
180VMMR3DECL(int) CFGMR3QueryBoolDef( PCFGMNODE pNode, const char *pszName, bool *pf, bool fDef);
181VMMR3DECL(int) CFGMR3QueryPort( PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort);
182VMMR3DECL(int) CFGMR3QueryPortDef( PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort, RTIOPORT PortDef);
183VMMR3DECL(int) CFGMR3QueryUInt( PCFGMNODE pNode, const char *pszName, unsigned int *pu);
184VMMR3DECL(int) CFGMR3QueryUIntDef( PCFGMNODE pNode, const char *pszName, unsigned int *pu, unsigned int uDef);
185VMMR3DECL(int) CFGMR3QuerySInt( PCFGMNODE pNode, const char *pszName, signed int *pi);
186VMMR3DECL(int) CFGMR3QuerySIntDef( PCFGMNODE pNode, const char *pszName, signed int *pi, signed int iDef);
187VMMR3DECL(int) CFGMR3QueryPtr( PCFGMNODE pNode, const char *pszName, void **ppv);
188VMMR3DECL(int) CFGMR3QueryPtrDef( PCFGMNODE pNode, const char *pszName, void **ppv, void *pvDef);
189VMMR3DECL(int) CFGMR3QueryGCPtr( PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr);
190VMMR3DECL(int) CFGMR3QueryGCPtrDef( PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr, RTGCPTR GCPtrDef);
191VMMR3DECL(int) CFGMR3QueryGCPtrU( PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr);
192VMMR3DECL(int) CFGMR3QueryGCPtrUDef( PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr, RTGCUINTPTR GCPtrDef);
193VMMR3DECL(int) CFGMR3QueryGCPtrS( PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr);
194VMMR3DECL(int) CFGMR3QueryGCPtrSDef( PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr, RTGCINTPTR GCPtrDef);
195VMMR3DECL(int) CFGMR3QueryStringAlloc( PCFGMNODE pNode, const char *pszName, char **ppszString);
196VMMR3DECL(int) CFGMR3QueryStringAllocDef(PCFGMNODE pNode, const char *pszName, char **ppszString, const char *pszDef);
197
198/** @} */
199
200/** @name Tree Navigation and Enumeration.
201 * @{
202 */
203VMMR3DECL(PCFGMNODE) CFGMR3GetRoot(PVM pVM);
204VMMR3DECL(PCFGMNODE) CFGMR3GetRootU(PUVM pUVM);
205VMMR3DECL(PCFGMNODE) CFGMR3GetParent(PCFGMNODE pNode);
206VMMR3DECL(PCFGMNODE) CFGMR3GetParentEx(PVM pVM, PCFGMNODE pNode);
207VMMR3DECL(PCFGMNODE) CFGMR3GetChild(PCFGMNODE pNode, const char *pszPath);
208VMMR3DECL(PCFGMNODE) CFGMR3GetChildF(PCFGMNODE pNode, const char *pszPathFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
209VMMR3DECL(PCFGMNODE) CFGMR3GetChildFV(PCFGMNODE pNode, const char *pszPathFormat, va_list Args) RT_IPRT_FORMAT_ATTR(3, 0);
210VMMR3DECL(PCFGMNODE) CFGMR3GetFirstChild(PCFGMNODE pNode);
211VMMR3DECL(PCFGMNODE) CFGMR3GetNextChild(PCFGMNODE pCur);
212VMMR3DECL(int) CFGMR3GetName(PCFGMNODE pCur, char *pszName, size_t cchName);
213VMMR3DECL(size_t) CFGMR3GetNameLen(PCFGMNODE pCur);
214VMMR3DECL(bool) CFGMR3AreChildrenValid(PCFGMNODE pNode, const char *pszzValid);
215VMMR3DECL(PCFGMLEAF) CFGMR3GetFirstValue(PCFGMNODE pCur);
216VMMR3DECL(PCFGMLEAF) CFGMR3GetNextValue(PCFGMLEAF pCur);
217VMMR3DECL(int) CFGMR3GetValueName(PCFGMLEAF pCur, char *pszName, size_t cchName);
218VMMR3DECL(size_t) CFGMR3GetValueNameLen(PCFGMLEAF pCur);
219VMMR3DECL(CFGMVALUETYPE) CFGMR3GetValueType(PCFGMLEAF pCur);
220VMMR3DECL(bool) CFGMR3AreValuesValid(PCFGMNODE pNode, const char *pszzValid);
221VMMR3DECL(int) CFGMR3ValidateConfig(PCFGMNODE pNode, const char *pszNode,
222 const char *pszValidValues, const char *pszValidNodes,
223 const char *pszWho, uint32_t uInstance);
224
225/** @} */
226
227
228/** @} */
229#endif /* IN_RING3 */
230
231
232RT_C_DECLS_END
233
234/** @} */
235
236#endif /* !VBOX_INCLUDED_vmm_cfgm_h */
237
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