VirtualBox

source: vbox/trunk/include/VBox/cfgm.h@ 2981

Last change on this file since 2981 was 2981, checked in by vboxsync, 17 years ago

InnoTek -> innotek: all the headers and comments.

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