restbase.h@ 74126

Last change on this file since 74126 was 74117, checked in by vboxsync, 6 years ago
IPRT/rest: Started implemented more flexible handling of binary uploads and downloads. bugref:9167
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 24.8 KB

Line
1	/** @file
2	* IPRT - C++ Representational State Transfer (REST) Base Classes.
3	*/
4
5	/*
6	* Copyright (C) 2008-2018 Oracle Corporation
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 (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.
24	*/
25
26	#ifndef ___iprt_cpp_restbase_h
27	#define ___iprt_cpp_restbase_h
28
29	#include <iprt/cdefs.h>
30	#include <iprt/types.h>
31	#include <iprt/json.h>
32	#include <iprt/stdarg.h>
33	#include <iprt/cpp/ministring.h>
34
35
36	/** @defgroup grp_rt_cpp_restbase C++ Representational State Transfer (REST) Base Classes.
37	* @ingroup grp_rt_cpp
38	* @{
39	*/
40
41
42
43	/**
44	* Abstract base class for serializing data objects.
45	*/
46	class RT_DECL_CLASS RTCRestOutputBase
47	{
48	public:
49	RTCRestOutputBase()
50	: m_uIndent(0)
51	{ }
52	virtual ~RTCRestOutputBase()
53	{ }
54
55	/**
56	* RTStrPrintf like function (see @ref pg_rt_str_format).
57	*
58	* @returns Number of bytes outputted.
59	* @param pszFormat The format string.
60	* @param ... Argument specfied in @a pszFormat.
61	*/
62	size_t printf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3)
63	{
64	va_list va;
65	va_start(va, pszFormat);
66	size_t cchWritten = this->vprintf(pszFormat, va);
67	va_end(va);
68	return cchWritten;
69	}
70
71	/**
72	* RTStrPrintfV like function (see @ref pg_rt_str_format).
73	*
74	* @returns Number of bytes outputted.
75	* @param pszFormat The format string.
76	* @param va Argument specfied in @a pszFormat.
77	*/
78	virtual size_t vprintf(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0) = 0;
79
80	/**
81	* Sets the indentation level for use when pretty priting things.
82	*
83	* @returns Previous indentation level.
84	* @param uIndent The indentation level.
85	*/
86	unsigned setIndent(unsigned uIndent)
87	{
88	unsigned const uRet = m_uIndent;
89	m_uIndent = uIndent;
90	return uRet;
91	}
92
93	/**
94	* Increases the indentation level.
95	*
96	* @returns Previous indentation level.
97	*/
98	unsigned incrementIndent()
99	{
100	unsigned const uRet = m_uIndent;
101	m_uIndent = uRet + 1;
102	return uRet;
103	}
104
105	protected:
106	/** The current indentation level. */
107	unsigned m_uIndent;
108	};
109
110
111	/**
112	* Serialize to a string object.
113	*/
114	class RT_DECL_CLASS RTCRestOutputToString : public RTCRestOutputBase
115	{
116	public:
117	/**
118	* Creates an instance that appends to @a a_pDst.
119	* @param a_pDst Pointer to the destination string object.
120	* NULL is not accepted and will assert.
121	* @param a_fAppend Whether to append to the current string value, or
122	* nuke the string content before starting the output.
123	*/
124	RTCRestOutputToString(RTCString *a_pDst, bool a_fAppend = false);
125	virtual ~RTCRestOutputToString();
126
127	virtual size_t vprintf(const char *pszFormat, va_list va) RT_OVERRIDE;
128
129	/**
130	* Finalizes the output and releases the string object to the caller.
131	*
132	* @returns The released string object. NULL if we ran out of memory or if
133	* called already.
134	*
135	* @remark This sets m_pDst to NULL and the object cannot be use for any
136	* more output afterwards.
137	*/
138	virtual RTCString *finalize();
139
140
141	protected:
142	/** Pointer to the destination string. NULL after finalize(). */
143	RTCString *m_pDst;
144	/** Set if we ran out of memory and should ignore subsequent calls. */
145	bool m_fOutOfMemory;
146
147	/** @callback_method_impl{FNRTSTROUTPUT} */
148	static DECLCALLBACK(size_t) strOutput(void pvArg, const char pachChars, size_t cbChars);
149
150	/* Make non-copyable (RTCNonCopyable causes warnings): */
151	RTCRestOutputToString(RTCRestOutputToString const &);
152	RTCRestOutputToString *operator=(RTCRestOutputToString const &);
153	};
154
155
156	/* forward decl: */
157	class RTCRestJsonPrimaryCursor;
158
159	/**
160	* JSON cursor structure.
161	*
162	* This reduces the number of parameters passed around when deserializing JSON
163	* input and also helps constructing full object name for logging and error reporting.
164	*/
165	struct RT_DECL_CLASS RTCRestJsonCursor
166	{
167	/** Handle to the value being parsed. */
168	RTJSONVAL m_hValue;
169	/** Name of the value. */
170	const char *m_pszName;
171	/** Pointer to the parent, NULL if primary. */
172	struct RTCRestJsonCursor const *m_pParent;
173	/** Pointer to the primary cursor structure. */
174	RTCRestJsonPrimaryCursor *m_pPrimary;
175
176	RTCRestJsonCursor(struct RTCRestJsonCursor const &a_rParent)
177	: m_hValue(NIL_RTJSONVAL), m_pszName(NULL), m_pParent(&a_rParent), m_pPrimary(a_rParent.m_pPrimary)
178	{ }
179
180	RTCRestJsonCursor(RTJSONVAL hValue, const char pszName, struct RTCRestJsonCursor pParent)
181	: m_hValue(hValue), m_pszName(pszName), m_pParent(pParent), m_pPrimary(pParent->m_pPrimary)
182	{ }
183
184	RTCRestJsonCursor(RTJSONVAL hValue, const char *pszName)
185	: m_hValue(hValue), m_pszName(pszName), m_pParent(NULL), m_pPrimary(NULL)
186	{ }
187
188	~RTCRestJsonCursor()
189	{
190	if (m_hValue != NIL_RTJSONVAL)
191	{
192	RTJsonValueRelease(m_hValue);
193	m_hValue = NIL_RTJSONVAL;
194	}
195	}
196	};
197
198
199	/**
200	* The primary JSON cursor class.
201	*/
202	class RT_DECL_CLASS RTCRestJsonPrimaryCursor
203	{
204	public:
205	/** The cursor for the first level. */
206	RTCRestJsonCursor m_Cursor;
207	/** Error info keeper. */
208	PRTERRINFO m_pErrInfo;
209
210	/** Creates a primary json cursor with optiona error info. */
211	RTCRestJsonPrimaryCursor(RTJSONVAL hValue, const char *pszName, PRTERRINFO pErrInfo = NULL)
212	: m_Cursor(hValue, pszName)
213	, m_pErrInfo(pErrInfo)
214	{
215	m_Cursor.m_pPrimary = this;
216	}
217
218	virtual ~RTCRestJsonPrimaryCursor()
219	{ }
220
221	/**
222	* Add an error message.
223	*
224	* @returns a_rc
225	* @param a_rCursor The cursor reporting the error.
226	* @param a_rc The status code.
227	* @param a_pszFormat Format string.
228	* @param ... Format string arguments.
229	*/
230	virtual int addError(RTCRestJsonCursor const &a_rCursor, int a_rc, const char *a_pszFormat, ...);
231
232	/**
233	* Reports that the current field is not known.
234	*
235	* @returns Status to propagate.
236	* @param a_rCursor The cursor for the field.
237	*/
238	virtual int unknownField(RTCRestJsonCursor const &a_rCursor);
239
240	/**
241	* Copies the full path into pszDst.
242	*
243	* @returns pszDst
244	* @param a_rCursor The cursor to start walking at.
245	* @param a_pszDst Where to put the path.
246	* @param a_cbDst Size of the destination buffer.
247	*/
248	virtual char getPath(RTCRestJsonCursor const &a_rCursor, char a_pszDst, size_t a_cbDst) const;
249	};
250
251
252	/**
253	* Abstract base class for REST data objects.
254	*
255	* The only information this keeps is the null indicator.
256	*/
257	class RT_DECL_CLASS RTCRestObjectBase
258	{
259	public:
260	RTCRestObjectBase();
261	RTCRestObjectBase(RTCRestObjectBase const &a_rThat);
262	virtual ~RTCRestObjectBase();
263
264	/**
265	* Tests if the object is @a null.
266	* @returns true if null, false if not.
267	*/
268	bool isNull(void) const { return m_fNullIndicator; };
269
270	/**
271	* Sets the object to @a null and fills it with defaults.
272	* @returns IPRT status code (from resetToDefault).
273	*/
274	virtual int setNull(void);
275
276	/**
277	* Sets the object to not-null state (i.e. undoes setNull()).
278	* @remarks Only really important for strings.
279	*/
280	virtual void setNotNull(void);
281
282	/**
283	* Resets the object to all default values.
284	* @returns IPRT status code.
285	*/
286	virtual int resetToDefault() = 0;
287
288	/**
289	* Serialize the object as JSON.
290	*
291	* @returns a_rDst
292	* @param a_rDst The destination for the serialization.
293	*/
294	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const = 0;
295
296	/**
297	* Deserialize object from the given JSON iterator.
298	*
299	* @returns IPRT status code.
300	* @param a_rCursor The JSON cursor.
301	*/
302	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) = 0;
303
304	/**
305	* Flags for toString().
306	*
307	* The kCollectionFormat_xxx bunch controls multiple values in arrays
308	* are formatted. They are ignored by everyone else.
309	*
310	* @note When adding collection format types, make sure to also
311	* update RTCRestArrayBase::toString().
312	* @note Bit 24 is reserved (for kHdrField_MapCollection).
313	*/
314	enum
315	{
316	kCollectionFormat_Unspecified = 0, /*< Not specified. /
317	kCollectionFormat_csv, /*< Comma-separated list. /
318	kCollectionFormat_ssv, /*< Space-separated list. /
319	kCollectionFormat_tsv, /*< Tab-separated list. /
320	kCollectionFormat_pipes, /*< Pipe-separated list. /
321	kCollectionFormat_multi, /*< Special collection type that must be handled by caller of toString. /
322	kCollectionFormat_Mask = 7, /*< Collection type mask. /
323
324	kToString_Append = 8 /*< Append to the string (rather than assigning). /
325	};
326
327	/**
328	* String conversion.
329	*
330	* The default implementation of is a wrapper around serializeAsJson().
331	*
332	* @returns IPRT status code.
333	* @param a_pDst Pointer to the destionation string.
334	* @param a_fFlags kCollectionFormat_xxx.
335	*/
336	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const;
337
338	/**
339	* String convertsion, naive variant.
340	*
341	* @returns String represenation.
342	*/
343	RTCString toString() const;
344
345	/**
346	* Convert from (header) string value.
347	*
348	* The default implementation of is a wrapper around deserializeFromJson().
349	*
350	* @returns IPRT status code.
351	* @param a_rValue The string value string to parse.
352	* @param a_pszName Field name or similar.
353	* @param a_pErrInfo Where to return additional error info. Optional.
354	* @param a_fFlags kCollectionFormat_xxx.
355	*/
356	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
357	uint32_t a_fFlags = kCollectionFormat_Unspecified);
358
359	/** Type classification */
360	typedef enum kTypeClass
361	{
362	kTypeClass_Invalid = 0,
363	kTypeClass_Bool, /*< Primitive: bool. /
364	kTypeClass_Int64, /*< Primitive: bool. /
365	kTypeClass_Int32, /*< Primitive: bool. /
366	kTypeClass_Int16, /*< Primitive: bool. /
367	kTypeClass_Double, /*< Primitive: bool. /
368	kTypeClass_String, /*< Primitive: bool. /
369	kTypeClass_Object, /*< Object (any kind of data model object). /
370	kTypeClass_Array, /*< Array (containing any kind of object). /
371	kTypeClass_StringMap, /*< String map (containing any kind of object). /
372	kTypeClass_StringEnum, /*< String enum. /
373	kTypeClass_BinaryString /*< Binary string. /
374	} kTypeClass;
375
376	/**
377	* Returns the object type class.
378	*/
379	virtual kTypeClass typeClass(void) const;
380
381	/**
382	* Returns the object type name.
383	*/
384	virtual const char *typeName(void) const = 0;
385
386	/**
387	* Factory method.
388	* @returns Pointer to new object on success, NULL if out of memory.
389	*/
390	typedef DECLCALLBACK(RTCRestObjectBase *) FNCREATEINSTANCE(void);
391	/** Pointer to factory method. */
392	typedef FNCREATEINSTANCE *PFNCREATEINSTANCE;
393
394	protected:
395	/** Null indicator.
396	* @remarks The null values could be mapped onto C/C++ NULL pointer values,
397	* with the consequence that all data members in objects and such would
398	* have had to been allocated individually, even simple @a bool members.
399	* Given that we're overly paranoid about heap allocations (std::bad_alloc),
400	* it's more fitting to use a null indicator for us.
401	*/
402	bool m_fNullIndicator;
403	};
404
405
406	/**
407	* Class wrapping 'bool'.
408	*/
409	class RT_DECL_CLASS RTCRestBool : public RTCRestObjectBase
410	{
411	public:
412	/** Default constructor. */
413	RTCRestBool();
414	/** Copy constructor. */
415	RTCRestBool(RTCRestBool const &a_rThat);
416	/** From value constructor. */
417	RTCRestBool(bool fValue);
418	/** Destructor. */
419	virtual ~RTCRestBool();
420	/** Copy assignment operator. */
421	RTCRestBool &operator=(RTCRestBool const &a_rThat);
422	/** Safe copy assignment method. */
423	int assignCopy(RTCRestBool const &a_rThat);
424	/** Assign value and clear null indicator. */
425	void assignValue(bool a_fValue);
426
427	/* Overridden methods: */
428	virtual int resetToDefault() RT_OVERRIDE;
429	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
430	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
431	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
432	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
433	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
434	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
435	virtual const char *typeName(void) const RT_OVERRIDE;
436
437	/** Factory method. */
438	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
439
440	public:
441	/** The value. */
442	bool m_fValue;
443	};
444
445
446	/**
447	* Class wrapping 'int64_t'.
448	*/
449	class RT_DECL_CLASS RTCRestInt64 : public RTCRestObjectBase
450	{
451	public:
452	/** Default constructor. */
453	RTCRestInt64();
454	/** Copy constructor. */
455	RTCRestInt64(RTCRestInt64 const &a_rThat);
456	/** From value constructor. */
457	RTCRestInt64(int64_t a_iValue);
458	/** Destructor. */
459	virtual ~RTCRestInt64();
460	/** Copy assignment operator. */
461	RTCRestInt64 &operator=(RTCRestInt64 const &a_rThat);
462	/** Safe copy assignment method. */
463	int assignCopy(RTCRestInt64 const &a_rThat);
464	/** Assign value and clear null indicator. */
465	void assignValue(int64_t a_iValue);
466
467	/* Overridden methods: */
468	virtual int resetToDefault() RT_OVERRIDE;
469	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
470	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
471	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
472	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
473	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
474	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
475	virtual const char *typeName(void) const RT_OVERRIDE;
476
477	/** Factory method. */
478	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
479
480	public:
481	/** The value. */
482	int64_t m_iValue;
483	};
484
485
486	/**
487	* Class wrapping 'int32_t'.
488	*/
489	class RT_DECL_CLASS RTCRestInt32 : public RTCRestObjectBase
490	{
491	public:
492	/** Default constructor. */
493	RTCRestInt32();
494	/** Copy constructor. */
495	RTCRestInt32(RTCRestInt32 const &a_rThat);
496	/** From value constructor. */
497	RTCRestInt32(int32_t iValue);
498	/** Destructor. */
499	virtual ~RTCRestInt32();
500	/** Copy assignment operator. */
501	RTCRestInt32 &operator=(RTCRestInt32 const &a_rThat);
502	/** Safe copy assignment method. */
503	int assignCopy(RTCRestInt32 const &a_rThat);
504	/** Assign value and clear null indicator. */
505	void assignValue(int32_t a_iValue);
506
507	/* Overridden methods: */
508	virtual int resetToDefault() RT_OVERRIDE;
509	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
510	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
511	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
512	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
513	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
514	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
515	virtual const char *typeName(void) const RT_OVERRIDE;
516
517	/** Factory method. */
518	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
519
520	public:
521	/** The value. */
522	int32_t m_iValue;
523	};
524
525
526	/**
527	* Class wrapping 'int16_t'.
528	*/
529	class RT_DECL_CLASS RTCRestInt16 : public RTCRestObjectBase
530	{
531	public:
532	/** Default constructor. */
533	RTCRestInt16();
534	/** Copy constructor. */
535	RTCRestInt16(RTCRestInt16 const &a_rThat);
536	/** From value constructor. */
537	RTCRestInt16(int16_t iValue);
538	/** Destructor. */
539	virtual ~RTCRestInt16();
540	/** Copy assignment operator. */
541	RTCRestInt16 &operator=(RTCRestInt16 const &a_rThat);
542	/** Safe copy assignment method. */
543	int assignCopy(RTCRestInt16 const &a_rThat);
544	/** Assign value and clear null indicator. */
545	void assignValue(int16_t a_iValue);
546
547	/* Overridden methods: */
548	virtual int resetToDefault() RT_OVERRIDE;
549	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
550	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
551	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
552	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
553	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
554	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
555	virtual const char *typeName(void) const RT_OVERRIDE;
556
557	/** Factory method. */
558	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
559
560	public:
561	/** The value. */
562	int16_t m_iValue;
563	};
564
565
566	/**
567	* Class wrapping 'double'.
568	*/
569	class RT_DECL_CLASS RTCRestDouble : public RTCRestObjectBase
570	{
571	public:
572	/** Default constructor. */
573	RTCRestDouble();
574	/** Copy constructor. */
575	RTCRestDouble(RTCRestDouble const &a_rThat);
576	/** From value constructor. */
577	RTCRestDouble(double rdValue);
578	/** Destructor. */
579	virtual ~RTCRestDouble();
580	/** Copy assignment operator. */
581	RTCRestDouble &operator=(RTCRestDouble const &a_rThat);
582	/** Safe copy assignment method. */
583	int assignCopy(RTCRestDouble const &a_rThat);
584	/** Assign value and clear null indicator. */
585	void assignValue(double a_rdValue);
586
587	/* Overridden methods: */
588	virtual int resetToDefault() RT_OVERRIDE;
589	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
590	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
591	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
592	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
593	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
594	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
595	virtual const char *typeName(void) const RT_OVERRIDE;
596
597	/** Factory method. */
598	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
599
600	public:
601	/** The value. */
602	double m_rdValue;
603	};
604
605
606	/**
607	* Class wrapping 'RTCString'.
608	*/
609	class RT_DECL_CLASS RTCRestString : public RTCString, public RTCRestObjectBase
610	{
611	public:
612	/** Default constructor. */
613	RTCRestString();
614	/** Destructor. */
615	virtual ~RTCRestString();
616
617	/** Copy constructor. */
618	RTCRestString(RTCRestString const &a_rThat);
619	/** From value constructor. */
620	RTCRestString(RTCString const &a_rThat);
621	/** From value constructor. */
622	RTCRestString(const char *a_pszSrc);
623	/** Safe copy assignment method. */
624	int assignCopy(RTCRestString const &a_rThat);
625	/** Safe copy assignment method. */
626	int assignCopy(RTCString const &a_rThat);
627	/** Safe copy assignment method. */
628	int assignCopy(const char *a_pszThat);
629
630	/* Overridden methods: */
631	virtual int setNull(void) RT_OVERRIDE; /* (ambigious, so overrider it to make sure.) */
632	virtual int resetToDefault() RT_OVERRIDE;
633	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
634	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
635	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
636	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
637	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
638	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
639	virtual const char *typeName(void) const RT_OVERRIDE;
640
641	/** Factory method. */
642	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
643	};
644
645
646	/**
647	* String enum base class.
648	*/
649	class RT_DECL_CLASS RTCRestStringEnumBase : public RTCRestObjectBase
650	{
651	public:
652	/** Enum map entry. */
653	typedef struct ENUMMAPENTRY
654	{
655	const char *pszName;
656	uint32_t cchName;
657	int32_t iValue;
658	} ENUMMAPENTRY;
659
660	/** Default constructor. */
661	RTCRestStringEnumBase();
662	/** Destructor. */
663	virtual ~RTCRestStringEnumBase();
664
665	/** Copy constructor. */
666	RTCRestStringEnumBase(RTCRestStringEnumBase const &a_rThat);
667	/** Copy assignment operator. */
668	RTCRestStringEnumBase &operator=(RTCRestStringEnumBase const &a_rThat);
669
670	/** Safe copy assignment method. */
671	int assignCopy(RTCRestStringEnumBase const &a_rThat);
672	/** Safe copy assignment method. */
673	int assignCopy(RTCString const &a_rThat) { return setByString(a_rThat); }
674	/** Safe copy assignment method. */
675	int assignCopy(const char *a_pszThat) { return setByString(a_pszThat); }
676
677	/* Overridden methods: */
678	virtual int resetToDefault() RT_OVERRIDE;
679	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
680	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
681	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
682	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
683	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
684	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
685
686	/**
687	* Sets the value given a C-string value.
688	*
689	* @retval VINF_SUCCESS on success.
690	* @retval VWRN_NOT_FOUND if not mappable to enum value.
691	* @retval VERR_NO_STR_MEMORY if not mappable and we're out of memory.
692	* @param a_pszValue The string value.
693	* @param a_cchValue The string value length. Optional.
694	*/
695	int setByString(const char *a_pszValue, size_t a_cchValue = RTSTR_MAX);
696
697	/**
698	* Sets the value given a string value.
699	*
700	* @retval VINF_SUCCESS on success.
701	* @retval VWRN_NOT_FOUND if not mappable to enum value.
702	* @retval VERR_NO_STR_MEMORY if not mappable and we're out of memory.
703	* @param a_rValue The string value.
704	*/
705	int setByString(RTCString const &a_rValue);
706
707	/**
708	* Gets the string value.
709	*/
710	const char *getString() const;
711
712	/** Maps the given string value to an enum. */
713	int stringToEnum(const char *a_pszValue, size_t a_cchValue = RTSTR_MAX);
714	/** Maps the given string value to an enum. */
715	int stringToEnum(RTCString const &a_rStrValue);
716	/** Maps the given string value to an enum. */
717	const char enumToString(int a_iEnumValue, size_t a_pcchString);
718
719
720	protected:
721	/** The enum value. */
722	int m_iEnumValue;
723	/** The string value if not a match. */
724	RTCString m_strValue;
725
726	/**
727	* Worker for setting the object to the given enum value.
728	*
729	* @retval true on success.
730	* @retval false if a_iEnumValue can't be translated.
731	* @param a_iEnumValue The enum value to set.
732	*/
733	bool setWorker(int a_iEnumValue);
734
735	/**
736	* Gets the mapping table.
737	*
738	* @returns Pointer to the translation table.
739	* @param pcEntries Where to return the translation table size.
740	*/
741	virtual ENUMMAPENTRY const getMappingTable(size_t pcEntries) const = 0;
742	};
743
744	/** @} */
745
746	#endif
747

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

source: vbox/trunk/include/iprt/cpp/restbase.h@ 74126

Download in other formats: