restbase.h@ 74334

Last change on this file since 74334 was 74263, checked in by vboxsync, 6 years ago
IPRT/rest: Reimplement RTCRestArrayBase::fromString and adjusted response header handling of arrays to deal with multiple headers for the same field (just in case). bugref:9167
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 35.3 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/time.h>
34	#include <iprt/cpp/ministring.h>
35
36
37	/** @defgroup grp_rt_cpp_restbase C++ Representational State Transfer (REST) Base Classes.
38	* @ingroup grp_rt_cpp
39	* @{
40	*/
41
42
43
44	/**
45	* Abstract base class for serializing data objects.
46	*/
47	class RT_DECL_CLASS RTCRestOutputBase
48	{
49	public:
50	RTCRestOutputBase()
51	: m_uIndent(0)
52	{ }
53	virtual ~RTCRestOutputBase()
54	{ }
55
56	/**
57	* RTStrPrintf like function (see @ref pg_rt_str_format).
58	*
59	* @returns Number of bytes outputted.
60	* @param pszFormat The format string.
61	* @param ... Argument specfied in @a pszFormat.
62	*/
63	size_t printf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3)
64	{
65	va_list va;
66	va_start(va, pszFormat);
67	size_t cchWritten = this->vprintf(pszFormat, va);
68	va_end(va);
69	return cchWritten;
70	}
71
72	/**
73	* RTStrPrintfV like function (see @ref pg_rt_str_format).
74	*
75	* @returns Number of bytes outputted.
76	* @param pszFormat The format string.
77	* @param va Argument specfied in @a pszFormat.
78	*/
79	virtual size_t vprintf(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0) = 0;
80
81	/**
82	* Sets the indentation level for use when pretty priting things.
83	*
84	* @returns Previous indentation level.
85	* @param uIndent The indentation level.
86	*/
87	inline unsigned setIndent(unsigned uIndent)
88	{
89	unsigned const uRet = m_uIndent;
90	m_uIndent = uIndent;
91	return uRet;
92	}
93
94	/**
95	* Increases the indentation level.
96	*
97	* @returns Previous indentation level.
98	*/
99	inline unsigned incrementIndent()
100	{
101	unsigned const uRet = m_uIndent;
102	m_uIndent = uRet + 1;
103	return uRet;
104	}
105
106	protected:
107	/** The current indentation level. */
108	unsigned m_uIndent;
109	};
110
111
112	/**
113	* Serialize to a string object.
114	*/
115	class RT_DECL_CLASS RTCRestOutputToString : public RTCRestOutputBase
116	{
117	public:
118	/**
119	* Creates an instance that appends to @a a_pDst.
120	* @param a_pDst Pointer to the destination string object.
121	* NULL is not accepted and will assert.
122	* @param a_fAppend Whether to append to the current string value, or
123	* nuke the string content before starting the output.
124	*/
125	RTCRestOutputToString(RTCString *a_pDst, bool a_fAppend = false);
126	virtual ~RTCRestOutputToString();
127
128	virtual size_t vprintf(const char *pszFormat, va_list va) RT_OVERRIDE;
129
130	/**
131	* Finalizes the output and releases the string object to the caller.
132	*
133	* @returns The released string object. NULL if we ran out of memory or if
134	* called already.
135	*
136	* @remark This sets m_pDst to NULL and the object cannot be use for any
137	* more output afterwards.
138	*/
139	virtual RTCString *finalize();
140
141
142	protected:
143	/** Pointer to the destination string. NULL after finalize(). */
144	RTCString *m_pDst;
145	/** Set if we ran out of memory and should ignore subsequent calls. */
146	bool m_fOutOfMemory;
147
148	/** @callback_method_impl{FNRTSTROUTPUT} */
149	static DECLCALLBACK(size_t) strOutput(void pvArg, const char pachChars, size_t cbChars);
150
151	/* Make non-copyable (RTCNonCopyable causes warnings): */
152	RTCRestOutputToString(RTCRestOutputToString const &);
153	RTCRestOutputToString *operator=(RTCRestOutputToString const &);
154	};
155
156
157	/* forward decl: */
158	class RTCRestJsonPrimaryCursor;
159
160	/**
161	* JSON cursor structure.
162	*
163	* This reduces the number of parameters passed around when deserializing JSON
164	* input and also helps constructing full object name for logging and error reporting.
165	*/
166	struct RT_DECL_CLASS RTCRestJsonCursor
167	{
168	/** Handle to the value being parsed. */
169	RTJSONVAL m_hValue;
170	/** Name of the value. */
171	const char *m_pszName;
172	/** Pointer to the parent, NULL if primary. */
173	struct RTCRestJsonCursor const *m_pParent;
174	/** Pointer to the primary cursor structure. */
175	RTCRestJsonPrimaryCursor *m_pPrimary;
176
177	RTCRestJsonCursor(struct RTCRestJsonCursor const &a_rParent)
178	: m_hValue(NIL_RTJSONVAL), m_pszName(NULL), m_pParent(&a_rParent), m_pPrimary(a_rParent.m_pPrimary)
179	{ }
180
181	RTCRestJsonCursor(RTJSONVAL hValue, const char pszName, struct RTCRestJsonCursor pParent)
182	: m_hValue(hValue), m_pszName(pszName), m_pParent(pParent), m_pPrimary(pParent->m_pPrimary)
183	{ }
184
185	RTCRestJsonCursor(RTJSONVAL hValue, const char *pszName)
186	: m_hValue(hValue), m_pszName(pszName), m_pParent(NULL), m_pPrimary(NULL)
187	{ }
188
189	~RTCRestJsonCursor()
190	{
191	if (m_hValue != NIL_RTJSONVAL)
192	{
193	RTJsonValueRelease(m_hValue);
194	m_hValue = NIL_RTJSONVAL;
195	}
196	}
197	};
198
199
200	/**
201	* The primary JSON cursor class.
202	*/
203	class RT_DECL_CLASS RTCRestJsonPrimaryCursor
204	{
205	public:
206	/** The cursor for the first level. */
207	RTCRestJsonCursor m_Cursor;
208	/** Error info keeper. */
209	PRTERRINFO m_pErrInfo;
210
211	/** Creates a primary json cursor with optiona error info. */
212	RTCRestJsonPrimaryCursor(RTJSONVAL hValue, const char *pszName, PRTERRINFO pErrInfo = NULL)
213	: m_Cursor(hValue, pszName)
214	, m_pErrInfo(pErrInfo)
215	{
216	m_Cursor.m_pPrimary = this;
217	}
218
219	virtual ~RTCRestJsonPrimaryCursor()
220	{ }
221
222	/**
223	* Add an error message.
224	*
225	* @returns a_rc
226	* @param a_rCursor The cursor reporting the error.
227	* @param a_rc The status code.
228	* @param a_pszFormat Format string.
229	* @param ... Format string arguments.
230	*/
231	virtual int addError(RTCRestJsonCursor const &a_rCursor, int a_rc, const char *a_pszFormat, ...);
232
233	/**
234	* Reports that the current field is not known.
235	*
236	* @returns Status to propagate.
237	* @param a_rCursor The cursor for the field.
238	*/
239	virtual int unknownField(RTCRestJsonCursor const &a_rCursor);
240
241	/**
242	* Copies the full path into pszDst.
243	*
244	* @returns pszDst
245	* @param a_rCursor The cursor to start walking at.
246	* @param a_pszDst Where to put the path.
247	* @param a_cbDst Size of the destination buffer.
248	*/
249	virtual char getPath(RTCRestJsonCursor const &a_rCursor, char a_pszDst, size_t a_cbDst) const;
250	};
251
252
253	/**
254	* Abstract base class for REST data objects.
255	*
256	* The only information this keeps is the null indicator.
257	*/
258	class RT_DECL_CLASS RTCRestObjectBase
259	{
260	public:
261	RTCRestObjectBase();
262	RTCRestObjectBase(RTCRestObjectBase const &a_rThat);
263	virtual ~RTCRestObjectBase();
264
265	/**
266	* Tests if the object is @a null.
267	* @returns true if null, false if not.
268	*/
269	inline bool isNull(void) const { return m_fNullIndicator; };
270
271	/**
272	* Sets the object to @a null and fills it with defaults.
273	* @returns IPRT status code (from resetToDefault).
274	*/
275	virtual int setNull(void);
276
277	/**
278	* Sets the object to not-null state (i.e. undoes setNull()).
279	* @remarks Only really important for strings.
280	*/
281	virtual void setNotNull(void);
282
283	/**
284	* Resets the object to all default values.
285	* @returns IPRT status code.
286	*/
287	virtual int resetToDefault() = 0;
288
289	/**
290	* Serialize the object as JSON.
291	*
292	* @returns a_rDst
293	* @param a_rDst The destination for the serialization.
294	*/
295	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const = 0;
296
297	/**
298	* Deserialize object from the given JSON iterator.
299	*
300	* @returns IPRT status code.
301	* @param a_rCursor The JSON cursor.
302	*/
303	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) = 0;
304
305	/**
306	* Flags for toString().
307	*
308	* The kCollectionFormat_xxx bunch controls multiple values in arrays
309	* are formatted. They are ignored by everyone else.
310	*
311	* @note When adding collection format types, make sure to also
312	* update RTCRestArrayBase::toString().
313	* @note Bit 24 is reserved (for kHdrField_MapCollection).
314	*/
315	enum
316	{
317	kCollectionFormat_Unspecified = 0, /*< Not specified. /
318	kCollectionFormat_csv, /*< Comma-separated list. /
319	kCollectionFormat_ssv, /*< Space-separated list. /
320	kCollectionFormat_tsv, /*< Tab-separated list. /
321	kCollectionFormat_pipes, /*< Pipe-separated list. /
322	kCollectionFormat_multi, /*< Special collection type that must be handled by caller of toString. /
323	kCollectionFormat_Mask = 7, /*< Collection type mask. /
324
325	kToString_Append = 8 /*< Append to the string/object (rather than assigning). /
326	};
327
328	/**
329	* String conversion.
330	*
331	* The default implementation of is a wrapper around serializeAsJson().
332	*
333	* @returns IPRT status code.
334	* @param a_pDst Pointer to the destionation string.
335	* @param a_fFlags kCollectionFormat_xxx.
336	*/
337	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const;
338
339	/**
340	* String convertsion, naive variant.
341	*
342	* @returns String represenation.
343	*/
344	RTCString toString() const;
345
346	/**
347	* Convert from (header) string value.
348	*
349	* The default implementation of is a wrapper around deserializeFromJson().
350	*
351	* @returns IPRT status code.
352	* @param a_rValue The string value string to parse.
353	* @param a_pszName Field name or similar.
354	* @param a_pErrInfo Where to return additional error info. Optional.
355	* @param a_fFlags kCollectionFormat_xxx.
356	*/
357	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
358	uint32_t a_fFlags = kCollectionFormat_Unspecified);
359
360	/** Type classification */
361	typedef enum kTypeClass
362	{
363	kTypeClass_Invalid = 0,
364	kTypeClass_Bool, /*< Primitive: bool. /
365	kTypeClass_Int64, /*< Primitive: int64_t. /
366	kTypeClass_Int32, /*< Primitive: int32_t. /
367	kTypeClass_Int16, /*< Primitive: int16_t. /
368	kTypeClass_Double, /*< Primitive: double. /
369	kTypeClass_String, /*< Primitive: string. /
370	kTypeClass_Date, /*< Date. /
371	kTypeClass_Uuid, /*< UUID. /
372	kTypeClass_Binary, /*< Binary blob. /
373	kTypeClass_Object, /*< Object (any kind of data model object). /
374	kTypeClass_Array, /*< Array (containing any kind of object). /
375	kTypeClass_StringMap, /*< String map (containing any kind of object). /
376	kTypeClass_StringEnum /*< String enum. /
377	} kTypeClass;
378
379	/**
380	* Returns the object type class.
381	*/
382	virtual kTypeClass typeClass(void) const;
383
384	/**
385	* Returns the object type name.
386	*/
387	virtual const char *typeName(void) const = 0;
388
389	protected:
390	/** Null indicator.
391	* @remarks The null values could be mapped onto C/C++ NULL pointer values,
392	* with the consequence that all data members in objects and such would
393	* have had to been allocated individually, even simple @a bool members.
394	* Given that we're overly paranoid about heap allocations (std::bad_alloc),
395	* it's more fitting to use a null indicator for us.
396	*/
397	bool m_fNullIndicator;
398	};
399
400
401	/**
402	* Class wrapping 'bool'.
403	*/
404	class RT_DECL_CLASS RTCRestBool : public RTCRestObjectBase
405	{
406	public:
407	/** Default constructor. */
408	RTCRestBool();
409	/** Copy constructor. */
410	RTCRestBool(RTCRestBool const &a_rThat);
411	/** From value constructor. */
412	RTCRestBool(bool fValue);
413	/** Destructor. */
414	virtual ~RTCRestBool();
415	/** Copy assignment operator. */
416	RTCRestBool &operator=(RTCRestBool const &a_rThat);
417	/** Safe copy assignment method. */
418	int assignCopy(RTCRestBool const &a_rThat);
419	/** Assign value and clear null indicator. */
420	void assignValue(bool a_fValue);
421
422	/* Overridden methods: */
423	virtual int resetToDefault() RT_OVERRIDE;
424	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
425	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
426	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
427	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
428	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
429	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
430	virtual const char *typeName(void) const RT_OVERRIDE;
431
432	/** Factory method. */
433	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
434
435	public:
436	/** The value. */
437	bool m_fValue;
438	};
439
440
441	/**
442	* Class wrapping 'int64_t'.
443	*/
444	class RT_DECL_CLASS RTCRestInt64 : public RTCRestObjectBase
445	{
446	public:
447	/** Default constructor. */
448	RTCRestInt64();
449	/** Copy constructor. */
450	RTCRestInt64(RTCRestInt64 const &a_rThat);
451	/** From value constructor. */
452	RTCRestInt64(int64_t a_iValue);
453	/** Destructor. */
454	virtual ~RTCRestInt64();
455	/** Copy assignment operator. */
456	RTCRestInt64 &operator=(RTCRestInt64 const &a_rThat);
457	/** Safe copy assignment method. */
458	int assignCopy(RTCRestInt64 const &a_rThat);
459	/** Assign value and clear null indicator. */
460	void assignValue(int64_t a_iValue);
461
462	/* Overridden methods: */
463	virtual int resetToDefault() RT_OVERRIDE;
464	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
465	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
466	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
467	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
468	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
469	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
470	virtual const char *typeName(void) const RT_OVERRIDE;
471
472	/** Factory method. */
473	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
474
475	public:
476	/** The value. */
477	int64_t m_iValue;
478	};
479
480
481	/**
482	* Class wrapping 'int32_t'.
483	*/
484	class RT_DECL_CLASS RTCRestInt32 : public RTCRestObjectBase
485	{
486	public:
487	/** Default constructor. */
488	RTCRestInt32();
489	/** Copy constructor. */
490	RTCRestInt32(RTCRestInt32 const &a_rThat);
491	/** From value constructor. */
492	RTCRestInt32(int32_t iValue);
493	/** Destructor. */
494	virtual ~RTCRestInt32();
495	/** Copy assignment operator. */
496	RTCRestInt32 &operator=(RTCRestInt32 const &a_rThat);
497	/** Safe copy assignment method. */
498	int assignCopy(RTCRestInt32 const &a_rThat);
499	/** Assign value and clear null indicator. */
500	void assignValue(int32_t a_iValue);
501
502	/* Overridden methods: */
503	virtual int resetToDefault() RT_OVERRIDE;
504	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
505	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
506	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
507	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
508	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
509	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
510	virtual const char *typeName(void) const RT_OVERRIDE;
511
512	/** Factory method. */
513	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
514
515	public:
516	/** The value. */
517	int32_t m_iValue;
518	};
519
520
521	/**
522	* Class wrapping 'int16_t'.
523	*/
524	class RT_DECL_CLASS RTCRestInt16 : public RTCRestObjectBase
525	{
526	public:
527	/** Default constructor. */
528	RTCRestInt16();
529	/** Copy constructor. */
530	RTCRestInt16(RTCRestInt16 const &a_rThat);
531	/** From value constructor. */
532	RTCRestInt16(int16_t iValue);
533	/** Destructor. */
534	virtual ~RTCRestInt16();
535	/** Copy assignment operator. */
536	RTCRestInt16 &operator=(RTCRestInt16 const &a_rThat);
537	/** Safe copy assignment method. */
538	int assignCopy(RTCRestInt16 const &a_rThat);
539	/** Assign value and clear null indicator. */
540	void assignValue(int16_t a_iValue);
541
542	/* Overridden methods: */
543	virtual int resetToDefault() RT_OVERRIDE;
544	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
545	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
546	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
547	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
548	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
549	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
550	virtual const char *typeName(void) const RT_OVERRIDE;
551
552	/** Factory method. */
553	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
554
555	public:
556	/** The value. */
557	int16_t m_iValue;
558	};
559
560
561	/**
562	* Class wrapping 'double'.
563	*/
564	class RT_DECL_CLASS RTCRestDouble : public RTCRestObjectBase
565	{
566	public:
567	/** Default constructor. */
568	RTCRestDouble();
569	/** Copy constructor. */
570	RTCRestDouble(RTCRestDouble const &a_rThat);
571	/** From value constructor. */
572	RTCRestDouble(double rdValue);
573	/** Destructor. */
574	virtual ~RTCRestDouble();
575	/** Copy assignment operator. */
576	RTCRestDouble &operator=(RTCRestDouble const &a_rThat);
577	/** Safe copy assignment method. */
578	int assignCopy(RTCRestDouble const &a_rThat);
579	/** Assign value and clear null indicator. */
580	void assignValue(double a_rdValue);
581
582	/* Overridden methods: */
583	virtual int resetToDefault() RT_OVERRIDE;
584	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
585	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
586	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
587	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
588	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
589	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
590	virtual const char *typeName(void) const RT_OVERRIDE;
591
592	/** Factory method. */
593	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
594
595	public:
596	/** The value. */
597	double m_rdValue;
598	};
599
600
601	/**
602	* Class wrapping 'RTCString'.
603	*/
604	class RT_DECL_CLASS RTCRestString : public RTCString, public RTCRestObjectBase
605	{
606	public:
607	/** Default constructor. */
608	RTCRestString();
609	/** Destructor. */
610	virtual ~RTCRestString();
611
612	/** Copy constructor. */
613	RTCRestString(RTCRestString const &a_rThat);
614	/** From value constructor. */
615	RTCRestString(RTCString const &a_rThat);
616	/** From value constructor. */
617	RTCRestString(const char *a_pszSrc);
618	/** Safe copy assignment method. */
619	int assignCopy(RTCRestString const &a_rThat);
620	/** Safe copy assignment method. */
621	int assignCopy(RTCString const &a_rThat);
622	/** Safe copy assignment method. */
623	int assignCopy(const char *a_pszThat);
624
625	/* Overridden methods: */
626	virtual int setNull(void) RT_OVERRIDE; /* (ambigious, so overrider it to make sure.) */
627	virtual int resetToDefault() RT_OVERRIDE;
628	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
629	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
630	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
631	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
632	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
633	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
634	virtual const char *typeName(void) const RT_OVERRIDE;
635
636	/** Factory method. */
637	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
638
639	/** @name RTCString assignment methods we need to replace to manage the null indicator
640	* @{ */
641	int assignNoThrow(const RTCString &a_rSrc) RT_NOEXCEPT;
642	int assignNoThrow(const char *a_pszSrc) RT_NOEXCEPT;
643	int assignNoThrow(const RTCString &a_rSrc, size_t a_offSrc, size_t a_cchSrc = npos) RT_NOEXCEPT;
644	int assignNoThrow(const char *a_pszSrc, size_t a_cchSrc) RT_NOEXCEPT;
645	int assignNoThrow(size_t a_cTimes, char a_ch) RT_NOEXCEPT;
646	int printfNoThrow(const char *pszFormat, ...) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 2);
647	int printfVNoThrow(const char *pszFormat, va_list va) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 0);
648	RTCRestString &operator=(const char *a_pcsz);
649	RTCRestString &operator=(const RTCString &a_rThat);
650	RTCRestString &operator=(const RTCRestString &a_rThat);
651	RTCRestString &assign(const RTCString &a_rSrc);
652	RTCRestString &assign(const char *a_pszSrc);
653	RTCRestString &assign(const RTCString &a_rSrc, size_t a_offSrc, size_t a_cchSrc = npos);
654	RTCRestString &assign(const char *a_pszSrc, size_t a_cchSrc);
655	RTCRestString &assign(size_t a_cTimes, char a_ch);
656	RTCRestString &printf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
657	RTCRestString &printfV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
658	/** @} */
659	};
660
661
662	/**
663	* Date class.
664	*
665	* There are numerous ways of formatting a timestamp and the specifications
666	* we're currently working with doesn't have a way of telling it seems.
667	* Thus, decoding need to have fail safes built in so the user can give hints.
668	* The formatting likewise needs to be told which format to use by the user.
669	*
670	* Two side-effects of the format stuff is that the default constructor creates
671	* an object that is null, and resetToDefault will do the same bug leave the
672	* format as a hint.
673	*/
674	class RT_DECL_CLASS RTCRestDate : public RTCRestObjectBase
675	{
676	public:
677	/** Default constructor.
678	* @note The result is a null-object. */
679	RTCRestDate();
680	/** Copy constructor. */
681	RTCRestDate(RTCRestDate const &a_rThat);
682	/** Destructor. */
683	virtual ~RTCRestDate();
684	/** Copy assignment operator. */
685	RTCRestDate &operator=(RTCRestDate const &a_rThat);
686	/** Safe copy assignment method. */
687	int assignCopy(RTCRestDate const &a_rThat);
688
689	/* Overridden methods: */
690	virtual int resetToDefault() RT_OVERRIDE;
691	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
692	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
693	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = 0) const RT_OVERRIDE;
694	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
695	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
696	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
697	virtual const char *typeName(void) const RT_OVERRIDE;
698
699	/** Factory method. */
700	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
701
702	/** Date formats. */
703	typedef enum
704	{
705	kFormat_Invalid = 0,
706	kFormat_Rfc2822, /*< Format it according to RFC-2822. /
707	kFormat_Rfc7131, /*< Format it according to RFC-7131 (HTTP). /
708	kFormat_Rfc3339, /*< Format it according to RFC-3339 (ISO-8601) (no fraction). /
709	kFormat_Rfc3339_Fraction_2, /*< Format it according to RFC-3339 (ISO-8601) with two digit fraction (hundreths). /
710	kFormat_Rfc3339_Fraction_3, /*< Format it according to RFC-3339 (ISO-8601) with three digit fraction (milliseconds). /
711	kFormat_Rfc3339_Fraction_6, /*< Format it according to RFC-3339 (ISO-8601) with six digit fraction (microseconds). /
712	kFormat_Rfc3339_Fraction_9, /*< Format it according to RFC-3339 (ISO-8601) with nine digit fraction (nanoseconds). /
713	kFormat_End
714	} kFormat;
715
716	/**
717	* Assigns the value, formats it as a string and clears the null indicator.
718	*
719	* @returns VINF_SUCCESS, VERR_NO_STR_MEMORY or VERR_INVALID_PARAMETER.
720	* @param a_pTimeSpec The time spec to set.
721	* @param a_enmFormat The date format to use when formatting it.
722	*/
723	int assignValue(PCRTTIMESPEC a_pTimeSpec, kFormat a_enmFormat);
724	int assignValueRfc2822(PCRTTIMESPEC a_pTimeSpec); /*< Convenience method for email/whatnot. /
725	int assignValueRfc7131(PCRTTIMESPEC a_pTimeSpec); /*< Convenience method for HTTP date. /
726	int assignValueRfc3339(PCRTTIMESPEC a_pTimeSpec); /*< Convenience method for ISO-8601 timstamp. /
727
728	/**
729	* Assigns the current UTC time and clears the null indicator .
730	*
731	* @returns VINF_SUCCESS, VERR_NO_STR_MEMORY or VERR_INVALID_PARAMETER.
732	* @returns VINF_SUCCESS or VERR_NO_STR_MEMORY.
733	* @param a_enmFormat The date format to use when formatting it.
734	*/
735	int assignNow(kFormat a_enmFormat);
736	int assignNowRfc2822(); /*< Convenience method for email/whatnot. /
737	int assignNowRfc7131(); /*< Convenience method for HTTP date. /
738	int assignNowRfc3339(); /*< Convenience method for ISO-8601 timstamp. /
739
740	/**
741	* Sets the format to help deal with decoding issues.
742	*
743	* This can also be used to change the date format for an okay timespec.
744	* @returns IPRT status code.
745	* @param a_enmFormat The date format to try/set.
746	*/
747	int setFormat(kFormat a_enmFormat);
748
749	/** Check if the value is okay (m_TimeSpec & m_Exploded). */
750	inline bool isOkay() const { return m_fTimeSpecOkay; }
751	/** Get the timespec value. */
752	inline RTTIMESPEC const &getTimeSpec() const { return m_TimeSpec; }
753	/** Get the exploded time. */
754	inline RTTIME const &getExploded() const { return m_Exploded; }
755	/** Gets the format. */
756	inline kFormat getFormat() const { return m_enmFormat; }
757	/** Get the formatted/raw string value. */
758	inline RTCString const &getString() const { return m_strFormatted; }
759
760	/** Get nanoseconds since unix epoch. */
761	inline int64_t getEpochNano() const { return RTTimeSpecGetNano(&m_TimeSpec); }
762	/** Get seconds since unix epoch. */
763	inline int64_t getEpochSeconds() const { return RTTimeSpecGetSeconds(&m_TimeSpec); }
764	/** Checks if UTC time. */
765	inline bool isUtc() const { return (m_Exploded.fFlags & RTTIME_FLAGS_TYPE_MASK) != RTTIME_FLAGS_TYPE_LOCAL; }
766	/** Checks if local time. */
767	inline bool isLocal() const { return (m_Exploded.fFlags & RTTIME_FLAGS_TYPE_MASK) == RTTIME_FLAGS_TYPE_LOCAL; }
768
769	protected:
770	/** The value. */
771	RTTIMESPEC m_TimeSpec;
772	/** The exploded time value. */
773	RTTIME m_Exploded;
774	/** Set if m_TimeSpec is okay, consult m_strFormatted if not. */
775	bool m_fTimeSpecOkay;
776	/** The format / format hint. */
777	kFormat m_enmFormat;
778	/** The formatted date string.
779	* This will be the raw input string for a deserialized value, where as for
780	* a value set by the user it will be the formatted value. */
781	RTCString m_strFormatted;
782
783	/**
784	* Explodes and formats the m_TimeSpec value.
785	*
786	* Sets m_Exploded, m_strFormatted, m_fTimeSpecOkay, and m_enmFormat, clears m_fNullIndicator.
787	*
788	* @returns VINF_SUCCESS or VERR_NO_STR_MEMORY.
789	* @param a_enmFormat The format to use.
790	*/
791	int explodeAndFormat(kFormat a_enmFormat);
792
793	/**
794	* Formats the m_Exploded value.
795	*
796	* Sets m_strFormatted, m_fTimeSpecOkay, and m_enmFormat, clears m_fNullIndicator.
797	*
798	* @returns VINF_SUCCESS or VERR_NO_STR_MEMORY.
799	* @param a_enmFormat The format to use.
800	*/
801	int format(kFormat a_enmFormat);
802
803	/**
804	* Internal worker that attempts to decode m_strFormatted.
805	*
806	* Sets m_fTimeSpecOkay.
807	*
808	* @returns IPRT status code.
809	* @param enmFormat Specific format to try, kFormat_Invalid (default) to try guess it.
810	*/
811	int decodeFormattedString(kFormat enmFormat = kFormat_Invalid);
812	};
813
814
815	/** We should provide a proper UUID class eventually. Currently it is not used. */
816	typedef RTCRestString RTCRestUuid;
817
818
819	/**
820	* String enum base class.
821	*/
822	class RT_DECL_CLASS RTCRestStringEnumBase : public RTCRestObjectBase
823	{
824	public:
825	/** Enum map entry. */
826	typedef struct ENUMMAPENTRY
827	{
828	const char *pszName;
829	uint32_t cchName;
830	int32_t iValue;
831	} ENUMMAPENTRY;
832
833	/** Default constructor. */
834	RTCRestStringEnumBase();
835	/** Destructor. */
836	virtual ~RTCRestStringEnumBase();
837
838	/** Copy constructor. */
839	RTCRestStringEnumBase(RTCRestStringEnumBase const &a_rThat);
840	/** Copy assignment operator. */
841	RTCRestStringEnumBase &operator=(RTCRestStringEnumBase const &a_rThat);
842
843	/** Safe copy assignment method. */
844	int assignCopy(RTCRestStringEnumBase const &a_rThat);
845	/** Safe copy assignment method. */
846	inline int assignCopy(RTCString const &a_rThat) { return setByString(a_rThat); }
847	/** Safe copy assignment method. */
848	inline int assignCopy(const char *a_pszThat) { return setByString(a_pszThat); }
849
850	/* Overridden methods: */
851	virtual int resetToDefault() RT_OVERRIDE;
852	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
853	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
854	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
855	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
856	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
857	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
858
859	/**
860	* Sets the value given a C-string value.
861	*
862	* @retval VINF_SUCCESS on success.
863	* @retval VWRN_NOT_FOUND if not mappable to enum value.
864	* @retval VERR_NO_STR_MEMORY if not mappable and we're out of memory.
865	* @param a_pszValue The string value.
866	* @param a_cchValue The string value length. Optional.
867	*/
868	int setByString(const char *a_pszValue, size_t a_cchValue = RTSTR_MAX);
869
870	/**
871	* Sets the value given a string value.
872	*
873	* @retval VINF_SUCCESS on success.
874	* @retval VWRN_NOT_FOUND if not mappable to enum value.
875	* @retval VERR_NO_STR_MEMORY if not mappable and we're out of memory.
876	* @param a_rValue The string value.
877	*/
878	int setByString(RTCString const &a_rValue);
879
880	/**
881	* Gets the string value.
882	*/
883	const char *getString() const;
884
885	/** Maps the given string value to an enum. */
886	int stringToEnum(const char *a_pszValue, size_t a_cchValue = RTSTR_MAX);
887	/** Maps the given string value to an enum. */
888	int stringToEnum(RTCString const &a_rStrValue);
889	/** Maps the given string value to an enum. */
890	const char enumToString(int a_iEnumValue, size_t a_pcchString);
891
892
893	protected:
894	/** The enum value. */
895	int m_iEnumValue;
896	/** The string value if not a match. */
897	RTCString m_strValue;
898
899	/**
900	* Worker for setting the object to the given enum value.
901	*
902	* @retval true on success.
903	* @retval false if a_iEnumValue can't be translated.
904	* @param a_iEnumValue The enum value to set.
905	*/
906	bool setWorker(int a_iEnumValue);
907
908	/**
909	* Gets the mapping table.
910	*
911	* @returns Pointer to the translation table.
912	* @param pcEntries Where to return the translation table size.
913	*/
914	virtual ENUMMAPENTRY const getMappingTable(size_t pcEntries) const = 0;
915	};
916
917
918	/**
919	* Class for handling binary blobs (strings).
920	*
921	* There are specializations of this class for body parameters and responses,
922	* see RTCRestBinaryParameter and RTCRestBinaryResponse.
923	*/
924	class RT_DECL_CLASS RTCRestBinary : public RTCRestObjectBase
925	{
926	public:
927	/** Default constructor. */
928	RTCRestBinary();
929	/** Destructor. */
930	virtual ~RTCRestBinary();
931
932	/** Safe copy assignment method. */
933	virtual int assignCopy(RTCRestBinary const &a_rThat);
934	/** Safe buffer copy method. */
935	virtual int assignCopy(void const *a_pvData, size_t a_cbData);
936
937	/** Use the specified data buffer directly. */
938	virtual int assignReadOnly(void const *a_pvData, size_t a_cbData);
939	/** Use the specified data buffer directly. */
940	virtual int assignWriteable(void *a_pvBuf, size_t a_cbBuf);
941	/** Frees the data held by the object and resets it default state. */
942	virtual void freeData();
943
944	/** Returns a pointer to the data blob. */
945	inline const uint8_t *getPtr() const { return m_pbData; }
946	/** Gets the size of the data. */
947	inline size_t getSize() const { return m_cbData; }
948
949	/* Overridden methods: */
950	virtual int setNull(void) RT_OVERRIDE;
951	virtual int resetToDefault(void) RT_OVERRIDE;
952	virtual RTCRestOutputBase &serializeAsJson(RTCRestOutputBase &a_rDst) const RT_OVERRIDE;
953	virtual int deserializeFromJson(RTCRestJsonCursor const &a_rCursor) RT_OVERRIDE;
954	virtual int toString(RTCString *a_pDst, uint32_t a_fFlags = kCollectionFormat_Unspecified) const RT_OVERRIDE;
955	virtual int fromString(RTCString const &a_rValue, const char *a_pszName, PRTERRINFO a_pErrInfo = NULL,
956	uint32_t a_fFlags = kCollectionFormat_Unspecified) RT_OVERRIDE;
957	virtual kTypeClass typeClass(void) const RT_OVERRIDE;
958	virtual const char *typeName(void) const RT_OVERRIDE;
959
960	/** Factory method. */
961	static DECLCALLBACK(RTCRestObjectBase *) createInstance(void);
962
963	protected:
964	/** Pointer to data blob. */
965	uint8_t *m_pbData;
966	/** Amount of valid data in the blob. */
967	size_t m_cbData;
968	/** Number of bytes allocated for the m_pbData buffer. */
969	size_t m_cbAllocated;
970	/** Set if the data is freeable, only ever clear if user data. */
971	bool m_fFreeable;
972	/** Set if the data blob is readonly user provided data. */
973	bool m_fReadOnly;
974
975	private:
976	/* No copy constructor or copy assignment: */
977	RTCRestBinary(RTCRestBinary const &a_rThat);
978	RTCRestBinary &operator=(RTCRestBinary const &a_rThat);
979	};
980
981
982	/** @} */
983
984	#endif
985

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

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

Download in other formats: