cfgldr.h revision f09e90cfd889a5957dbcc2b58c71c2770aa52706
/** @file
* CFGLDR - Configuration Loader
*/
/*
* Copyright (C) 2006 InnoTek Systemberatung GmbH
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* you can redistribute it and/or modify it under the terms of the GNU
* 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_cfgldr_h__
#define __VBox_cfgldr_h__
#include <VBox/cdefs.h>
#include <VBox/types.h>
#include <iprt/string.h>
/** @defgroup grp_cfgldr The Configuration Loader API
* @{
*/
#ifndef IN_RING3
# error "There are no configuration loader APIs available in Ring-0 Context!"
#else /* IN_RING3 */
/** @def IN_CFGLDR_R3
* Used to indicate whether we're inside the same link module as the
* Configuration Loader.
*/
#ifdef IN_CFGLDR_R3
# define CFGLDRR3DECL(type) DECLEXPORT(type) VBOXCALL
#else
# define CFGLDRR3DECL(type) DECLIMPORT(type) VBOXCALL
#endif
/** @type CFGHANDLE
* Configuration handle. */
/** @type CFGNODE
* Configuration node handle. */
#ifdef __cplusplus
class CfgLoader;
typedef CfgLoader *CFGHANDLE;
class CfgNode;
typedef CfgNode *CFGNODE;
#else
struct CfgLoader;
typedef struct CfgLoader *CFGHANDLE;
struct CfgNode;
typedef struct CfgNode *CFGNODE;
#endif
/** Entity type */
typedef enum CFGLDRENTITYTYPE
{
CFGLDRENTITYTYPE_INVALID = 0, /**< Invalid type */
CFGLDRENTITYTYPE_HANDLE, /**< File handle */
CFGLDRENTITYTYPE_MEMORY /**< Memory buffer */
} CFGLDRENTITYTYPE;
/** Entity descriptor for the entity resolver callback */
typedef struct CFGLDRENTITY
{
/** Entity type */
CFGLDRENTITYTYPE enmType;
union
{
/** File handle (CFGLDRENTITYTYPE_HANDLE) */
struct
{
RTFILE hFile; /**< Handle of the file opened for reading entity data */
bool bClose; /**< Whether to close the handle when no more needed */
} handle;
/** Memory buffer (CFGLDRENTITYTYPE_MEMORY) */
struct
{
unsigned char *puchBuf; /**< Byte array containing entity data */
size_t cbBuf; /**< Size of the puchBuf array */
bool bFree; /**< Whether to free puchBuf using RTMemTmpFree()
when no more needed */
} memory;
} u;
} CFGLDRRESOLVEDENTITY;
/** Pointer to CFGLDRENTITY */
typedef CFGLDRENTITY *PCFGLDRENTITY;
/** Pointer to const CFGLDRENTITY */
typedef const CFGLDRENTITY *PCCFGLDRENTITY;
/**
* Callback function used by CFGLDRLoad() to resolve external entities when
* loading and parsing the configuration file,
*
* First three arguments are input parameters, describing the entity to resolve.
* On return, the callback fills in a CFGLDRENTITY structure pointed to by the
* pEntity argument, with values corresponding to the given entity.
*
* @param pcszPublicId
* Public ID of the entity in question (UTF-8)
* @param pcszSystemId
* System ID (URI) of the entity in question (UTF-8)
* @param pcszBaseURI
* Base URI of the entity necessary to resolve relative URIs (UTF-8)
* @param pEntity
* Pointer to the entity descriptor structure to fill in
*
* @return
* VINF_SUCCESS to indicate that pEntity is successfully filled in by the
* callback. Any other value will cause the configuration
* loader to use the default entity resolver (see pfnEntityResolver in
* CFGLDRLoad()).
*/
typedef DECLCALLBACK(int) FNCFGLDRENTITYRESOLVER(const char *pcszPublicId,
const char *pcszSystemId,
const char *pcszBaseURI,
PCFGLDRENTITY pEntity);
/** Pointer to entity resolver callback. */
typedef FNCFGLDRENTITYRESOLVER *PFNCFGLDRENTITYRESOLVER;
__BEGIN_DECLS
/**
* Initializes CFGLDR, have to be called at VBox startup before accessing any CFGLDR functions.
*
* @return VBox status code.
*/
CFGLDRR3DECL(int) CFGLDRInitialize(void);
/**
* Deletes all configurations and nodes at VBox termination. After calling this function all CFGLDR functions will be unavailable.
*
* @return VBox status code.
*/
CFGLDRR3DECL(void) CFGLDRShutdown(void);
/**
* Creates a configuration file from scratch. The file then can be saved
* using the CFGLDRSaveAs() function.
*
* @return VBox status code.
*/
CFGLDRR3DECL(int) CFGLDRCreate(CFGHANDLE *phcfg);
/**
* Loads a configuration file.
*
* @param phcfg
* Pointer to a handle that will be used to access the configuration.
* @param pszFilename
* Name of the file containing the configuration (UTF-8).
* @param hFileHandle
* Handle of the file containing the configuration. If equals to NIL_RTFILE,
* an attempt to open the specified file will be made; otherwise
* it must be a valid file handle corresponding to the given file name
* opened at least for reading.
* @param pszExternalSchemaLocation
* Name of the file containing namespaceless XML Schema for the configuration
* file or one or more pairs (separated by spaces) consiting of a namespace
* and an XML schema file for the given namespace, depending on the
* value of bDoNamespaces. The parameter can be NULL to indicate that
* no validation of the configuration file should be done.
* @param bDoNamespaces
* If TRUE, namespace processing is turned on and pszExternalSchemaLocation
* is assumed to contain "namespace schema-file" pairs; otherwise namespaces
* are disabled and pszExternalSchemaLocation is assumed to be a single file
* name. The parameter ignored if pszExternalSchemaLocation is NULL.
* @param pfnEntityResolver
* Callback used to resolve external entities in the configuration file.
* Note that the configuration file itself is always accessed directly
* (using the given file name or file handle), but all external entities it
* refers to, as well as all schema files, are resolved using this callback.
* This parameter can be NULL, in which case the default resolver is used
* which simply tries to open an entity by its system ID (URI).
* @param ppszErrorMessage
* Address of a variable that will receive a pointer to an UTF-8 string
* containing all error messages produced by a parser while parsing and
* validating the configuration file. If non-NULL pointer is returned, the
* caller must free the string using RTStrFree(). The parameter can be
* NULL on input (no error string will be returned), and it can point to
* NULL on output indicating that no error message was provided.
* If the function succeeds, the returned string is always NULL.
*
* @return VBox status code.
*/
CFGLDRR3DECL(int) CFGLDRLoad(CFGHANDLE *phcfg,
const char *pszFileName, RTFILE hFileHandle,
const char *pszExternalSchemaLocation, bool bDoNamespaces,
PFNCFGLDRENTITYRESOLVER pfnEntityResolver,
char **ppszErrorMessage);
/**
* Frees the previously loaded configuration.
*
* @return VBox status code.
* @param hcfg Handle of configuration that was loaded using CFGLDRLoad().
*/
CFGLDRR3DECL(int) CFGLDRFree(CFGHANDLE hcfg);
/**
* Saves the previously loaded configuration.
*
* @param hcfg
* Handle of the configuration that was loaded using CFGLDRLoad().
* @param ppszErrorMessage
* Address of a variable that will receive a pointer to an UTF-8 string
* containing all error messages produced by a writer while saving
* the configuration file. If non-NULL pointer is returned, the
* caller must free the string using RTStrFree(). The parameter can be
* NULL on input (no error string will be returned), and it can point to
* NULL on output indicating that no error message was provided.
* If the function succeeds, the returned string is always NULL.
*
* @return VBox status code.
*/
CFGLDRR3DECL(int) CFGLDRSave(CFGHANDLE hcfg,
char **ppszErrorMessage);
/**
* Saves the configuration to a specified file.
*
* @param hcfg
* Handle of the configuration that was loaded using CFGLDRLoad().
* @param pszFilename
* Name of the file to save the configuration to (UTF-8).
* @param hFileHandle
* Handle of the file to save the configuration to. If equals to NIL_RTFILE,
* an attempt to open the specified file will be made; otherwise
* it must be a valid file handle corresponding to the given file name
* opened at least for writting.
* @param ppszErrorMessage
* Address of a variable that will receive a pointer to an UTF-8 string
* containing all error messages produced by a writer while saving
* the configuration file. If non-NULL pointer is returned, the
* caller must free the string using RTStrFree(). The parameter can be
* NULL on input (no error string will be returned), and it can point to
* NULL on output indicating that no error message was provided.
* If the function succeeds, the returned string is always NULL.
*
* @return VBox status code.
*/
CFGLDRR3DECL(int) CFGLDRSaveAs(CFGHANDLE hcfg,
const char *pszFilename, RTFILE hFileHandle,
char **ppszErrorMessage);
/**
* Applies an XSLT transformation to the given configuration handle.
*
* @param hcfg
* Handle of the configuration that was loaded using CFGLDRLoad().
* @param pszTemlateLocation
* Name of the file containing an XSL template to apply
* @param pfnEntityResolver
* Callback used to resolve external entities (the XSL template file).
* This parameter can be NULL, in which case the default resolver is used
* which simply tries to open an entity by its system ID (URI).
* @param ppszErrorMessage
* Address of a variable that will receive a pointer to an UTF-8 string
* containing all error messages produced by a parser while parsing and
* validating the configuration file. If non-NULL pointer is returned, the
* caller must free the string using RTStrFree(). The parameter can be
* NULL on input (no error string will be returned), and it can point to
* NULL on output indicating that no error message was provided.
* If the function succeeds, the returned string is always NULL.
*/
CFGLDRR3DECL(int) CFGLDRTransform (CFGHANDLE hcfg,
const char *pszTemlateLocation,
PFNCFGLDRENTITYRESOLVER pfnEntityResolver,
char **ppszErrorMessage);
/**
* Get node handle.
*
* @return VBox status code.
* @param hcfg Handle of configuration that was loaded using CFGLDRLoad().
* @param pszName Name of the node (UTF-8).
* @param uIndex Index of the node (0 based).
* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
*/
CFGLDRR3DECL(int) CFGLDRGetNode(CFGHANDLE hcfg, const char *pszName, unsigned uIndex, CFGNODE *phnode);
/**
* Get child node handle.
*
* @return VBox status code.
* @param hparent Handle of parent node.
* @param pszName Name of the child node (UTF-8), NULL for any child.
* @param uIndex Index of the child node (0 based).
* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
*/
CFGLDRR3DECL(int) CFGLDRGetChildNode(CFGNODE hparent, const char *pszName, unsigned uIndex, CFGNODE *phnode);
/**
* Creates a new node or returns the first one with a given name if
* already exists.
*
* @return VBox status code.
* @param hcfg Handle of the configuration.
* @param pszName Name of the node to be created (UTF-8).
* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
*/
CFGLDRR3DECL(int) CFGLDRCreateNode(CFGHANDLE hcfg, const char *pszName, CFGNODE *phnode);
/**
* Creates a new child node or returns the first one with a given name if
* already exists.
*
* @return VBox status code.
* @param hparent Handle of parent node.
* @param pszName Name of the child node (UTF-8).
* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
*/
CFGLDRR3DECL(int) CFGLDRCreateChildNode(CFGNODE hparent, const char *pszName, CFGNODE *phnode);
/**
* Appends a new child node.
*
* @return VBox status code.
* @param hparent Handle of parent node.
* @param pszName Name of the child node (UTF-8).
* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
*/
CFGLDRR3DECL(int) CFGLDRAppendChildNode(CFGNODE hparent, const char *pszName, CFGNODE *phnode);
/**
* Release node handle.
*
* @return VBox status code.
* @param hnode Handle that will not be used anymore.
*/
CFGLDRR3DECL(int) CFGLDRReleaseNode(CFGNODE hnode);
/**
* Delete node. The handle is released and the entire node is removed.
*
* @return VBox status code.
* @param hnode Handle of node that will be deleted.
*/
CFGLDRR3DECL(int) CFGLDRDeleteNode(CFGNODE hnode);
/**
* Count child nodes with given name.
*
* @return VBox status code.
* @param hparent Handle of parent node.
* @param pszChildName Name of the child node (UTF-8), NULL for all children.
* @param pCount Pointer to unsigned variable where to store the count.
*/
CFGLDRR3DECL(int) CFGLDRCountChildren(CFGNODE hnode, const char *pszChildName, unsigned *pCount);
/**
* Query 32 bit unsigned value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pu32Value Pointer to 32 bit variable where to store the value.
*/
CFGLDRR3DECL(int) CFGLDRQueryUInt32(CFGNODE hnode, const char *pszName, uint32_t *pu32Value);
/**
* Set 32 bit unsigned value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param u32Value The value.
*/
CFGLDRR3DECL(int) CFGLDRSetUInt32(CFGNODE hnode, const char *pszName, uint32_t u32Value);
/**
* Query 64 bit unsigned value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pu64Value Pointer to 64 bit variable where to store the value.
*/
CFGLDRR3DECL(int) CFGLDRQueryUInt64(CFGNODE hnode, const char *pszName, uint64_t *pu64Value);
/**
* Set 64 bit unsigned value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param u64Value The value.
*/
CFGLDRR3DECL(int) CFGLDRSetUInt64(CFGNODE hnode, const char *pszName, uint64_t u64Value);
/**
* Query 32 bit signed integer value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pint32Value Pointer to 32 bit variable where to store the value.
*/
CFGLDRR3DECL(int) CFGLDRQueryInt32(CFGNODE hnode, const char *pszName, int32_t *pint32Value);
/**
* Set 32 bit signed integer value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param int32Value The value.
*/
CFGLDRR3DECL(int) CFGLDRSetInt32(CFGNODE hnode, const char *pszName, int32_t int32Value);
/**
* Query 64 bit signed integer value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pint64Value Pointer to 64 bit variable where to store the value.
*/
CFGLDRR3DECL(int) CFGLDRQueryInt64(CFGNODE hnode, const char *pszName, int64_t *pint64Value);
/**
* Set 64 bit signed integer value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param int64Value The value.
*/
CFGLDRR3DECL(int) CFGLDRSetInt64(CFGNODE hnode, const char *pszName, int64_t int64Value);
/**
* Query 16 bit unsigned integer value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pu16Value Pointer to 16 bit variable where to store the value.
*/
CFGLDRR3DECL(int) CFGLDRQueryUInt16(CFGNODE hnode, const char *pszName, uint16_t *pu16Value);
/**
* Set 16 bit unsigned integer value attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param u16Value The value.
*/
CFGLDRR3DECL(int) CFGLDRSetUInt16(CFGNODE hnode, const char *pszName, uint16_t u16Value);
/**
* Query binary data attribute. If the size of the buffer (cbValue)
* is smaller than the binary data size, the VERR_BUFFER_OVERFLOW status
* code is returned and the actual data size is stored into the variable
* pointed to by pcbValue; pvValue is ignored in this case.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pvValue Where to store the binary data.
* @param cbValue Size of buffer pvValue points to.
* @param pcbValue Where to store the number of bytes actually retrieved.
*/
CFGLDRR3DECL(int) CFGLDRQueryBin(CFGNODE hnode, const char *pszName, void *pvValue, unsigned cbValue, unsigned *pcbValue);
/**
* Set binary data attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pvValue The binary data to store.
* @param cbValue Size of buffer pvValue points to.
*/
CFGLDRR3DECL(int) CFGLDRSetBin(CFGNODE hnode, const char *pszName, void *pvValue, unsigned cbValue);
/**
* Queries a string attribute. If the size of the buffer (cbValue)
* is smaller than the length of the string, the VERR_BUFFER_OVERFLOW status
* code is returned and the actual string length is stored into the variable
* pointed to by pcbValue; pszValue is ignored in this case.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pszValue Where to store the string (UTF-8).
* @param cbValue Size of buffer pszValue points to, including the terminating zero.
* @param pcbValue Where to store the number of bytes actually retrieved, including the terminating zero.
*/
CFGLDRR3DECL(int) CFGLDRQueryString(CFGNODE hnode, const char *pszName, char *pszValue, unsigned cbValue, unsigned *pcbValue);
#ifdef CFGLDR_HAVE_COM
/**
* Queries a string attribute and returns it as an allocated OLE BSTR.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param ppuszValue Where to store the pointer to the allocated BSTR.
*/
CFGLDRR3DECL(int) CFGLDRQueryBSTR(CFGNODE hnode, const char *pszName, BSTR *ppuszValue);
#endif // CFGLDR_HAVE_COM
/**
* Queries a UUID attribute and returns it into the supplied buffer.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pUUID Where to store the UUID.
*/
CFGLDRR3DECL(int) CFGLDRQueryUUID(CFGNODE hnode, const char *pszName, PRTUUID pUUID);
/**
* Set UUID attribute. It will be put inside curly brackets.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pUuid The uuid.
*/
CFGLDRR3DECL(int) CFGLDRSetUUID(CFGNODE hnode, const char *pszName, PCRTUUID pUuid);
/**
* Set string attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pszValue The string (UTF-8).
* @param cbValue Size of buffer pszValue points to.
*/
CFGLDRR3DECL(int) CFGLDRSetString(CFGNODE hnode, const char *pszName, const char *pszValue);
#ifdef CFGLDR_HAVE_COM
/**
* Set BSTR attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param bstrValue The string (COM BSTR).
* @param cbValue Size of buffer pszValue points to.
*/
CFGLDRR3DECL(int) CFGLDRSetBSTR(CFGNODE hnode, const char *pszName, const BSTR bstrValue);
#endif // CFGLDR_HAVE_COM
/**
* Queries a boolean attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pfValue Where to store the value.
*/
CFGLDRR3DECL(int) CFGLDRQueryBool(CFGNODE hnode, const char *pszName, bool *pfValue);
/**
* Sets a boolean attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param fValue The boolean value.
*/
CFGLDRR3DECL(int) CFGLDRSetBool(CFGNODE hnode, const char *pszName, bool fValue);
/**
* Query 64-bit unix time (in milliseconds since 1970-01-01 UTC).
* The specified node or attribute must be a string in xsd:dateTime format.
*
* Currently, only the UTC ('Z') time zone is supported and must always present.
* If there is a different timezone, or no timezone at all, VERR_PARSE_ERROR
* is returned (use XML Schema constarints to limit the value space and prevent
* this error).
*
* Also note that the minimum 64-bit unix date year is
* about -292269053 and the maximum year is about ~292272993.
* It's a good idea to limit the max and min date values in the XML Schema
* as well, to something like -200000000 to 200000000.
*
* @return VBox status code.
* @param hnode Node which attribute will be queried.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param pu64Value Pointer to 64 bit variable where to store the time value.
*/
CFGLDRR3DECL(int) CFGLDRQueryDateTime(CFGNODE hnode, const char *pszName, int64_t *pi64Value);
/**
* Set 64-bit unix time (in milliseconds since 1970-01-01 UTC).
* Time is written to the specified node or attribute in the xsd:format.
*
* @return VBox status code.
* @param hnode Node which attribute will be set.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
* @param u64Value The time value.
*/
CFGLDRR3DECL(int) CFGLDRSetDateTime(CFGNODE hnode, const char *pszName, int64_t i64Value);
/**
* Delete an attribute.
*
* @return VBox status code.
* @param hnode Node which attribute will be deleted.
* @param pszName Name of the attribute (UTF-8), NULL for the node value.
*/
CFGLDRR3DECL(int) CFGLDRDeleteAttribute(CFGNODE hnode, const char *pszName);
// hack to not have to define BSTR
#ifdef BSTR_REDEFINED
#undef BSTR
#endif
#endif /* IN_RING3 */
__END_DECLS
/** @} */
#endif /* __VBox_cfgldr_h__ */