restbase.h@ 74111

Last change on this file since 74111 was 74096, checked in by vboxsync, 7 years ago
IPRT/rest: doxygen fix
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 30.1 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;
374
375	/**
376	* Returns the object type class.
377	*/
378	virtual kTypeClass typeClass(void) const;
379
380	/**
381	* Returns the object type name.
382	*/
383	virtual const char *typeName(void) const = 0;
384
385	/**
386	* Factory method.
387	* @returns Pointer to new object on success, NULL if out of memory.
388	*/
389	typedef DECLCALLBACK(RTCRestObjectBase *) FNCREATEINSTANCE(void);
390	/** Pointer to factory method. */
391	typedef FNCREATEINSTANCE *PFNCREATEINSTANCE;
392
393	protected:
394	/** Null indicator.
395	* @remarks The null values could be mapped onto C/C++ NULL pointer values,
396	* with the consequence that all data members in objects and such would
397	* have had to been allocated individually, even simple @a bool members.
398	* Given that we're overly paranoid about heap allocations (std::bad_alloc),
399	* it's more fitting to use a null indicator for us.
400	*/
401	bool m_fNullIndicator;
402	};
403
404
405	/**
406	* Class wrapping 'bool'.
407	*/
408	class RT_DECL_CLASS RTCRestBool : public RTCRestObjectBase
409	{
410	public:
411	/** Default constructor. */
412	RTCRestBool();
413	/** Copy constructor. */
414	RTCRestBool(RTCRestBool const &a_rThat);
415	/** From value constructor. */
416	RTCRestBool(bool fValue);
417	/** Destructor. */
418	virtual ~RTCRestBool();
419	/** Copy assignment operator. */
420	RTCRestBool &operator=(RTCRestBool const &a_rThat);
421	/** Safe copy assignment method. */
422	int assignCopy(RTCRestBool const &a_rThat);
423	/** Assign value and clear null indicator. */
424	void assignValue(bool a_fValue);
425
426	/* Overridden methods: */
427	virtual int resetToDefault() RT_OVERRIDE;
428	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
429	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
430	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
431	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
432	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
433	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
434	virtual const char *typeName(void) const RT_OVERRIDE;
435
436	/** Factory method. */
437	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
438
439	public:
440	/** The value. */
441	bool m_fValue;
442	};
443
444
445	/**
446	* Class wrapping 'int64_t'.
447	*/
448	class RT_DECL_CLASS RTCRestInt64 : public RTCRestObjectBase
449	{
450	public:
451	/** Default constructor. */
452	RTCRestInt64();
453	/** Copy constructor. */
454	RTCRestInt64(RTCRestInt64 const &a_rThat);
455	/** From value constructor. */
456	RTCRestInt64(int64_t a_iValue);
457	/** Destructor. */
458	virtual ~RTCRestInt64();
459	/** Copy assignment operator. */
460	RTCRestInt64 &operator=(RTCRestInt64 const &a_rThat);
461	/** Safe copy assignment method. */
462	int assignCopy(RTCRestInt64 const &a_rThat);
463	/** Assign value and clear null indicator. */
464	void assignValue(int64_t a_iValue);
465
466	/* Overridden methods: */
467	virtual int resetToDefault() RT_OVERRIDE;
468	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
469	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
470	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
471	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
472	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
473	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
474	virtual const char *typeName(void) const RT_OVERRIDE;
475
476	/** Factory method. */
477	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
478
479	public:
480	/** The value. */
481	int64_t m_iValue;
482	};
483
484
485	/**
486	* Class wrapping 'int32_t'.
487	*/
488	class RT_DECL_CLASS RTCRestInt32 : public RTCRestObjectBase
489	{
490	public:
491	/** Default constructor. */
492	RTCRestInt32();
493	/** Copy constructor. */
494	RTCRestInt32(RTCRestInt32 const &a_rThat);
495	/** From value constructor. */
496	RTCRestInt32(int32_t iValue);
497	/** Destructor. */
498	virtual ~RTCRestInt32();
499	/** Copy assignment operator. */
500	RTCRestInt32 &operator=(RTCRestInt32 const &a_rThat);
501	/** Safe copy assignment method. */
502	int assignCopy(RTCRestInt32 const &a_rThat);
503	/** Assign value and clear null indicator. */
504	void assignValue(int32_t a_iValue);
505
506	/* Overridden methods: */
507	virtual int resetToDefault() RT_OVERRIDE;
508	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
509	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
510	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
511	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
512	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
513	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
514	virtual const char *typeName(void) const RT_OVERRIDE;
515
516	/** Factory method. */
517	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
518
519	public:
520	/** The value. */
521	int32_t m_iValue;
522	};
523
524
525	/**
526	* Class wrapping 'int16_t'.
527	*/
528	class RT_DECL_CLASS RTCRestInt16 : public RTCRestObjectBase
529	{
530	public:
531	/** Default constructor. */
532	RTCRestInt16();
533	/** Copy constructor. */
534	RTCRestInt16(RTCRestInt16 const &a_rThat);
535	/** From value constructor. */
536	RTCRestInt16(int16_t iValue);
537	/** Destructor. */
538	virtual ~RTCRestInt16();
539	/** Copy assignment operator. */
540	RTCRestInt16 &operator=(RTCRestInt16 const &a_rThat);
541	/** Safe copy assignment method. */
542	int assignCopy(RTCRestInt16 const &a_rThat);
543	/** Assign value and clear null indicator. */
544	void assignValue(int16_t a_iValue);
545
546	/* Overridden methods: */
547	virtual int resetToDefault() RT_OVERRIDE;
548	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
549	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
550	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
551	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
552	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
553	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
554	virtual const char *typeName(void) const RT_OVERRIDE;
555
556	/** Factory method. */
557	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
558
559	public:
560	/** The value. */
561	int16_t m_iValue;
562	};
563
564
565	/**
566	* Class wrapping 'double'.
567	*/
568	class RT_DECL_CLASS RTCRestDouble : public RTCRestObjectBase
569	{
570	public:
571	/** Default constructor. */
572	RTCRestDouble();
573	/** Copy constructor. */
574	RTCRestDouble(RTCRestDouble const &a_rThat);
575	/** From value constructor. */
576	RTCRestDouble(double rdValue);
577	/** Destructor. */
578	virtual ~RTCRestDouble();
579	/** Copy assignment operator. */
580	RTCRestDouble &operator=(RTCRestDouble const &a_rThat);
581	/** Safe copy assignment method. */
582	int assignCopy(RTCRestDouble const &a_rThat);
583	/** Assign value and clear null indicator. */
584	void assignValue(double a_rdValue);
585
586	/* Overridden methods: */
587	virtual int resetToDefault() RT_OVERRIDE;
588	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
589	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
590	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
591	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
592	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
593	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
594	virtual const char *typeName(void) const RT_OVERRIDE;
595
596	/** Factory method. */
597	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
598
599	public:
600	/** The value. */
601	double m_rdValue;
602	};
603
604
605	/**
606	* Class wrapping 'RTCString'.
607	*/
608	class RT_DECL_CLASS RTCRestString : public RTCString, public RTCRestObjectBase
609	{
610	public:
611	/** Default constructor. */
612	RTCRestString();
613	/** Destructor. */
614	virtual ~RTCRestString();
615
616	/** Copy constructor. */
617	RTCRestString(RTCRestString const &a_rThat);
618	/** From value constructor. */
619	RTCRestString(RTCString const &a_rThat);
620	/** From value constructor. */
621	RTCRestString(const char *a_pszSrc);
622	/** Safe copy assignment method. */
623	int assignCopy(RTCRestString const &a_rThat);
624	/** Safe copy assignment method. */
625	int assignCopy(RTCString const &a_rThat);
626	/** Safe copy assignment method. */
627	int assignCopy(const char *a_pszThat);
628
629	/* Overridden methods: */
630	virtual int setNull(void) RT_OVERRIDE; /* (ambigious, so overrider it to make sure.) */
631	virtual int resetToDefault() RT_OVERRIDE;
632	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
633	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
634	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
635	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
636	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
637	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
638	virtual const char *typeName(void) const RT_OVERRIDE;
639
640	/** Factory method. */
641	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
642	};
643
644
645	/**
646	* String enum base class.
647	*/
648	class RT_DECL_CLASS RTCRestStringEnumBase : public RTCRestObjectBase
649	{
650	public:
651	/** Enum map entry. */
652	typedef struct ENUMMAPENTRY
653	{
654	const char *pszName;
655	uint32_t cchName;
656	int32_t iValue;
657	} ENUMMAPENTRY;
658
659	/** Default constructor. */
660	RTCRestStringEnumBase();
661	/** Destructor. */
662	virtual ~RTCRestStringEnumBase();
663
664	/** Copy constructor. */
665	RTCRestStringEnumBase(RTCRestStringEnumBase const &a_rThat);
666	/** Copy assignment operator. */
667	RTCRestStringEnumBase &operator=(RTCRestStringEnumBase const &a_rThat);
668
669	/** Safe copy assignment method. */
670	int assignCopy(RTCRestStringEnumBase const &a_rThat);
671	/** Safe copy assignment method. */
672	int assignCopy(RTCString const &a_rThat) { return setByString(a_rThat); }
673	/** Safe copy assignment method. */
674	int assignCopy(const char *a_pszThat) { return setByString(a_pszThat); }
675
676	/* Overridden methods: */
677	virtual int resetToDefault() RT_OVERRIDE;
678	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
679	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
680	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
681	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
682	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
683	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
684
685	/**
686	* Sets the value given a C-string value.
687	*
688	* @retval VINF_SUCCESS on success.
689	* @retval VWRN_NOT_FOUND if not mappable to enum value.
690	* @retval VERR_NO_STR_MEMORY if not mappable and we're out of memory.
691	* @param a_pszValue The string value.
692	* @param a_cchValue The string value length. Optional.
693	*/
694	int setByString(const char *a_pszValue, size_t a_cchValue = RTSTR_MAX);
695
696	/**
697	* Sets the value given a string value.
698	*
699	* @retval VINF_SUCCESS on success.
700	* @retval VWRN_NOT_FOUND if not mappable to enum value.
701	* @retval VERR_NO_STR_MEMORY if not mappable and we're out of memory.
702	* @param a_rValue The string value.
703	*/
704	int setByString(RTCString const &a_rValue);
705
706	/**
707	* Gets the string value.
708	*/
709	const char *getString() const;
710
711	/** Maps the given string value to an enum. */
712	int stringToEnum(const char *a_pszValue, size_t a_cchValue = RTSTR_MAX);
713	/** Maps the given string value to an enum. */
714	int stringToEnum(RTCString const &a_rStrValue);
715	/** Maps the given string value to an enum. */
716	const char enumToString(int a_iEnumValue, size_t a_pcchString);
717
718
719	protected:
720	/** The enum value. */
721	int m_iEnumValue;
722	/** The string value if not a match. */
723	RTCString m_strValue;
724
725	/**
726	* Worker for setting the object to the given enum value.
727	*
728	* @retval true on success.
729	* @retval false if a_iEnumValue can't be translated.
730	* @param a_iEnumValue The enum value to set.
731	*/
732	bool setWorker(int a_iEnumValue);
733
734	/**
735	* Gets the mapping table.
736	*
737	* @returns Pointer to the translation table.
738	* @param pcEntries Where to return the translation table size.
739	*/
740	virtual ENUMMAPENTRY const getMappingTable(size_t pcEntries) const = 0;
741	};
742
743
744	/**
745	* Class for handling strings on the binary format.
746	*
747	* This can only be used for body parameters.
748	*/
749	class RT_DECL_CLASS RTCRestBinaryString : public RTCRestObjectBase
750	{
751	public:
752	/** Default constructor. */
753	RTCRestBinaryString();
754	/** Destructor. */
755	virtual ~RTCRestBinaryString();
756
757	/** Safe copy assignment method. */
758	int assignCopy(RTCRestBinaryString const &a_rThat);
759
760	/* Overridden methods: */
761	virtual int resetToDefault() RT_OVERRIDE;
762	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
763	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
764	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
765	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
766	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
767	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
768	virtual const char *typeName(void) const RT_OVERRIDE;
769
770	/** Factory method. */
771	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
772
773	/**
774	* Gets the data size.
775	*
776	* This can be used from a consumer callback to get the Content-Length field
777	* value if available. Returns UINT64_MAX if not available.
778	*/
779	uint64_t getDataSize() const { return m_cbData; }
780
781	/**
782	* Sets the data to upload.
783	*
784	* @returns IPRT status code.
785	* @param a_pvData The data buffer. NULL can be used to actively
786	* deregister previous data.
787	* @param a_cbData The amount of data to upload from that buffer.
788	* @param a_fCopy Whether to make a copy (@a true) or use the
789	* buffer directly (@a false). In the latter case
790	* the caller must make sure the data remains available
791	* for the entire lifetime of this object (or until
792	* setUploadData is called with NULL parameters).
793	*/
794	int setUploadData(void const *a_pvData, size_t a_cbData, bool a_fCopy);
795
796	/** @name Data callbacks.
797	* @{ */
798	/**
799	* Callback for producing bytes to upload.
800	*
801	* @returns IPRT status code.
802	* @param a_pThis The related string object.
803	* @param a_pvDst Where to put the bytes.
804	* @param a_cbDst Max number of bytes to produce.
805	* @param a_pcbActual Where to return the number of bytes actually produced.
806	* @remarks Use getCallbackData to get the user data.
807	*/
808	typedef DECLCALLBACK(int) FNPRODUCER(RTCRestBinaryString a_pThis, void a_pvDst, size_t a_cbDst, size_t *a_pcbActual);
809	/** Pointer to a byte producer callback. */
810	typedef FNPRODUCER *PFNPRODUCER;
811
812	/**
813	* Callback for consuming downloaded bytes.
814	*
815	* @returns IPRT status code.
816	* @param a_pThis The related string object.
817	* @param a_pvSrc Buffer containing the bytes.
818	* @param a_cbSrc The number of bytes in the buffer.
819	* @remarks Use getCallbackData to get the user data.
820	*/
821	typedef DECLCALLBACK(int) FNCONSUMER(RTCRestBinaryString a_pThis, const void a_pvSrc, size_t a_cbSrc);
822	/** Pointer to a byte consumer callback. */
823	typedef FNCONSUMER *PFNCONSUMER;
824
825	/**
826	* Retrieves the callback data.
827	*/
828	void *getCallbackData() const { return m_pvCallbackData; }
829
830	/**
831	* Sets the consumer callback.
832	*
833	* @returns IPRT status code.
834	* @param a_pfnConsumer The callback function for consuming downloaded data.
835	* NULL if data should be stored in m_pbData/m_cbData (the default).
836	* @param a_pvCallbackData Data the can be retrieved from the callback
837	* using getCallbackData().
838	*/
839	int setConsumerCallback(PFNCONSUMER a_pfnConsumer, void *a_pvCallbackData = NULL);
840
841	/**
842	* Sets the producer callback.
843	*
844	* @returns IPRT status code.
845	* @param a_pfnProducer The callback function for producing data.
846	* @param a_pvCallbackData Data the can be retrieved from the callback
847	* using getCallbackData().
848	* @param a_cbData The amount of data that will be uploaded,
849	* UINT64_MAX if not unknown.
850	*
851	* @note This will drop any buffer previously registered using
852	* setUploadData(), unless a_pfnProducer is NULL.
853	*/
854	int setProducerCallback(PFNPRODUCER a_pfnProducer, void *a_pvCallbackData = NULL, uint64_t a_cbData = UINT64_MAX);
855	/** @} */
856
857	protected:
858	/** Pointer to the bytes, if provided directly. */
859	uint8_t *m_pbData;
860	/** Number of bytes. UINT64_MAX if not known. */
861	uint64_t m_cbData;
862	/** User argument for callbacks. */
863	void *m_pvCallbackData;
864	/** Pointer to user-registered consumer callback function. */
865	PFNCONSUMER m_pfnConsumer;
866	/** Pointer to user-registered producer callback function. */
867	PFNPRODUCER m_pfnProducer;
868	/** Set if m_pbData must be freed. */
869	bool m_fFreeData;
870	/** Set if it is an upload, clear if download. */
871	bool m_fIsUpload;
872
873	private:
874	/* No copy constructor or copy assignment: */
875	RTCRestBinaryString(RTCRestBinaryString const &a_rThat);
876	RTCRestDouble &operator=(RTCRestDouble const &a_rThat);
877	};
878
879	/** @} */
880
881	#endif
882

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

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

Download in other formats: