280 lines
8.8 KiB
C++
280 lines
8.8 KiB
C++
/** @file
|
|
* IPRT - C++ Representational State Transfer (REST) Output Classes.
|
|
*/
|
|
|
|
/*
|
|
* Copyright (C) 2008-2024 Oracle and/or its affiliates.
|
|
*
|
|
* This file is part of VirtualBox base platform packages, as
|
|
* available from https://www.virtualbox.org.
|
|
*
|
|
* This program is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU General Public License
|
|
* as published by the Free Software Foundation, in version 3 of the
|
|
* License.
|
|
*
|
|
* This program is distributed in the hope that it will be useful, but
|
|
* WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, see <https://www.gnu.org/licenses>.
|
|
*
|
|
* The contents of this file may alternatively be used under the terms
|
|
* of the Common Development and Distribution License Version 1.0
|
|
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
|
* in the VirtualBox distribution, in which case the provisions of the
|
|
* CDDL are applicable instead of those of the GPL.
|
|
*
|
|
* You may elect to license modified versions of this file under the
|
|
* terms and conditions of either the GPL or the CDDL or both.
|
|
*
|
|
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
|
*/
|
|
|
|
#ifndef IPRT_INCLUDED_cpp_restoutput_h
|
|
#define IPRT_INCLUDED_cpp_restoutput_h
|
|
#ifndef RT_WITHOUT_PRAGMA_ONCE
|
|
# pragma once
|
|
#endif
|
|
|
|
#include <iprt/cdefs.h>
|
|
#include <iprt/types.h>
|
|
#include <iprt/stdarg.h>
|
|
#include <iprt/cpp/ministring.h>
|
|
|
|
|
|
/** @defgroup grp_rt_cpp_restoutput C++ Representational State Transfer (REST) Output Classes.
|
|
* @ingroup grp_rt_cpp
|
|
* @{
|
|
*/
|
|
|
|
|
|
/**
|
|
* Abstract base class for serializing data objects.
|
|
*/
|
|
class RT_DECL_CLASS RTCRestOutputBase
|
|
{
|
|
public:
|
|
RTCRestOutputBase() RT_NOEXCEPT;
|
|
virtual ~RTCRestOutputBase();
|
|
|
|
/**
|
|
* Raw output function.
|
|
*
|
|
* @returns Number of bytes outputted.
|
|
* @param a_pchString The string to output (not necessarily terminated).
|
|
* @param a_cchToWrite The length of the string
|
|
*/
|
|
virtual size_t output(const char *a_pchString, size_t a_cchToWrite) RT_NOEXCEPT = 0;
|
|
|
|
/**
|
|
* RTStrPrintf like function (see @ref pg_rt_str_format).
|
|
*
|
|
* @returns Number of bytes outputted.
|
|
* @param pszFormat The format string.
|
|
* @param ... Argument specfied in @a pszFormat.
|
|
*/
|
|
inline size_t printf(const char *pszFormat, ...) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(2, 3)
|
|
{
|
|
va_list va;
|
|
va_start(va, pszFormat);
|
|
size_t cchWritten = this->vprintf(pszFormat, va);
|
|
va_end(va);
|
|
return cchWritten;
|
|
}
|
|
|
|
/**
|
|
* RTStrPrintfV like function (see @ref pg_rt_str_format).
|
|
*
|
|
* @returns Number of bytes outputted.
|
|
* @param pszFormat The format string.
|
|
* @param va Argument specfied in @a pszFormat.
|
|
*/
|
|
size_t vprintf(const char *pszFormat, va_list va) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(2, 0);
|
|
|
|
/**
|
|
* Begins an array.
|
|
* @returns Previous output state. Pass to endArray() when done.
|
|
*/
|
|
virtual uint32_t beginArray() RT_NOEXCEPT;
|
|
|
|
/**
|
|
* Ends an array.
|
|
* @param a_uOldState Previous output state (returned by beginArray()).
|
|
*/
|
|
virtual void endArray(uint32_t a_uOldState) RT_NOEXCEPT;
|
|
|
|
/**
|
|
* Begins an object.
|
|
* @returns Previous output state. Pass to endObject() when done.
|
|
*/
|
|
virtual uint32_t beginObject() RT_NOEXCEPT;
|
|
|
|
/**
|
|
* Ends an array.
|
|
* @param a_uOldState Previous output state (returned by beginObject()).
|
|
*/
|
|
virtual void endObject(uint32_t a_uOldState) RT_NOEXCEPT;
|
|
|
|
/**
|
|
* Outputs a value separator.
|
|
* This is called before a value, not after.
|
|
*/
|
|
virtual void valueSeparator() RT_NOEXCEPT;
|
|
|
|
/**
|
|
* Outputs a value separator, name and name separator.
|
|
*/
|
|
virtual void valueSeparatorAndName(const char *a_pszName, size_t a_cchName) RT_NOEXCEPT;
|
|
|
|
/** Outputs a null-value. */
|
|
void nullValue() RT_NOEXCEPT;
|
|
|
|
protected:
|
|
/** The current indentation level (bits 15:0) and separator state (bit 31). */
|
|
uint32_t m_uState;
|
|
|
|
/** @callback_method_impl{FNRTSTROUTPUT} */
|
|
static DECLCALLBACK(size_t) printfOutputCallback(void *pvArg, const char *pachChars, size_t cbChars) RT_NOEXCEPT;
|
|
};
|
|
|
|
|
|
/**
|
|
* Abstract base class for pretty output.
|
|
*/
|
|
class RT_DECL_CLASS RTCRestOutputPrettyBase : public RTCRestOutputBase
|
|
{
|
|
public:
|
|
RTCRestOutputPrettyBase() RT_NOEXCEPT;
|
|
virtual ~RTCRestOutputPrettyBase();
|
|
|
|
/**
|
|
* Begins an array.
|
|
* @returns Previous output state. Pass to endArray() when done.
|
|
*/
|
|
virtual uint32_t beginArray() RT_NOEXCEPT RT_OVERRIDE;
|
|
|
|
/**
|
|
* Ends an array.
|
|
* @param a_uOldState Previous output state (returned by beginArray()).
|
|
*/
|
|
virtual void endArray(uint32_t a_uOldState) RT_NOEXCEPT RT_OVERRIDE;
|
|
|
|
/**
|
|
* Begins an object.
|
|
* @returns Previous output state. Pass to endObject() when done.
|
|
*/
|
|
virtual uint32_t beginObject() RT_NOEXCEPT RT_OVERRIDE;
|
|
|
|
/**
|
|
* Ends an array.
|
|
* @param a_uOldState Previous output state (returned by beginObject()).
|
|
*/
|
|
virtual void endObject(uint32_t a_uOldState) RT_NOEXCEPT RT_OVERRIDE;
|
|
|
|
/**
|
|
* Outputs a value separator.
|
|
* This is called before a value, not after.
|
|
*/
|
|
virtual void valueSeparator() RT_NOEXCEPT RT_OVERRIDE;
|
|
|
|
/**
|
|
* Outputs a value separator, name and name separator.
|
|
*/
|
|
virtual void valueSeparatorAndName(const char *a_pszName, size_t a_cchName) RT_NOEXCEPT RT_OVERRIDE;
|
|
|
|
protected:
|
|
/** Helper for outputting the correct amount of indentation. */
|
|
void outputIndentation() RT_NOEXCEPT;
|
|
};
|
|
|
|
|
|
/**
|
|
* Serialize to a string object.
|
|
*/
|
|
class RT_DECL_CLASS RTCRestOutputToString : public RTCRestOutputBase
|
|
{
|
|
public:
|
|
/**
|
|
* Creates an instance that appends to @a a_pDst.
|
|
* @param a_pDst Pointer to the destination string object.
|
|
* NULL is not accepted and will assert.
|
|
* @param a_fAppend Whether to append to the current string value, or
|
|
* nuke the string content before starting the output.
|
|
*/
|
|
RTCRestOutputToString(RTCString *a_pDst, bool a_fAppend = false) RT_NOEXCEPT;
|
|
virtual ~RTCRestOutputToString();
|
|
|
|
virtual size_t output(const char *a_pchString, size_t a_cchToWrite) RT_NOEXCEPT RT_OVERRIDE;
|
|
|
|
/**
|
|
* Finalizes the output and releases the string object to the caller.
|
|
*
|
|
* @returns The released string object. NULL if we ran out of memory or if
|
|
* called already.
|
|
*
|
|
* @remark This sets m_pDst to NULL and the object cannot be use for any
|
|
* more output afterwards.
|
|
*/
|
|
virtual RTCString *finalize() RT_NOEXCEPT;
|
|
|
|
protected:
|
|
/** Pointer to the destination string. NULL after finalize(). */
|
|
RTCString *m_pDst;
|
|
/** Set if we ran out of memory and should ignore subsequent calls. */
|
|
bool m_fOutOfMemory;
|
|
|
|
/* Make non-copyable (RTCNonCopyable causes warnings): */
|
|
RTCRestOutputToString(RTCRestOutputToString const &);
|
|
RTCRestOutputToString *operator=(RTCRestOutputToString const &);
|
|
};
|
|
|
|
|
|
/**
|
|
* Serialize pretty JSON to a string object.
|
|
*/
|
|
class RT_DECL_CLASS RTCRestOutputPrettyToString : public RTCRestOutputPrettyBase
|
|
{
|
|
public:
|
|
/**
|
|
* Creates an instance that appends to @a a_pDst.
|
|
* @param a_pDst Pointer to the destination string object.
|
|
* NULL is not accepted and will assert.
|
|
* @param a_fAppend Whether to append to the current string value, or
|
|
* nuke the string content before starting the output.
|
|
*/
|
|
RTCRestOutputPrettyToString(RTCString *a_pDst, bool a_fAppend = false) RT_NOEXCEPT;
|
|
virtual ~RTCRestOutputPrettyToString();
|
|
|
|
virtual size_t output(const char *a_pchString, size_t a_cchToWrite) RT_NOEXCEPT RT_OVERRIDE;
|
|
|
|
/**
|
|
* Finalizes the output and releases the string object to the caller.
|
|
*
|
|
* @returns The released string object. NULL if we ran out of memory or if
|
|
* called already.
|
|
*
|
|
* @remark This sets m_pDst to NULL and the object cannot be use for any
|
|
* more output afterwards.
|
|
*/
|
|
virtual RTCString *finalize() RT_NOEXCEPT;
|
|
|
|
protected:
|
|
/** Pointer to the destination string. NULL after finalize(). */
|
|
RTCString *m_pDst;
|
|
/** Set if we ran out of memory and should ignore subsequent calls. */
|
|
bool m_fOutOfMemory;
|
|
|
|
/* Make non-copyable (RTCNonCopyable causes warnings): */
|
|
RTCRestOutputPrettyToString(RTCRestOutputToString const &);
|
|
RTCRestOutputPrettyToString *operator=(RTCRestOutputToString const &);
|
|
};
|
|
|
|
|
|
|
|
/** @} */
|
|
|
|
#endif /* !IPRT_INCLUDED_cpp_restoutput_h */
|
|
|