cfgldr.h@ 4388

Last change on this file since 4388 was 4337, checked in by vboxsync, 17 years ago
Mian/CFGLDR: Use IPRT functions to do string<->integer conversion (this also fixed some memory lieaks).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 26.3 KB

Line
1	/** @file
2	* CFGLDR - Configuration Loader
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
17	#ifndef ___VBox_cfgldr_h
18	#define ___VBox_cfgldr_h
19
20	#include <VBox/cdefs.h>
21	#include <VBox/types.h>
22	#include <iprt/string.h>
23
24
25	/** @defgroup grp_cfgldr The Configuration Loader API
26	* @{
27	*/
28
29	#ifndef IN_RING3
30	# error "There are no configuration loader APIs available in Ring-0 Context!"
31	#else /* IN_RING3 */
32
33	/** @def IN_CFGLDR_R3
34	* Used to indicate whether we're inside the same link module as the
35	* Configuration Loader.
36	*/
37	#ifdef IN_CFGLDR_R3
38	# define CFGLDRR3DECL(type) DECLEXPORT(type) VBOXCALL
39	#else
40	# define CFGLDRR3DECL(type) DECLIMPORT(type) VBOXCALL
41	#endif
42
43	/** @type CFGHANDLE
44	* Configuration handle. */
45	/** @type CFGNODE
46	* Configuration node handle. */
47	#ifdef __cplusplus
48	class CfgLoader;
49	typedef CfgLoader *CFGHANDLE;
50
51	class CfgNode;
52	typedef CfgNode *CFGNODE;
53	#else
54	struct CfgLoader;
55	typedef struct CfgLoader *CFGHANDLE;
56
57	struct CfgNode;
58	typedef struct CfgNode *CFGNODE;
59	#endif
60
61	/** Entity type */
62	typedef enum CFGLDRENTITYTYPE
63	{
64	CFGLDRENTITYTYPE_INVALID = 0, /*< Invalid type /
65	CFGLDRENTITYTYPE_HANDLE, /*< File handle /
66	CFGLDRENTITYTYPE_MEMORY /*< Memory buffer /
67	} CFGLDRENTITYTYPE;
68
69	/** Entity descriptor for the entity resolver callback */
70	typedef struct CFGLDRENTITY
71	{
72	/** Entity type */
73	CFGLDRENTITYTYPE enmType;
74
75	union
76	{
77	/** File handle (CFGLDRENTITYTYPE_HANDLE) */
78	struct
79	{
80	RTFILE hFile; /*< Handle of the file opened for reading entity data /
81	bool bClose; /*< Whether to close the handle when no more needed /
82	} handle;
83	/** Memory buffer (CFGLDRENTITYTYPE_MEMORY) */
84	struct
85	{
86	unsigned char puchBuf; /< Byte array containing entity data /
87	size_t cbBuf; /*< Size of the puchBuf array /
88	bool bFree; /**< Whether to free puchBuf using RTMemTmpFree()
89	when no more needed */
90	} memory;
91	} u;
92
93	} CFGLDRRESOLVEDENTITY;
94
95	/** Pointer to CFGLDRENTITY */
96	typedef CFGLDRENTITY *PCFGLDRENTITY;
97	/** Pointer to const CFGLDRENTITY */
98	typedef const CFGLDRENTITY *PCCFGLDRENTITY;
99
100	/**
101	* Callback function used by CFGLDRLoad() to resolve external entities when
102	* loading and parsing the configuration file,
103	*
104	* First three arguments are input parameters, describing the entity to resolve.
105	* On return, the callback fills in a CFGLDRENTITY structure pointed to by the
106	* pEntity argument, with values corresponding to the given entity.
107	*
108	* @param pcszPublicId
109	* Public ID of the entity in question (UTF-8)
110	* @param pcszSystemId
111	* System ID (URI) of the entity in question (UTF-8)
112	* @param pcszBaseURI
113	* Base URI of the entity necessary to resolve relative URIs (UTF-8)
114	* @param pEntity
115	* Pointer to the entity descriptor structure to fill in
116	*
117	* @return
118	* VINF_SUCCESS to indicate that pEntity is successfully filled in by the
119	* callback. Any other value will cause the configuration
120	* loader to use the default entity resolver (see pfnEntityResolver in
121	* CFGLDRLoad()).
122	*/
123	typedef DECLCALLBACK(int) FNCFGLDRENTITYRESOLVER(const char *pcszPublicId,
124	const char *pcszSystemId,
125	const char *pcszBaseURI,
126	PCFGLDRENTITY pEntity);
127	/** Pointer to entity resolver callback. */
128	typedef FNCFGLDRENTITYRESOLVER *PFNCFGLDRENTITYRESOLVER;
129
130	__BEGIN_DECLS
131
132	/**
133	* Initializes CFGLDR, have to be called at VBox startup before accessing any CFGLDR functions.
134	*
135	* @return VBox status code.
136	*/
137	CFGLDRR3DECL(int) CFGLDRInitialize(void);
138
139	/**
140	* Deletes all configurations and nodes at VBox termination. After calling this function all CFGLDR functions will be unavailable.
141	*
142	* @return VBox status code.
143	*/
144	CFGLDRR3DECL(void) CFGLDRShutdown(void);
145
146	/**
147	* Creates a configuration file from scratch. The file then can be saved
148	* using the CFGLDRSaveAs() function.
149	*
150	* @return VBox status code.
151	*/
152	CFGLDRR3DECL(int) CFGLDRCreate(CFGHANDLE *phcfg);
153
154	/**
155	* Loads a configuration file.
156	*
157	* @param phcfg
158	* Pointer to a handle that will be used to access the configuration.
159	* @param pszFilename
160	* Name of the file containing the configuration (UTF-8).
161	* @param hFileHandle
162	* Handle of the file containing the configuration. If equals to NIL_RTFILE,
163	* an attempt to open the specified file will be made; otherwise
164	* it must be a valid file handle corresponding to the given file name
165	* opened at least for reading.
166	* @param pszExternalSchemaLocation
167	* Name of the file containing namespaceless XML Schema for the configuration
168	* file or one or more pairs (separated by spaces) consiting of a namespace
169	* and an XML schema file for the given namespace, depending on the
170	* value of bDoNamespaces. The parameter can be NULL to indicate that
171	* no validation of the configuration file should be done.
172	* @param bDoNamespaces
173	* If TRUE, namespace processing is turned on and pszExternalSchemaLocation
174	* is assumed to contain "namespace schema-file" pairs; otherwise namespaces
175	* are disabled and pszExternalSchemaLocation is assumed to be a single file
176	* name. The parameter ignored if pszExternalSchemaLocation is NULL.
177	* @param pfnEntityResolver
178	* Callback used to resolve external entities in the configuration file.
179	* Note that the configuration file itself is always accessed directly
180	* (using the given file name or file handle), but all external entities it
181	* refers to, as well as all schema files, are resolved using this callback.
182	* This parameter can be NULL, in which case the default resolver is used
183	* which simply tries to open an entity by its system ID (URI).
184	* @param ppszErrorMessage
185	* Address of a variable that will receive a pointer to an UTF-8 string
186	* containing all error messages produced by a parser while parsing and
187	* validating the configuration file. If non-NULL pointer is returned, the
188	* caller must free the string using RTStrFree(). The parameter can be
189	* NULL on input (no error string will be returned), and it can point to
190	* NULL on output indicating that no error message was provided.
191	* If the function succeeds, the returned string is always NULL.
192	*
193	* @return VBox status code.
194	*/
195	CFGLDRR3DECL(int) CFGLDRLoad(CFGHANDLE *phcfg,
196	const char *pszFileName, RTFILE hFileHandle,
197	const char *pszExternalSchemaLocation, bool bDoNamespaces,
198	PFNCFGLDRENTITYRESOLVER pfnEntityResolver,
199	char **ppszErrorMessage);
200
201	/**
202	* Frees the previously loaded configuration.
203	*
204	* @return VBox status code.
205	* @param hcfg Handle of configuration that was loaded using CFGLDRLoad().
206	*/
207	CFGLDRR3DECL(int) CFGLDRFree(CFGHANDLE hcfg);
208
209	/**
210	* Saves the previously loaded configuration.
211	*
212	* @param hcfg
213	* Handle of the configuration that was loaded using CFGLDRLoad().
214	* @param ppszErrorMessage
215	* Address of a variable that will receive a pointer to an UTF-8 string
216	* containing all error messages produced by a writer while saving
217	* the configuration file. If non-NULL pointer is returned, the
218	* caller must free the string using RTStrFree(). The parameter can be
219	* NULL on input (no error string will be returned), and it can point to
220	* NULL on output indicating that no error message was provided.
221	* If the function succeeds, the returned string is always NULL.
222	*
223	* @return VBox status code.
224	*/
225	CFGLDRR3DECL(int) CFGLDRSave(CFGHANDLE hcfg,
226	char **ppszErrorMessage);
227	/**
228	* Saves the configuration to a specified file.
229	*
230	* @param hcfg
231	* Handle of the configuration that was loaded using CFGLDRLoad().
232	* @param pszFilename
233	* Name of the file to save the configuration to (UTF-8).
234	* @param hFileHandle
235	* Handle of the file to save the configuration to. If equals to NIL_RTFILE,
236	* an attempt to open the specified file will be made; otherwise
237	* it must be a valid file handle corresponding to the given file name
238	* opened at least for writting.
239	* @param ppszErrorMessage
240	* Address of a variable that will receive a pointer to an UTF-8 string
241	* containing all error messages produced by a writer while saving
242	* the configuration file. If non-NULL pointer is returned, the
243	* caller must free the string using RTStrFree(). The parameter can be
244	* NULL on input (no error string will be returned), and it can point to
245	* NULL on output indicating that no error message was provided.
246	* If the function succeeds, the returned string is always NULL.
247	*
248	* @return VBox status code.
249	*/
250	CFGLDRR3DECL(int) CFGLDRSaveAs(CFGHANDLE hcfg,
251	const char *pszFilename, RTFILE hFileHandle,
252	char **ppszErrorMessage);
253
254	/**
255	* Applies an XSLT transformation to the given configuration handle.
256	*
257	* @param hcfg
258	* Handle of the configuration that was loaded using CFGLDRLoad().
259	* @param pszTemlateLocation
260	* Name of the file containing an XSL template to apply
261	* @param pfnEntityResolver
262	* Callback used to resolve external entities (the XSL template file).
263	* This parameter can be NULL, in which case the default resolver is used
264	* which simply tries to open an entity by its system ID (URI).
265	* @param ppszErrorMessage
266	* Address of a variable that will receive a pointer to an UTF-8 string
267	* containing all error messages produced by a parser while parsing and
268	* validating the configuration file. If non-NULL pointer is returned, the
269	* caller must free the string using RTStrFree(). The parameter can be
270	* NULL on input (no error string will be returned), and it can point to
271	* NULL on output indicating that no error message was provided.
272	* If the function succeeds, the returned string is always NULL.
273	*/
274	CFGLDRR3DECL(int) CFGLDRTransform (CFGHANDLE hcfg,
275	const char *pszTemlateLocation,
276	PFNCFGLDRENTITYRESOLVER pfnEntityResolver,
277	char **ppszErrorMessage);
278
279	/**
280	* Get node handle.
281	*
282	* @return VBox status code.
283	* @param hcfg Handle of configuration that was loaded using CFGLDRLoad().
284	* @param pszName Name of the node (UTF-8).
285	* @param uIndex Index of the node (0 based).
286	* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
287	*/
288	CFGLDRR3DECL(int) CFGLDRGetNode(CFGHANDLE hcfg, const char pszName, unsigned uIndex, CFGNODE phnode);
289
290	/**
291	* Get child node handle.
292	*
293	* @return VBox status code.
294	* @param hparent Handle of parent node.
295	* @param pszName Name of the child node (UTF-8), NULL for any child.
296	* @param uIndex Index of the child node (0 based).
297	* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
298	*/
299	CFGLDRR3DECL(int) CFGLDRGetChildNode(CFGNODE hparent, const char pszName, unsigned uIndex, CFGNODE phnode);
300
301	/**
302	* Creates a new node or returns the first one with a given name if
303	* already exists.
304	*
305	* @return VBox status code.
306	* @param hcfg Handle of the configuration.
307	* @param pszName Name of the node to be created (UTF-8).
308	* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
309	*/
310	CFGLDRR3DECL(int) CFGLDRCreateNode(CFGHANDLE hcfg, const char pszName, CFGNODE phnode);
311
312	/**
313	* Creates a new child node or returns the first one with a given name if
314	* already exists.
315	*
316	* @return VBox status code.
317	* @param hparent Handle of parent node.
318	* @param pszName Name of the child node (UTF-8).
319	* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
320	*/
321	CFGLDRR3DECL(int) CFGLDRCreateChildNode(CFGNODE hparent, const char pszName, CFGNODE phnode);
322
323	/**
324	* Appends a new child node.
325	*
326	* @return VBox status code.
327	* @param hparent Handle of parent node.
328	* @param pszName Name of the child node (UTF-8).
329	* @param phnode Pointer to a handle that will be used to access the node attributes, value and child nodes.
330	*/
331	CFGLDRR3DECL(int) CFGLDRAppendChildNode(CFGNODE hparent, const char pszName, CFGNODE phnode);
332
333	/**
334	* Release node handle.
335	*
336	* @return VBox status code.
337	* @param hnode Handle that will not be used anymore.
338	*/
339	CFGLDRR3DECL(int) CFGLDRReleaseNode(CFGNODE hnode);
340
341	/**
342	* Delete node. The handle is released and the entire node is removed.
343	*
344	* @return VBox status code.
345	* @param hnode Handle of node that will be deleted.
346	*/
347	CFGLDRR3DECL(int) CFGLDRDeleteNode(CFGNODE hnode);
348
349	/**
350	* Count child nodes with given name.
351	*
352	* @return VBox status code.
353	* @param hparent Handle of parent node.
354	* @param pszChildName Name of the child node (UTF-8), NULL for all children.
355	* @param pCount Pointer to unsigned variable where to store the count.
356	*/
357	CFGLDRR3DECL(int) CFGLDRCountChildren(CFGNODE hnode, const char pszChildName, unsigned pCount);
358
359	/**
360	* Query 32 bit unsigned value attribute.
361	*
362	* @return VBox status code.
363	* @param hnode Node which attribute will be queried.
364	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
365	* @param pulValue Pointer to 32 bit variable where to store the value.
366	*/
367	CFGLDRR3DECL(int) CFGLDRQueryUInt32(CFGNODE hnode, const char pszName, uint32_t pulValue);
368
369	/**
370	* Set 32 bit unsigned value attribute.
371	*
372	* @return VBox status code.
373	* @param hnode Node which attribute will be set.
374	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
375	* @param ulValue The value.
376	*/
377	CFGLDRR3DECL(int) CFGLDRSetUInt32(CFGNODE hnode, const char *pszName, uint32_t ulValue);
378
379	/**
380	* Set 32 bit unsigned value attribute.
381	*
382	* @return VBox status code.
383	* @param hnode Node which attribute will be set.
384	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
385	* @param ulValue The value.
386	* @patam uiBase 0, 8 or 16.
387	*/
388	CFGLDRR3DECL(int) CFGLDRSetUInt32Ex(CFGNODE hnode, const char *pszName, uint32_t ulValue, unsigned int uiBase);
389
390	/**
391	* Query 64 bit unsigned value attribute.
392	*
393	* @return VBox status code.
394	* @param hnode Node which attribute will be queried.
395	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
396	* @param pullValue Pointer to 64 bit variable where to store the value.
397	*/
398	CFGLDRR3DECL(int) CFGLDRQueryUInt64(CFGNODE hnode, const char pszName, uint64_t pullValue);
399
400	/**
401	* Set 64 bit unsigned value attribute.
402	*
403	* @return VBox status code.
404	* @param hnode Node which attribute will be set.
405	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
406	* @param ullValue The value.
407	*/
408	CFGLDRR3DECL(int) CFGLDRSetUInt64(CFGNODE hnode, const char *pszName, uint64_t ullValue);
409
410	/**
411	* Set 64 bit unsigned value attribute.
412	*
413	* @return VBox status code.
414	* @param hnode Node which attribute will be set.
415	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
416	* @param ullValue The value.
417	* @patam uiBase 0, 8 or 16.
418	*/
419	CFGLDRR3DECL(int) CFGLDRSetUInt64Ex(CFGNODE hnode, const char *pszName, uint64_t ullValue, unsigned int uiBase);
420
421	/**
422	* Query 32 bit signed integer value attribute.
423	*
424	* @return VBox status code.
425	* @param hnode Node which attribute will be queried.
426	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
427	* @param plValue Pointer to 32 bit variable where to store the value.
428	*/
429	CFGLDRR3DECL(int) CFGLDRQueryInt32(CFGNODE hnode, const char pszName, int32_t plValue);
430
431	/**
432	* Set 32 bit signed integer value attribute.
433	*
434	* @return VBox status code.
435	* @param hnode Node which attribute will be set.
436	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
437	* @param lValue The value.
438	*/
439	CFGLDRR3DECL(int) CFGLDRSetInt32(CFGNODE hnode, const char *pszName, int32_t lValue);
440
441	/**
442	* Set 32 bit signed integer value attribute.
443	*
444	* @return VBox status code.
445	* @param hnode Node which attribute will be set.
446	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
447	* @param lValue The value.
448	* @patam uiBase 0, 8 or 16.
449	*/
450	CFGLDRR3DECL(int) CFGLDRSetInt32Ex(CFGNODE hnode, const char *pszName, int32_t lValue, unsigned int uiBase);
451
452	/**
453	* Query 64 bit signed integer value attribute.
454	*
455	* @return VBox status code.
456	* @param hnode Node which attribute will be queried.
457	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
458	* @param pllValue Pointer to 64 bit variable where to store the value.
459	*/
460	CFGLDRR3DECL(int) CFGLDRQueryInt64(CFGNODE hnode, const char pszName, int64_t pllValue);
461
462	/**
463	* Set 64 bit signed integer value attribute.
464	*
465	* @return VBox status code.
466	* @param hnode Node which attribute will be set.
467	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
468	* @param llValue The value.
469	*/
470	CFGLDRR3DECL(int) CFGLDRSetInt64(CFGNODE hnode, const char *pszName, int64_t llValue);
471
472	/**
473	* Set 64 bit signed integer value attribute.
474	*
475	* @return VBox status code.
476	* @param hnode Node which attribute will be set.
477	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
478	* @param llValue The value.
479	* @patam uiBase 0, 8 or 16.
480	*/
481	CFGLDRR3DECL(int) CFGLDRSetInt64Ex(CFGNODE hnode, const char *pszName, int64_t llValue, unsigned int uiBase);
482
483	/**
484	* Query 16 bit unsigned integer value attribute.
485	*
486	* @return VBox status code.
487	* @param hnode Node which attribute will be queried.
488	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
489	* @param puhValue Pointer to 16 bit variable where to store the value.
490	*/
491	CFGLDRR3DECL(int) CFGLDRQueryUInt16(CFGNODE hnode, const char pszName, uint16_t puhValue);
492
493	/**
494	* Set 16 bit unsigned integer value attribute.
495	*
496	* @return VBox status code.
497	* @param hnode Node which attribute will be set.
498	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
499	* @param uhValue The value.
500	*/
501	CFGLDRR3DECL(int) CFGLDRSetUInt16(CFGNODE hnode, const char *pszName, uint16_t uhValue);
502
503	/**
504	* Set 16 bit unsigned integer value attribute.
505	*
506	* @return VBox status code.
507	* @param hnode Node which attribute will be set.
508	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
509	* @param uhValue The value.
510	* @patam uiBase 0, 8 or 16.
511	*/
512	CFGLDRR3DECL(int) CFGLDRSetUInt16Ex(CFGNODE hnode, const char *pszName, uint16_t uhValue, unsigned int uiBase);
513
514	/**
515	* Query binary data attribute. If the size of the buffer (cbValue)
516	* is smaller than the binary data size, the VERR_BUFFER_OVERFLOW status
517	* code is returned and the actual data size is stored into the variable
518	* pointed to by pcbValue; pvValue is ignored in this case.
519	*
520	* @return VBox status code.
521	* @param hnode Node which attribute will be queried.
522	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
523	* @param pvValue Where to store the binary data.
524	* @param cbValue Size of buffer pvValue points to.
525	* @param pcbValue Where to store the number of bytes actually retrieved.
526	*/
527	CFGLDRR3DECL(int) CFGLDRQueryBin(CFGNODE hnode, const char pszName, void pvValue, unsigned cbValue, unsigned *pcbValue);
528
529	/**
530	* Set binary data attribute.
531	*
532	* @return VBox status code.
533	* @param hnode Node which attribute will be set.
534	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
535	* @param pvValue The binary data to store.
536	* @param cbValue Size of buffer pvValue points to.
537	*/
538	CFGLDRR3DECL(int) CFGLDRSetBin(CFGNODE hnode, const char pszName, void pvValue, unsigned cbValue);
539
540	/**
541	* Queries a string attribute. If the size of the buffer (cbValue)
542	* is smaller than the length of the string, the VERR_BUFFER_OVERFLOW status
543	* code is returned and the actual string length is stored into the variable
544	* pointed to by pcbValue; pszValue is ignored in this case.
545	*
546	* @return VBox status code.
547	* @param hnode Node which attribute will be queried.
548	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
549	* @param pszValue Where to store the string (UTF-8).
550	* @param cbValue Size of buffer pszValue points to, including the terminating zero.
551	* @param pcbValue Where to store the number of bytes actually retrieved, including the terminating zero.
552	*/
553	CFGLDRR3DECL(int) CFGLDRQueryString(CFGNODE hnode, const char pszName, char pszValue, unsigned cbValue, unsigned *pcbValue);
554
555	#ifdef CFGLDR_HAVE_COM
556	/**
557	* Queries a string attribute and returns it as an allocated OLE BSTR.
558	*
559	* @return VBox status code.
560	* @param hnode Node which attribute will be queried.
561	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
562	* @param ppuszValue Where to store the pointer to the allocated BSTR.
563	*/
564	CFGLDRR3DECL(int) CFGLDRQueryBSTR(CFGNODE hnode, const char pszName, BSTR ppuszValue);
565	#endif // CFGLDR_HAVE_COM
566
567	/**
568	* Queries a UUID attribute and returns it into the supplied buffer.
569	*
570	* @return VBox status code.
571	* @param hnode Node which attribute will be queried.
572	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
573	* @param pUUID Where to store the UUID.
574	*/
575	CFGLDRR3DECL(int) CFGLDRQueryUUID(CFGNODE hnode, const char *pszName, PRTUUID pUUID);
576
577	/**
578	* Set UUID attribute. It will be put inside curly brackets.
579	*
580	* @return VBox status code.
581	* @param hnode Node which attribute will be set.
582	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
583	* @param pUuid The uuid.
584	*/
585	CFGLDRR3DECL(int) CFGLDRSetUUID(CFGNODE hnode, const char *pszName, PCRTUUID pUuid);
586
587	/**
588	* Set string attribute.
589	*
590	* @return VBox status code.
591	* @param hnode Node which attribute will be set.
592	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
593	* @param pszValue The string (UTF-8).
594	* @param cbValue Size of buffer pszValue points to.
595	*/
596	CFGLDRR3DECL(int) CFGLDRSetString(CFGNODE hnode, const char pszName, const char pszValue);
597
598	#ifdef CFGLDR_HAVE_COM
599	/**
600	* Set BSTR attribute.
601	*
602	* @return VBox status code.
603	* @param hnode Node which attribute will be set.
604	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
605	* @param bstrValue The string (COM BSTR).
606	* @param cbValue Size of buffer pszValue points to.
607	*/
608	CFGLDRR3DECL(int) CFGLDRSetBSTR(CFGNODE hnode, const char *pszName, const BSTR bstrValue);
609	#endif // CFGLDR_HAVE_COM
610
611	/**
612	* Queries a boolean attribute.
613	*
614	* @return VBox status code.
615	* @param hnode Node which attribute will be queried.
616	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
617	* @param pfValue Where to store the value.
618	*/
619	CFGLDRR3DECL(int) CFGLDRQueryBool(CFGNODE hnode, const char pszName, bool pfValue);
620
621	/**
622	* Sets a boolean attribute.
623	*
624	* @return VBox status code.
625	* @param hnode Node which attribute will be queried.
626	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
627	* @param fValue The boolean value.
628	*/
629	CFGLDRR3DECL(int) CFGLDRSetBool(CFGNODE hnode, const char *pszName, bool fValue);
630
631	/**
632	* Query 64-bit unix time (in milliseconds since 1970-01-01 UTC).
633	* The specified node or attribute must be a string in xsd:dateTime format.
634	*
635	* Currently, only the UTC ('Z') time zone is supported and must always present.
636	* If there is a different timezone, or no timezone at all, VERR_PARSE_ERROR
637	* is returned (use XML Schema constarints to limit the value space and prevent
638	* this error).
639	*
640	* Also note that the minimum 64-bit unix date year is
641	* about -292269053 and the maximum year is about ~292272993.
642	* It's a good idea to limit the max and min date values in the XML Schema
643	* as well, to something like -200000000 to 200000000.
644	*
645	* @return VBox status code.
646	* @param hnode Node which attribute will be queried.
647	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
648	* @param pu64Value Pointer to 64 bit variable where to store the time value.
649	*/
650	CFGLDRR3DECL(int) CFGLDRQueryDateTime(CFGNODE hnode, const char pszName, int64_t pi64Value);
651
652	/**
653	* Set 64-bit unix time (in milliseconds since 1970-01-01 UTC).
654	* Time is written to the specified node or attribute in the xsd:format.
655	*
656	* @return VBox status code.
657	* @param hnode Node which attribute will be set.
658	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
659	* @param u64Value The time value.
660	*/
661	CFGLDRR3DECL(int) CFGLDRSetDateTime(CFGNODE hnode, const char *pszName, int64_t i64Value);
662
663	/**
664	* Delete an attribute.
665	*
666	* @return VBox status code.
667	* @param hnode Node which attribute will be deleted.
668	* @param pszName Name of the attribute (UTF-8), NULL for the node value.
669	*/
670	CFGLDRR3DECL(int) CFGLDRDeleteAttribute(CFGNODE hnode, const char *pszName);
671
672	// hack to not have to define BSTR
673	#ifdef BSTR_REDEFINED
674	#undef BSTR
675	#endif
676
677	#endif /* IN_RING3 */
678
679	__END_DECLS
680
681	/** @} */
682
683	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/VBox/cfgldr.h@ 4388

Download in other formats: