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