[1] | 1 | /** @file
|
---|
| 2 | * CFGM - Configuration Manager
|
---|
| 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[2981] | 6 | * Copyright (C) 2006-2007 innotek GmbH
|
---|
[1] | 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
|
---|
[5999] | 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.
|
---|
[1] | 24 | */
|
---|
| 25 |
|
---|
[3632] | 26 | #ifndef ___VBox_cfgm_h
|
---|
| 27 | #define ___VBox_cfgm_h
|
---|
[1] | 28 |
|
---|
| 29 | #include <VBox/cdefs.h>
|
---|
| 30 | #include <VBox/types.h>
|
---|
[665] | 31 | #include <iprt/stdarg.h>
|
---|
[1] | 32 |
|
---|
| 33 | /** @defgroup grp_cfgm The Configuration Manager API
|
---|
| 34 | * @{
|
---|
| 35 | */
|
---|
| 36 |
|
---|
| 37 | /** Configuration manager tree node - A key. */
|
---|
| 38 | typedef struct CFGMNODE *PCFGMNODE;
|
---|
| 39 |
|
---|
| 40 | /** Configuration manager tree leaf - A value. */
|
---|
| 41 | typedef struct CFGMLEAF *PCFGMLEAF;
|
---|
| 42 |
|
---|
| 43 | /**
|
---|
| 44 | * Configuration manager value type.
|
---|
| 45 | */
|
---|
| 46 | typedef enum CFGMVALUETYPE
|
---|
| 47 | {
|
---|
| 48 | /** Integer value. */
|
---|
| 49 | CFGMVALUETYPE_INTEGER = 1,
|
---|
| 50 | /** String value. */
|
---|
| 51 | CFGMVALUETYPE_STRING,
|
---|
| 52 | /** Bytestring value. */
|
---|
| 53 | CFGMVALUETYPE_BYTES
|
---|
| 54 | } CFGMVALUETYPE;
|
---|
| 55 | /** Pointer to configuration manager property type. */
|
---|
| 56 | typedef CFGMVALUETYPE *PCFGMVALUETYPE;
|
---|
| 57 |
|
---|
| 58 |
|
---|
| 59 |
|
---|
| 60 | __BEGIN_DECLS
|
---|
| 61 |
|
---|
| 62 | #ifdef IN_RING3
|
---|
| 63 | /** @defgroup grp_cfgm_r3 The CFGM Host Context Ring-3 API
|
---|
| 64 | * @ingroup grp_cfgm
|
---|
| 65 | * @{
|
---|
| 66 | */
|
---|
| 67 |
|
---|
| 68 | typedef enum CFGMCONFIGTYPE
|
---|
| 69 | {
|
---|
| 70 | /** pvConfig points to nothing, use defaults. */
|
---|
| 71 | CFGMCONFIGTYPE_NONE = 0,
|
---|
| 72 | /** pvConfig points to a IMachine interface. */
|
---|
| 73 | CFGMCONFIGTYPE_IMACHINE
|
---|
| 74 | } CFGMCONFIGTYPE;
|
---|
| 75 |
|
---|
| 76 |
|
---|
| 77 | /**
|
---|
| 78 | * CFGM init callback for constructing the configuration tree.
|
---|
| 79 | *
|
---|
| 80 | * This is called from the emulation thread, and the one interfacing the VM
|
---|
| 81 | * can make any necessary per-thread initializations at this point.
|
---|
| 82 | *
|
---|
| 83 | * @returns VBox status code.
|
---|
| 84 | * @param pVM VM handle.
|
---|
| 85 | * @param pvUser The argument supplied to VMR3Create().
|
---|
| 86 | */
|
---|
| 87 | typedef DECLCALLBACK(int) FNCFGMCONSTRUCTOR(PVM pVM, void *pvUser);
|
---|
| 88 | /** Pointer to a FNCFGMCONSTRUCTOR(). */
|
---|
| 89 | typedef FNCFGMCONSTRUCTOR *PFNCFGMCONSTRUCTOR;
|
---|
| 90 |
|
---|
| 91 |
|
---|
| 92 | /**
|
---|
| 93 | * Constructs the configuration for the VM.
|
---|
| 94 | *
|
---|
| 95 | * @returns VBox status code.
|
---|
| 96 | * @param pVM Pointer to VM which configuration has not yet been loaded.
|
---|
| 97 | * @param pfnCFGMConstructor Pointer to callback function for constructing the VM configuration tree.
|
---|
| 98 | * This is called in the EM.
|
---|
| 99 | * @param pvUser The user argument passed to pfnCFGMConstructor.
|
---|
| 100 | */
|
---|
| 101 | CFGMR3DECL(int) CFGMR3Init(PVM pVM, PFNCFGMCONSTRUCTOR pfnCFGMConstructor, void *pvUser);
|
---|
| 102 |
|
---|
| 103 | /**
|
---|
| 104 | * Terminates the configuration manager.
|
---|
| 105 | *
|
---|
| 106 | * @returns VBox status code.
|
---|
| 107 | * @param pVM VM handle.
|
---|
| 108 | */
|
---|
| 109 | CFGMR3DECL(int) CFGMR3Term(PVM pVM);
|
---|
| 110 |
|
---|
| 111 |
|
---|
| 112 | /** Tree Navigation and Enumeration.
|
---|
| 113 | * @{
|
---|
| 114 | */
|
---|
| 115 |
|
---|
| 116 | /**
|
---|
| 117 | * Gets the root node for the VM.
|
---|
| 118 | *
|
---|
| 119 | * @returns Pointer to root node.
|
---|
| 120 | * @param pVM VM handle.
|
---|
| 121 | */
|
---|
| 122 | CFGMR3DECL(PCFGMNODE) CFGMR3GetRoot(PVM pVM);
|
---|
| 123 |
|
---|
| 124 | /**
|
---|
| 125 | * Gets the parent of a CFGM node.
|
---|
| 126 | *
|
---|
| 127 | * @returns Pointer to the parent node.
|
---|
| 128 | * @returns NULL if pNode is Root or pNode is the start of a
|
---|
| 129 | * restricted subtree (use CFGMr3GetParentEx() for that).
|
---|
| 130 | *
|
---|
| 131 | * @param pNode The node which parent we query.
|
---|
| 132 | */
|
---|
| 133 | CFGMR3DECL(PCFGMNODE) CFGMR3GetParent(PCFGMNODE pNode);
|
---|
| 134 |
|
---|
| 135 | /**
|
---|
| 136 | * Gets the parent of a CFGM node.
|
---|
| 137 | *
|
---|
| 138 | * @returns Pointer to the parent node.
|
---|
| 139 | * @returns NULL if pNode is Root or pVM is not correct.
|
---|
| 140 | *
|
---|
| 141 | * @param pVM The VM handle, used as token that the caller is trusted.
|
---|
| 142 | * @param pNode The node which parent we query.
|
---|
| 143 | */
|
---|
| 144 | CFGMR3DECL(PCFGMNODE) CFGMR3GetParentEx(PVM pVM, PCFGMNODE pNode);
|
---|
| 145 |
|
---|
| 146 | /**
|
---|
| 147 | * Query a child node.
|
---|
| 148 | *
|
---|
| 149 | * @returns Pointer to the specified node.
|
---|
| 150 | * @returns NULL if node was not found or pNode is NULL.
|
---|
| 151 | * @param pNode Node pszPath is relative to.
|
---|
| 152 | * @param pszPath Path to the child node or pNode.
|
---|
| 153 | * It's good style to end this with '/'.
|
---|
| 154 | */
|
---|
| 155 | CFGMR3DECL(PCFGMNODE) CFGMR3GetChild(PCFGMNODE pNode, const char *pszPath);
|
---|
| 156 |
|
---|
| 157 | /**
|
---|
| 158 | * Query a child node by a format string.
|
---|
| 159 | *
|
---|
| 160 | * @returns Pointer to the specified node.
|
---|
| 161 | * @returns NULL if node was not found or pNode is NULL.
|
---|
| 162 | * @param pNode Node pszPath is relative to.
|
---|
| 163 | * @param pszPathFormat Path to the child node or pNode.
|
---|
| 164 | * It's good style to end this with '/'.
|
---|
| 165 | * @param ... Arguments to pszPathFormat.
|
---|
| 166 | */
|
---|
| 167 | CFGMR3DECL(PCFGMNODE) CFGMR3GetChildF(PCFGMNODE pNode, const char *pszPathFormat, ...);
|
---|
| 168 |
|
---|
| 169 | /**
|
---|
| 170 | * Query a child node by a format string.
|
---|
| 171 | *
|
---|
| 172 | * @returns Pointer to the specified node.
|
---|
| 173 | * @returns NULL if node was not found or pNode is NULL.
|
---|
| 174 | * @param pNode Node pszPath is relative to.
|
---|
| 175 | * @param pszPathFormat Path to the child node or pNode.
|
---|
| 176 | * It's good style to end this with '/'.
|
---|
| 177 | * @param Args Arguments to pszPathFormat.
|
---|
| 178 | */
|
---|
| 179 | CFGMR3DECL(PCFGMNODE) CFGMR3GetChildFV(PCFGMNODE pNode, const char *pszPathFormat, va_list Args);
|
---|
| 180 |
|
---|
| 181 | /**
|
---|
| 182 | * Gets the first child node.
|
---|
| 183 | * Use this to start an enumeration of child nodes.
|
---|
| 184 | *
|
---|
| 185 | * @returns Pointer to the first child.
|
---|
| 186 | * @returns NULL if no children.
|
---|
| 187 | * @param pNode Node to enumerate children for.
|
---|
| 188 | */
|
---|
| 189 | CFGMR3DECL(PCFGMNODE) CFGMR3GetFirstChild(PCFGMNODE pNode);
|
---|
| 190 |
|
---|
| 191 | /**
|
---|
| 192 | * Gets the next sibling node.
|
---|
| 193 | * Use this to continue an enumeration.
|
---|
| 194 | *
|
---|
| 195 | * @returns Pointer to the first child.
|
---|
| 196 | * @returns NULL if no children.
|
---|
| 197 | * @param pCur Node to returned by a call to CFGMR3GetFirstChild()
|
---|
| 198 | * or successive calls to this function.
|
---|
| 199 | */
|
---|
| 200 | CFGMR3DECL(PCFGMNODE) CFGMR3GetNextChild(PCFGMNODE pCur);
|
---|
| 201 |
|
---|
| 202 | /**
|
---|
| 203 | * Gets the name of the current node.
|
---|
| 204 | * (Needed for enumeration.)
|
---|
| 205 | *
|
---|
| 206 | * @returns VBox status code.
|
---|
| 207 | * @param pCur Node to returned by a call to CFGMR3GetFirstChild()
|
---|
| 208 | * or successive calls to CFGMR3GetNextChild().
|
---|
| 209 | * @param pszName Where to store the node name.
|
---|
| 210 | * @param cchName Size of the buffer pointed to by pszName (with terminator).
|
---|
| 211 | */
|
---|
| 212 | CFGMR3DECL(int) CFGMR3GetName(PCFGMNODE pCur, char *pszName, size_t cchName);
|
---|
| 213 |
|
---|
| 214 | /**
|
---|
| 215 | * Gets the length of the current node's name.
|
---|
| 216 | * (Needed for enumeration.)
|
---|
| 217 | *
|
---|
| 218 | * @returns Node name length in bytes including the terminating null char.
|
---|
| 219 | * @returns 0 if pCur is NULL.
|
---|
| 220 | * @param pCur Node returned by a call to CFGMR3GetFirstChild()
|
---|
| 221 | * or successive calls to CFGMR3GetNextChild().
|
---|
| 222 | */
|
---|
| 223 | CFGMR3DECL(int) CFGMR3GetNameLen(PCFGMNODE pCur);
|
---|
| 224 |
|
---|
| 225 | /**
|
---|
| 226 | * Validates that the child nodes are within a set of valid names.
|
---|
| 227 | *
|
---|
| 228 | * @returns true if all names are found in pszzAllowed.
|
---|
| 229 | * @returns false if not.
|
---|
| 230 | * @param pNode The node which values should be examined.
|
---|
| 231 | * @param pszzValid List of valid names separated by '\\0' and ending with
|
---|
| 232 | * a double '\\0'.
|
---|
| 233 | */
|
---|
| 234 | CFGMR3DECL(bool) CFGMR3AreChildrenValid(PCFGMNODE pNode, const char *pszzValid);
|
---|
| 235 |
|
---|
| 236 |
|
---|
| 237 | /**
|
---|
| 238 | * Gets the first value of a node.
|
---|
| 239 | * Use this to start an enumeration of values.
|
---|
| 240 | *
|
---|
| 241 | * @returns Pointer to the first value.
|
---|
| 242 | * @param pCur The node (Key) which values to enumerate.
|
---|
| 243 | */
|
---|
| 244 | CFGMR3DECL(PCFGMLEAF) CFGMR3GetFirstValue(PCFGMNODE pCur);
|
---|
| 245 |
|
---|
| 246 | /**
|
---|
| 247 | * Gets the next value in enumeration.
|
---|
| 248 | *
|
---|
| 249 | * @returns Pointer to the next value.
|
---|
| 250 | * @param pCur The current value as returned by this function or CFGMR3GetFirstValue().
|
---|
| 251 | */
|
---|
| 252 | CFGMR3DECL(PCFGMLEAF) CFGMR3GetNextValue(PCFGMLEAF pCur);
|
---|
| 253 |
|
---|
| 254 | /**
|
---|
| 255 | * Get the value name.
|
---|
| 256 | * (Needed for enumeration.)
|
---|
| 257 | *
|
---|
| 258 | * @returns VBox status code.
|
---|
| 259 | * @param pCur Value returned by a call to CFGMR3GetFirstValue()
|
---|
| 260 | * or successive calls to CFGMR3GetNextValue().
|
---|
| 261 | * @param pszName Where to store the value name.
|
---|
| 262 | * @param cchName Size of the buffer pointed to by pszName (with terminator).
|
---|
| 263 | */
|
---|
| 264 | CFGMR3DECL(int) CFGMR3GetValueName(PCFGMLEAF pCur, char *pszName, size_t cchName);
|
---|
| 265 |
|
---|
| 266 | /**
|
---|
| 267 | * Gets the length of the current node's name.
|
---|
| 268 | * (Needed for enumeration.)
|
---|
| 269 | *
|
---|
| 270 | * @returns Value name length in bytes including the terminating null char.
|
---|
| 271 | * @returns 0 if pCur is NULL.
|
---|
| 272 | * @param pCur Value returned by a call to CFGMR3GetFirstValue()
|
---|
| 273 | * or successive calls to CFGMR3GetNextValue().
|
---|
| 274 | */
|
---|
| 275 | CFGMR3DECL(int) CFGMR3GetValueNameLen(PCFGMLEAF pCur);
|
---|
| 276 |
|
---|
| 277 | /**
|
---|
| 278 | * Gets the value type.
|
---|
| 279 | * (For enumeration.)
|
---|
| 280 | *
|
---|
| 281 | * @returns VBox status code.
|
---|
| 282 | * @param pCur Value returned by a call to CFGMR3GetFirstValue()
|
---|
| 283 | * or successive calls to CFGMR3GetNextValue().
|
---|
| 284 | */
|
---|
| 285 | CFGMR3DECL(CFGMVALUETYPE) CFGMR3GetValueType(PCFGMLEAF pCur);
|
---|
| 286 |
|
---|
| 287 | /**
|
---|
| 288 | * Validates that the values are within a set of valid names.
|
---|
| 289 | *
|
---|
| 290 | * @returns true if all names are found in pszzAllowed.
|
---|
| 291 | * @returns false if not.
|
---|
| 292 | * @param pNode The node which values should be examined.
|
---|
| 293 | * @param pszzValid List of valid names separated by '\\0' and ending with
|
---|
| 294 | * a double '\\0'.
|
---|
| 295 | */
|
---|
| 296 | CFGMR3DECL(bool) CFGMR3AreValuesValid(PCFGMNODE pNode, const char *pszzValid);
|
---|
| 297 |
|
---|
| 298 | /** @} */
|
---|
| 299 |
|
---|
| 300 | /**
|
---|
| 301 | * Query value type.
|
---|
| 302 | *
|
---|
| 303 | * @returns VBox status code.
|
---|
| 304 | * @param pNode Which node to search for pszName in.
|
---|
| 305 | * @param pszName Name of an integer value.
|
---|
| 306 | * @param penmType Where to store the type.
|
---|
| 307 | */
|
---|
| 308 | CFGMR3DECL(int) CFGMR3QueryType(PCFGMNODE pNode, const char *pszName, PCFGMVALUETYPE penmType);
|
---|
| 309 |
|
---|
| 310 | /**
|
---|
| 311 | * Query value size.
|
---|
| 312 | * This works on all types of values.
|
---|
| 313 | *
|
---|
| 314 | * @returns VBox status code.
|
---|
| 315 | * @param pNode Which node to search for pszName in.
|
---|
| 316 | * @param pszName Name of an integer value.
|
---|
| 317 | * @param pcb Where to store the value size.
|
---|
| 318 | */
|
---|
| 319 | CFGMR3DECL(int) CFGMR3QuerySize(PCFGMNODE pNode, const char *pszName, size_t *pcb);
|
---|
| 320 |
|
---|
| 321 | /**
|
---|
| 322 | * Query integer value.
|
---|
| 323 | *
|
---|
| 324 | * @returns VBox status code.
|
---|
| 325 | * @param pNode Which node to search for pszName in.
|
---|
| 326 | * @param pszName Name of an integer value.
|
---|
| 327 | * @param pu64 Where to store the integer value.
|
---|
| 328 | */
|
---|
| 329 | CFGMR3DECL(int) CFGMR3QueryInteger(PCFGMNODE pNode, const char *pszName, uint64_t *pu64);
|
---|
| 330 |
|
---|
| 331 | /**
|
---|
| 332 | * Query zero terminated character value.
|
---|
| 333 | *
|
---|
| 334 | * @returns VBox status code.
|
---|
| 335 | * @param pNode Which node to search for pszName in.
|
---|
| 336 | * @param pszName Name of a zero terminate character value.
|
---|
| 337 | * @param pszString Where to store the string.
|
---|
| 338 | * @param cchString Size of the string buffer. (Includes terminator.)
|
---|
| 339 | */
|
---|
| 340 | CFGMR3DECL(int) CFGMR3QueryString(PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString);
|
---|
| 341 |
|
---|
| 342 | /**
|
---|
| 343 | * Query byte string value.
|
---|
| 344 | *
|
---|
| 345 | * @returns VBox status code.
|
---|
| 346 | * @param pNode Which node to search for pszName in.
|
---|
| 347 | * @param pszName Name of a byte string value.
|
---|
| 348 | * @param pvData Where to store the binary data.
|
---|
| 349 | * @param cbData Size of buffer pvData points too.
|
---|
| 350 | */
|
---|
| 351 | CFGMR3DECL(int) CFGMR3QueryBytes(PCFGMNODE pNode, const char *pszName, void *pvData, size_t cbData);
|
---|
| 352 |
|
---|
| 353 |
|
---|
| 354 | /**
|
---|
[3840] | 355 | * Creates a CFGM tree.
|
---|
| 356 | *
|
---|
| 357 | * This is intended for creating device/driver configs can be
|
---|
| 358 | * passed around and later attached to the main tree in the
|
---|
| 359 | * correct location.
|
---|
| 360 | *
|
---|
| 361 | * @returns Pointer to the root node.
|
---|
| 362 | * @param pVM The VM handle.
|
---|
| 363 | */
|
---|
| 364 | CFGMR3DECL(PCFGMNODE) CFGMR3CreateTree(PVM pVM);
|
---|
| 365 |
|
---|
| 366 | /**
|
---|
| 367 | * Insert subtree.
|
---|
| 368 | *
|
---|
| 369 | * This function inserts (no duplication) a tree created by CFGMR3CreateTree()
|
---|
| 370 | * into the main tree.
|
---|
| 371 | *
|
---|
| 372 | * The root node of the inserted subtree will need to be reallocated, which
|
---|
| 373 | * effectually means that the passed in pSubTree handle becomes invalid
|
---|
| 374 | * upon successful return. Use the value returned in ppChild instead
|
---|
| 375 | * of pSubTree.
|
---|
| 376 | *
|
---|
| 377 | * @returns VBox status code.
|
---|
| 378 | * @returns VERR_CFGM_NODE_EXISTS if the final child node name component exists.
|
---|
| 379 | * @param pNode Parent node.
|
---|
| 380 | * @param pszName Name or path of the new child node.
|
---|
| 381 | * @param pSubTree The subtree to insert. Must be returned by CFGMR3CreateTree().
|
---|
| 382 | * @param ppChild Where to store the address of the new child node. (optional)
|
---|
| 383 | */
|
---|
| 384 | CFGMR3DECL(int) CFGMR3InsertSubTree(PCFGMNODE pNode, const char *pszName, PCFGMNODE pSubTree, PCFGMNODE *ppChild);
|
---|
| 385 |
|
---|
| 386 | /**
|
---|
[1] | 387 | * Insert a node.
|
---|
| 388 | *
|
---|
| 389 | * @returns VBox status code.
|
---|
| 390 | * @returns VERR_CFGM_NODE_EXISTS if the final child node name component exists.
|
---|
| 391 | * @param pNode Parent node.
|
---|
| 392 | * @param pszName Name or path of the new child node.
|
---|
| 393 | * @param ppChild Where to store the address of the new child node. (optional)
|
---|
| 394 | */
|
---|
| 395 | CFGMR3DECL(int) CFGMR3InsertNode(PCFGMNODE pNode, const char *pszName, PCFGMNODE *ppChild);
|
---|
| 396 |
|
---|
| 397 | /**
|
---|
| 398 | * Insert a node, format string name.
|
---|
| 399 | *
|
---|
| 400 | * @returns VBox status code.
|
---|
| 401 | * @param pNode Parent node.
|
---|
| 402 | * @param ppChild Where to store the address of the new child node. (optional)
|
---|
| 403 | * @param pszNameFormat Name or path of the new child node.
|
---|
| 404 | * @param ... Name format arguments.
|
---|
| 405 | */
|
---|
| 406 | CFGMR3DECL(int) CFGMR3InsertNodeF(PCFGMNODE pNode, PCFGMNODE *ppChild, const char *pszNameFormat, ...);
|
---|
| 407 |
|
---|
| 408 | /**
|
---|
| 409 | * Insert a node, format string name.
|
---|
| 410 | *
|
---|
| 411 | * @returns VBox status code.
|
---|
| 412 | * @param pNode Parent node.
|
---|
| 413 | * @param ppChild Where to store the address of the new child node. (optional)
|
---|
| 414 | * @param pszNameFormat Name or path of the new child node.
|
---|
| 415 | * @param Args Name format arguments.
|
---|
| 416 | */
|
---|
| 417 | CFGMR3DECL(int) CFGMR3InsertNodeFV(PCFGMNODE pNode, PCFGMNODE *ppChild, const char *pszNameFormat, va_list Args);
|
---|
| 418 |
|
---|
| 419 | /**
|
---|
| 420 | * Marks the node as the root of a restricted subtree, i.e. the end of
|
---|
| 421 | * a CFGMR3GetParent() journey.
|
---|
| 422 | *
|
---|
| 423 | * @param pNode The node to mark.
|
---|
| 424 | */
|
---|
| 425 | CFGMR3DECL(void) CFGMR3SetRestrictedRoot(PCFGMNODE pNode);
|
---|
| 426 |
|
---|
| 427 | /**
|
---|
| 428 | * Remove a node.
|
---|
| 429 | *
|
---|
| 430 | * @param pNode Parent node.
|
---|
| 431 | */
|
---|
| 432 | CFGMR3DECL(void) CFGMR3RemoveNode(PCFGMNODE pNode);
|
---|
| 433 |
|
---|
| 434 |
|
---|
| 435 | /**
|
---|
| 436 | * Inserts a new integer value.
|
---|
| 437 | *
|
---|
| 438 | * @returns VBox status code.
|
---|
| 439 | * @param pNode Parent node.
|
---|
| 440 | * @param pszName Value name.
|
---|
| 441 | * @param u64Integer The value.
|
---|
| 442 | */
|
---|
| 443 | CFGMR3DECL(int) CFGMR3InsertInteger(PCFGMNODE pNode, const char *pszName, uint64_t u64Integer);
|
---|
| 444 |
|
---|
| 445 | /**
|
---|
| 446 | * Inserts a new string value.
|
---|
| 447 | *
|
---|
| 448 | * @returns VBox status code.
|
---|
| 449 | * @param pNode Parent node.
|
---|
| 450 | * @param pszName Value name.
|
---|
| 451 | * @param pszString The value.
|
---|
| 452 | */
|
---|
| 453 | CFGMR3DECL(int) CFGMR3InsertString(PCFGMNODE pNode, const char *pszName, const char *pszString);
|
---|
| 454 |
|
---|
| 455 | /**
|
---|
| 456 | * Inserts a new integer value.
|
---|
| 457 | *
|
---|
| 458 | * @returns VBox status code.
|
---|
| 459 | * @param pNode Parent node.
|
---|
| 460 | * @param pszName Value name.
|
---|
| 461 | * @param pvBytes The value.
|
---|
| 462 | * @param cbBytes The value size.
|
---|
| 463 | */
|
---|
[4503] | 464 | CFGMR3DECL(int) CFGMR3InsertBytes(PCFGMNODE pNode, const char *pszName, const void *pvBytes, size_t cbBytes);
|
---|
[1] | 465 |
|
---|
| 466 | /**
|
---|
| 467 | * Remove a value.
|
---|
| 468 | *
|
---|
| 469 | * @returns VBox status code.
|
---|
| 470 | * @param pNode Parent node.
|
---|
| 471 | * @param pszName Name of the new child node.
|
---|
| 472 | */
|
---|
| 473 | CFGMR3DECL(int) CFGMR3RemoveValue(PCFGMNODE pNode, const char *pszName);
|
---|
| 474 |
|
---|
| 475 |
|
---|
| 476 |
|
---|
| 477 | /** Helpers
|
---|
| 478 | * @{
|
---|
| 479 | */
|
---|
| 480 | /**
|
---|
| 481 | * Query unsigned 64-bit integer value.
|
---|
| 482 | *
|
---|
| 483 | * @returns VBox status code.
|
---|
| 484 | * @param pNode Which node to search for pszName in.
|
---|
| 485 | * @param pszName Name of an integer value.
|
---|
| 486 | * @param pu64 Where to store the integer value.
|
---|
| 487 | */
|
---|
| 488 | CFGMR3DECL(int) CFGMR3QueryU64(PCFGMNODE pNode, const char *pszName, uint64_t *pu64);
|
---|
| 489 |
|
---|
| 490 | /**
|
---|
| 491 | * Query signed 64-bit integer value.
|
---|
| 492 | *
|
---|
| 493 | * @returns VBox status code.
|
---|
| 494 | * @param pNode Which node to search for pszName in.
|
---|
| 495 | * @param pszName Name of an integer value.
|
---|
| 496 | * @param pi64 Where to store the value.
|
---|
| 497 | */
|
---|
| 498 | CFGMR3DECL(int) CFGMR3QueryS64(PCFGMNODE pNode, const char *pszName, int64_t *pi64);
|
---|
| 499 |
|
---|
| 500 | /**
|
---|
| 501 | * Query unsigned 32-bit integer value.
|
---|
| 502 | *
|
---|
| 503 | * @returns VBox status code.
|
---|
| 504 | * @param pNode Which node to search for pszName in.
|
---|
| 505 | * @param pszName Name of an integer value.
|
---|
| 506 | * @param pu32 Where to store the value.
|
---|
| 507 | */
|
---|
| 508 | CFGMR3DECL(int) CFGMR3QueryU32(PCFGMNODE pNode, const char *pszName, uint32_t *pu32);
|
---|
| 509 |
|
---|
| 510 | /**
|
---|
| 511 | * Query signed 32-bit integer value.
|
---|
| 512 | *
|
---|
| 513 | * @returns VBox status code.
|
---|
| 514 | * @param pNode Which node to search for pszName in.
|
---|
| 515 | * @param pszName Name of an integer value.
|
---|
| 516 | * @param pi32 Where to store the value.
|
---|
| 517 | */
|
---|
| 518 | CFGMR3DECL(int) CFGMR3QueryS32(PCFGMNODE pNode, const char *pszName, int32_t *pi32);
|
---|
| 519 |
|
---|
| 520 | /**
|
---|
| 521 | * Query unsigned 16-bit integer value.
|
---|
| 522 | *
|
---|
| 523 | * @returns VBox status code.
|
---|
| 524 | * @param pNode Which node to search for pszName in.
|
---|
| 525 | * @param pszName Name of an integer value.
|
---|
| 526 | * @param pu16 Where to store the value.
|
---|
| 527 | */
|
---|
| 528 | CFGMR3DECL(int) CFGMR3QueryU16(PCFGMNODE pNode, const char *pszName, uint16_t *pu16);
|
---|
| 529 |
|
---|
| 530 | /**
|
---|
| 531 | * Query signed 16-bit integer value.
|
---|
| 532 | *
|
---|
| 533 | * @returns VBox status code.
|
---|
| 534 | * @param pNode Which node to search for pszName in.
|
---|
| 535 | * @param pszName Name of an integer value.
|
---|
| 536 | * @param pi16 Where to store the value.
|
---|
| 537 | */
|
---|
| 538 | CFGMR3DECL(int) CFGMR3QueryS16(PCFGMNODE pNode, const char *pszName, int16_t *pi16);
|
---|
| 539 |
|
---|
| 540 | /**
|
---|
| 541 | * Query unsigned 8-bit integer value.
|
---|
| 542 | *
|
---|
| 543 | * @returns VBox status code.
|
---|
| 544 | * @param pNode Which node to search for pszName in.
|
---|
| 545 | * @param pszName Name of an integer value.
|
---|
| 546 | * @param pu8 Where to store the value.
|
---|
| 547 | */
|
---|
| 548 | CFGMR3DECL(int) CFGMR3QueryU8(PCFGMNODE pNode, const char *pszName, uint8_t *pu8);
|
---|
| 549 |
|
---|
| 550 | /**
|
---|
| 551 | * Query signed 8-bit integer value.
|
---|
| 552 | *
|
---|
| 553 | * @returns VBox status code.
|
---|
| 554 | * @param pNode Which node to search for pszName in.
|
---|
| 555 | * @param pszName Name of an integer value.
|
---|
| 556 | * @param pi8 Where to store the value.
|
---|
| 557 | */
|
---|
| 558 | CFGMR3DECL(int) CFGMR3QueryS8(PCFGMNODE pNode, const char *pszName, int8_t *pi8);
|
---|
| 559 |
|
---|
| 560 | /**
|
---|
| 561 | * Query boolean integer value.
|
---|
| 562 | *
|
---|
| 563 | * @returns VBox status code.
|
---|
| 564 | * @param pNode Which node to search for pszName in.
|
---|
| 565 | * @param pszName Name of an integer value.
|
---|
| 566 | * @param pf Where to store the value.
|
---|
| 567 | * @remark This function will interpret any non-zero value as true.
|
---|
| 568 | */
|
---|
| 569 | CFGMR3DECL(int) CFGMR3QueryBool(PCFGMNODE pNode, const char *pszName, bool *pf);
|
---|
| 570 |
|
---|
| 571 | /**
|
---|
| 572 | * Query pointer integer value.
|
---|
| 573 | *
|
---|
| 574 | * @returns VBox status code.
|
---|
| 575 | * @param pNode Which node to search for pszName in.
|
---|
| 576 | * @param pszName Name of an integer value.
|
---|
| 577 | * @param ppv Where to store the value.
|
---|
| 578 | */
|
---|
| 579 | CFGMR3DECL(int) CFGMR3QueryPtr(PCFGMNODE pNode, const char *pszName, void **ppv);
|
---|
| 580 |
|
---|
| 581 | /**
|
---|
| 582 | * Query Guest Context pointer integer value.
|
---|
| 583 | *
|
---|
| 584 | * @returns VBox status code.
|
---|
| 585 | * @param pNode Which node to search for pszName in.
|
---|
| 586 | * @param pszName Name of an integer value.
|
---|
| 587 | * @param pGCPtr Where to store the value.
|
---|
| 588 | */
|
---|
| 589 | CFGMR3DECL(int) CFGMR3QueryGCPtr(PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr);
|
---|
| 590 |
|
---|
| 591 | /**
|
---|
| 592 | * Query Guest Context unsigned pointer value.
|
---|
| 593 | *
|
---|
| 594 | * @returns VBox status code.
|
---|
| 595 | * @param pNode Which node to search for pszName in.
|
---|
| 596 | * @param pszName Name of an integer value.
|
---|
| 597 | * @param pGCPtr Where to store the value.
|
---|
| 598 | */
|
---|
| 599 | CFGMR3DECL(int) CFGMR3QueryGCPtrU(PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr);
|
---|
| 600 |
|
---|
| 601 | /**
|
---|
| 602 | * Query Guest Context signed pointer value.
|
---|
| 603 | *
|
---|
| 604 | * @returns VBox status code.
|
---|
| 605 | * @param pNode Which node to search for pszName in.
|
---|
| 606 | * @param pszName Name of an integer value.
|
---|
| 607 | * @param pGCPtr Where to store the value.
|
---|
| 608 | */
|
---|
| 609 | CFGMR3DECL(int) CFGMR3QueryGCPtrS(PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr);
|
---|
| 610 |
|
---|
| 611 | /**
|
---|
| 612 | * Query boolean integer value.
|
---|
| 613 | *
|
---|
| 614 | * @returns VBox status code.
|
---|
| 615 | * @param pNode Which node to search for pszName in.
|
---|
| 616 | * @param pszName Name of an integer value.
|
---|
| 617 | * @param pvValue Where to store the value.
|
---|
| 618 | * @param cbValue The size of the integer value (in bytes).
|
---|
| 619 | * @param fSigned Whether the integer is signed (true) or not (false).
|
---|
| 620 | * @remark This function will interpret any non-zero value as true.
|
---|
| 621 | */
|
---|
| 622 | DECLINLINE(int) CFGMR3QueryIntegerBySize(PCFGMNODE pNode, const char *pszName, void *pvValue, size_t cbValue, bool fSigned)
|
---|
| 623 | {
|
---|
| 624 | int rc;
|
---|
| 625 | if (fSigned)
|
---|
| 626 | {
|
---|
| 627 | switch (cbValue)
|
---|
| 628 | {
|
---|
| 629 | case 8: rc = CFGMR3QueryS8(pNode, pszName, (int8_t *)pvValue); break;
|
---|
| 630 | case 16: rc = CFGMR3QueryS16(pNode, pszName, (int16_t *)pvValue); break;
|
---|
| 631 | case 32: rc = CFGMR3QueryS32(pNode, pszName, (int32_t *)pvValue); break;
|
---|
| 632 | case 64: rc = CFGMR3QueryS64(pNode, pszName, (int64_t *)pvValue); break;
|
---|
| 633 | default: rc = -1 /* VERR_GENERAL_FAILURE*/; break;
|
---|
| 634 | }
|
---|
| 635 | }
|
---|
| 636 | else
|
---|
| 637 | {
|
---|
| 638 | switch (cbValue)
|
---|
| 639 | {
|
---|
| 640 | case 8: rc = CFGMR3QueryU8(pNode, pszName, (uint8_t *)pvValue); break;
|
---|
| 641 | case 16: rc = CFGMR3QueryU16(pNode, pszName, (uint16_t *)pvValue); break;
|
---|
| 642 | case 32: rc = CFGMR3QueryU32(pNode, pszName, (uint32_t *)pvValue); break;
|
---|
| 643 | case 64: rc = CFGMR3QueryU64(pNode, pszName, (uint64_t *)pvValue); break;
|
---|
| 644 | default: rc = -1 /* VERR_GENERAL_FAILURE*/; break;
|
---|
| 645 | }
|
---|
| 646 | }
|
---|
| 647 | return rc;
|
---|
| 648 | }
|
---|
| 649 |
|
---|
| 650 |
|
---|
| 651 | /**
|
---|
| 652 | * Query I/O port address value (integer).
|
---|
| 653 | *
|
---|
| 654 | * @returns VBox status code.
|
---|
| 655 | * @param pNode Which node to search for pszName in.
|
---|
| 656 | * @param pszName Name of an integer value.
|
---|
| 657 | * @param pPort Where to store the value.
|
---|
| 658 | */
|
---|
| 659 | DECLINLINE(int) CFGMR3QueryPort(PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort)
|
---|
| 660 | {
|
---|
| 661 | return CFGMR3QueryIntegerBySize(pNode, pszName, pPort, sizeof(*pPort), false);
|
---|
| 662 | }
|
---|
| 663 |
|
---|
| 664 |
|
---|
| 665 |
|
---|
| 666 | /**
|
---|
| 667 | * Query zero terminated character value storing it in a
|
---|
| 668 | * buffer allocated from the MM heap.
|
---|
| 669 | *
|
---|
| 670 | * @returns VBox status code.
|
---|
| 671 | * @param pNode Which node to search for pszName in.
|
---|
| 672 | * @param pszName Value name. This value must be of zero terminated character string type.
|
---|
| 673 | * @param ppszString Where to store the string pointer.
|
---|
| 674 | * Free this using MMR3HeapFree().
|
---|
| 675 | */
|
---|
| 676 | CFGMR3DECL(int) CFGMR3QueryStringAlloc(PCFGMNODE pNode, const char *pszName, char **ppszString);
|
---|
| 677 |
|
---|
| 678 | /** @} */
|
---|
| 679 |
|
---|
| 680 |
|
---|
| 681 | /**
|
---|
| 682 | * Dumps the configuration (sub)tree.
|
---|
| 683 | *
|
---|
| 684 | * @param pRoot The root node of the dump.
|
---|
| 685 | */
|
---|
| 686 | CFGMR3DECL(void) CFGMR3Dump(PCFGMNODE pRoot);
|
---|
| 687 |
|
---|
| 688 | /** @} */
|
---|
| 689 | #endif /* IN_RING3 */
|
---|
| 690 |
|
---|
| 691 |
|
---|
| 692 | __END_DECLS
|
---|
| 693 |
|
---|
| 694 | /** @} */
|
---|
| 695 |
|
---|
| 696 | #endif
|
---|