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