cfgm.h revision 616637905fa2f00febb1acd553136d7e56316f7c
/** @file
* CFGM - Configuration Manager
*/
/*
* Copyright (C) 2006-2007 innotek GmbH
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License as published by the Free Software Foundation,
* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
* distribution. VirtualBox OSE is distributed in the hope that it will
* be useful, but WITHOUT ANY WARRANTY of any kind.
*
* If you received this file as part of a commercial VirtualBox
* distribution, then only the terms of your commercial VirtualBox
* license agreement apply instead of the previous paragraph.
*/
#ifndef ___VBox_cfgm_h
#define ___VBox_cfgm_h
/** @defgroup grp_cfgm The Configuration Manager API
* @{
*/
/** Configuration manager tree node - A key. */
/** Configuration manager tree leaf - A value. */
/**
* Configuration manager value type.
*/
typedef enum CFGMVALUETYPE
{
/** Integer value. */
/** String value. */
/** Bytestring value. */
/** Pointer to configuration manager property type. */
typedef CFGMVALUETYPE *PCFGMVALUETYPE;
#ifdef IN_RING3
/** @defgroup grp_cfgm_r3 The CFGM Host Context Ring-3 API
* @ingroup grp_cfgm
* @{
*/
typedef enum CFGMCONFIGTYPE
{
/** pvConfig points to nothing, use defaults. */
CFGMCONFIGTYPE_NONE = 0,
/** pvConfig points to a IMachine interface. */
/**
* CFGM init callback for constructing the configuration tree.
*
* This is called from the emulation thread, and the one interfacing the VM
* can make any necessary per-thread initializations at this point.
*
* @returns VBox status code.
* @param pVM VM handle.
* @param pvUser The argument supplied to VMR3Create().
*/
/** Pointer to a FNCFGMCONSTRUCTOR(). */
typedef FNCFGMCONSTRUCTOR *PFNCFGMCONSTRUCTOR;
/**
* Constructs the configuration for the VM.
*
* @returns VBox status code.
* @param pVM Pointer to VM which configuration has not yet been loaded.
* @param pfnCFGMConstructor Pointer to callback function for constructing the VM configuration tree.
* This is called in the EM.
* @param pvUser The user argument passed to pfnCFGMConstructor.
*/
/**
* Terminates the configuration manager.
*
* @returns VBox status code.
* @param pVM VM handle.
*/
/** Tree Navigation and Enumeration.
* @{
*/
/**
* Gets the root node for the VM.
*
* @returns Pointer to root node.
* @param pVM VM handle.
*/
/**
* Gets the parent of a CFGM node.
*
* @returns Pointer to the parent node.
* @returns NULL if pNode is Root or pNode is the start of a
* restricted subtree (use CFGMr3GetParentEx() for that).
*
* @param pNode The node which parent we query.
*/
/**
* Gets the parent of a CFGM node.
*
* @returns Pointer to the parent node.
* @returns NULL if pNode is Root or pVM is not correct.
*
* @param pVM The VM handle, used as token that the caller is trusted.
* @param pNode The node which parent we query.
*/
/**
* Query a child node.
*
* @returns Pointer to the specified node.
* @returns NULL if node was not found or pNode is NULL.
* @param pNode Node pszPath is relative to.
* @param pszPath Path to the child node or pNode.
* It's good style to end this with '/'.
*/
/**
* Query a child node by a format string.
*
* @returns Pointer to the specified node.
* @returns NULL if node was not found or pNode is NULL.
* @param pNode Node pszPath is relative to.
* @param pszPathFormat Path to the child node or pNode.
* It's good style to end this with '/'.
* @param ... Arguments to pszPathFormat.
*/
/**
* Query a child node by a format string.
*
* @returns Pointer to the specified node.
* @returns NULL if node was not found or pNode is NULL.
* @param pNode Node pszPath is relative to.
* @param pszPathFormat Path to the child node or pNode.
* It's good style to end this with '/'.
* @param Args Arguments to pszPathFormat.
*/
/**
* Gets the first child node.
* Use this to start an enumeration of child nodes.
*
* @returns Pointer to the first child.
* @returns NULL if no children.
* @param pNode Node to enumerate children for.
*/
/**
* Gets the next sibling node.
* Use this to continue an enumeration.
*
* @returns Pointer to the first child.
* @returns NULL if no children.
* @param pCur Node to returned by a call to CFGMR3GetFirstChild()
* or successive calls to this function.
*/
/**
* Gets the name of the current node.
* (Needed for enumeration.)
*
* @returns VBox status code.
* @param pCur Node to returned by a call to CFGMR3GetFirstChild()
* or successive calls to CFGMR3GetNextChild().
* @param pszName Where to store the node name.
* @param cchName Size of the buffer pointed to by pszName (with terminator).
*/
/**
* Gets the length of the current node's name.
* (Needed for enumeration.)
*
* @returns Node name length in bytes including the terminating null char.
* @returns 0 if pCur is NULL.
* @param pCur Node returned by a call to CFGMR3GetFirstChild()
* or successive calls to CFGMR3GetNextChild().
*/
/**
* Validates that the child nodes are within a set of valid names.
*
* @returns true if all names are found in pszzAllowed.
* @returns false if not.
* @param pNode The node which values should be examined.
* @param pszzValid List of valid names separated by '\\0' and ending with
* a double '\\0'.
*/
/**
* Gets the first value of a node.
* Use this to start an enumeration of values.
*
* @returns Pointer to the first value.
* @param pCur The node (Key) which values to enumerate.
*/
/**
* Gets the next value in enumeration.
*
* @returns Pointer to the next value.
* @param pCur The current value as returned by this function or CFGMR3GetFirstValue().
*/
/**
* Get the value name.
* (Needed for enumeration.)
*
* @returns VBox status code.
* @param pCur Value returned by a call to CFGMR3GetFirstValue()
* or successive calls to CFGMR3GetNextValue().
* @param pszName Where to store the value name.
* @param cchName Size of the buffer pointed to by pszName (with terminator).
*/
/**
* Gets the length of the current node's name.
* (Needed for enumeration.)
*
* @returns Value name length in bytes including the terminating null char.
* @returns 0 if pCur is NULL.
* @param pCur Value returned by a call to CFGMR3GetFirstValue()
* or successive calls to CFGMR3GetNextValue().
*/
/**
* Gets the value type.
* (For enumeration.)
*
* @returns VBox status code.
* @param pCur Value returned by a call to CFGMR3GetFirstValue()
* or successive calls to CFGMR3GetNextValue().
*/
/**
* Validates that the values are within a set of valid names.
*
* @returns true if all names are found in pszzAllowed.
* @returns false if not.
* @param pNode The node which values should be examined.
* @param pszzValid List of valid names separated by '\\0' and ending with
* a double '\\0'.
*/
/** @} */
/**
* Query value type.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param penmType Where to store the type.
*/
/**
* Query value size.
* This works on all types of values.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pcb Where to store the value size.
*/
/**
* Query integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pu64 Where to store the integer value.
*/
/**
* Query zero terminated character value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of a zero terminate character value.
* @param pszString Where to store the string.
* @param cchString Size of the string buffer. (Includes terminator.)
*/
CFGMR3DECL(int) CFGMR3QueryString(PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString);
/**
* Query byte string value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of a byte string value.
* @param pvData Where to store the binary data.
* @param cbData Size of buffer pvData points too.
*/
CFGMR3DECL(int) CFGMR3QueryBytes(PCFGMNODE pNode, const char *pszName, void *pvData, size_t cbData);
/**
* Insert a node.
*
* @returns VBox status code.
* @returns VERR_CFGM_NODE_EXISTS if the final child node name component exists.
* @param pNode Parent node.
* @param pszName Name or path of the new child node.
* @param ppChild Where to store the address of the new child node. (optional)
*/
/**
* Insert a node, format string name.
*
* @returns VBox status code.
* @param pNode Parent node.
* @param ppChild Where to store the address of the new child node. (optional)
* @param pszNameFormat Name or path of the new child node.
* @param ... Name format arguments.
*/
CFGMR3DECL(int) CFGMR3InsertNodeF(PCFGMNODE pNode, PCFGMNODE *ppChild, const char *pszNameFormat, ...);
/**
* Insert a node, format string name.
*
* @returns VBox status code.
* @param pNode Parent node.
* @param ppChild Where to store the address of the new child node. (optional)
* @param pszNameFormat Name or path of the new child node.
* @param Args Name format arguments.
*/
CFGMR3DECL(int) CFGMR3InsertNodeFV(PCFGMNODE pNode, PCFGMNODE *ppChild, const char *pszNameFormat, va_list Args);
/**
* Marks the node as the root of a restricted subtree, i.e. the end of
* a CFGMR3GetParent() journey.
*
* @param pNode The node to mark.
*/
/**
* Remove a node.
*
* @param pNode Parent node.
*/
/**
* Inserts a new integer value.
*
* @returns VBox status code.
* @param pNode Parent node.
* @param pszName Value name.
* @param u64Integer The value.
*/
/**
* Inserts a new string value.
*
* @returns VBox status code.
* @param pNode Parent node.
* @param pszName Value name.
* @param pszString The value.
*/
/**
* Inserts a new integer value.
*
* @returns VBox status code.
* @param pNode Parent node.
* @param pszName Value name.
* @param pvBytes The value.
* @param cbBytes The value size.
*/
CFGMR3DECL(int) CFGMR3InsertBytes(PCFGMNODE pNode, const char *pszName, void *pvBytes, size_t cbBytes);
/**
* Remove a value.
*
* @returns VBox status code.
* @param pNode Parent node.
* @param pszName Name of the new child node.
*/
/** Helpers
* @{
*/
/**
* Query unsigned 64-bit integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pu64 Where to store the integer value.
*/
/**
* Query signed 64-bit integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pi64 Where to store the value.
*/
/**
* Query unsigned 32-bit integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pu32 Where to store the value.
*/
/**
* Query signed 32-bit integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pi32 Where to store the value.
*/
/**
* Query unsigned 16-bit integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pu16 Where to store the value.
*/
/**
* Query signed 16-bit integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pi16 Where to store the value.
*/
/**
* Query unsigned 8-bit integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pu8 Where to store the value.
*/
/**
* Query signed 8-bit integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pi8 Where to store the value.
*/
/**
* Query boolean integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pf Where to store the value.
* @remark This function will interpret any non-zero value as true.
*/
/**
* Query pointer integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param ppv Where to store the value.
*/
/**
* Query Guest Context pointer integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pGCPtr Where to store the value.
*/
/**
* Query Guest Context unsigned pointer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pGCPtr Where to store the value.
*/
/**
* Query Guest Context signed pointer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pGCPtr Where to store the value.
*/
/**
* Query boolean integer value.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pvValue Where to store the value.
* @param cbValue The size of the integer value (in bytes).
* @param fSigned Whether the integer is signed (true) or not (false).
* @remark This function will interpret any non-zero value as true.
*/
DECLINLINE(int) CFGMR3QueryIntegerBySize(PCFGMNODE pNode, const char *pszName, void *pvValue, size_t cbValue, bool fSigned)
{
int rc;
if (fSigned)
{
switch (cbValue)
{
}
}
else
{
switch (cbValue)
{
}
}
return rc;
}
/**
* Query I/O port address value (integer).
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Name of an integer value.
* @param pPort Where to store the value.
*/
{
}
/**
* Query zero terminated character value storing it in a
* buffer allocated from the MM heap.
*
* @returns VBox status code.
* @param pNode Which node to search for pszName in.
* @param pszName Value name. This value must be of zero terminated character string type.
* @param ppszString Where to store the string pointer.
* Free this using MMR3HeapFree().
*/
/** @} */
/**
* Dumps the configuration (sub)tree.
*
* @param pRoot The root node of the dump.
*/
/** @} */
#endif /* IN_RING3 */
/** @} */
#endif