qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/ndds/rtijson/rtijson_builder.h

/*
 (c) Copyright, Real-Time Innovations, 2024.
 All rights reserved.
 
 No duplications, whole or partial, manual or electronic, may be made
 without express written permission.  Any such copies, or
 revisions thereof, must display this notice unaltered.
 This code contains trade secrets of Real-Time Innovations, Inc.
=========================================================================*/

#ifndef rtijson_builder_h
#define rtijson_builder_h

#include "rtijson/rtijson_dll.h"
#include "rtijson/rtijson_object.h"

#ifdef __cplusplus
    extern "C" {
#endif

#define RTIJSON_SERIALIZE_MODE_MULTILINE 0
#define RTIJSON_SERIALIZE_MODE_SINGLE_LINE 1

    /**
     * @brief Options for JSON serialization.
     */
    struct RTIJSONSerializeOptions {
        int mode;
        int indentSize;
    };

#define RTIJSONSerializeOptions_INITIALIZER \
    { \
        RTIJSON_SERIALIZE_MODE_MULTILINE, 4 \
    }

    /**
     * @brief Create a new JSON array.
     *
     * @param length [in] The initial length of the array.
     * @return A pointer to the new JSON array object, or NULL on failure.
     */
    extern RTIJSONDllExport RTIJSONObject *RTIJSONObject_arrayNew(
            size_t length);

    /** @brief Push a value into a JSON array.
     *
     * @param self [inout] The JSON array object.
     * @param value [inout] The value to push into the array.
     * @return RTI_TRUE on success, or RTI_FALSE on failure.
     */
    extern RTIJSONDllExport RTIBool
    RTIJSONObject_arrayPush(RTIJSONObject *self, RTIJSONObject *value);

    /**
     * @brief Create a new JSON object.
     *
     * @param length [in] Initial amount of child elements the object can hold
     * without reallocations.
     * @return A pointer to the new JSON object, or NULL on failure.
     */
    extern RTIJSONDllExport RTIJSONObject *RTIJSONObject_objectNew(
            size_t length);

    /**
     * @brief Push a value into a JSON object.
     *
     * @param self [inout] The JSON object.
     * @param value [inout] The value to push into the object.
     * @param name [in] The name of the value to push.
     * @return RTI_TRUE on success, or RTI_FALSE on failure.
     */
    extern RTIJSONDllExport RTIBool RTIJSONObject_objectPush(
            RTIJSONObject *self,
            RTIJSONObject *value,
            const char *name);

    /**
     * @brief Merge two JSON objects.
     *
     * @post The first object will contain the merged result, and the second
     * object will be freed.
     *
     * @param self [inout] The first JSON object.
     * @param other [inout] The second JSON object to merge into the first.
     * @return A pointer to the first object after merging, or NULL on failure.
     */
    extern RTIJSONDllExport RTIJSONObject *RTIJSONObject_objectMerge(
            RTIJSONObject *self,
            RTIJSONObject *other);

    /**
     * @brief Create a new JSON string.
     *
     * @param value [in] The string value. It cannot be NULL.
     * @return A pointer to the new JSON string object, or NULL on failure.
     */
    extern RTIJSONDllExport RTIJSONObject *RTIJSONObject_stringNew(
            const char *value);

    /**
     * @brief Create a new JSON integer.
     *
     * @param value [in] The integer value.
     * @return A pointer to the new JSON integer object, or NULL on failure.
     */
    extern RTIJSONDllExport RTIJSONObject *RTIJSONObject_integerNew(
            RTI_INT64 value);

    /**
     * @brief Create a new JSON double.
     *
     * @param value [in] The double value.
     * @return A pointer to the new JSON double object, or NULL on failure.
     */
    extern RTIJSONDllExport RTIJSONObject *RTIJSONObject_doubleNew(
            RTI_DOUBLE64 value);

    /**
     * @brief Create a new JSON boolean.
     *
     * @param value [in] The boolean value.
     * @return A pointer to the new JSON boolean object, or NULL on failure.
     */
    extern RTIJSONDllExport RTIJSONObject *RTIJSONObject_booleanNew(
            RTIBool value);

    /**
     * @brief Create a new JSON null value.
     *
     * @return A pointer to the new JSON null object, or NULL on failure.
     */
    extern RTIJSONDllExport RTIJSONObject *RTIJSONObject_nullNew(void);

    /**
     * @brief Calculates the size of the serialized JSON object.
     *
     * @param self [inout] The JSON object to measure.
     * @return The size of the serialized JSON object in bytes, or 0 if the
     * object is NULL.
     */
    extern RTIJSONDllExport size_t RTIJSONObject_measure(RTIJSONObject *self);

    /**
     * @brief Calculates the size of the serialized JSON object with options.
     *
     * @param self [inout] The JSON object to measure.
     * @param options [in] The serialization options.
     * @return The size of the serialized JSON object in bytes, or 0 if the
     * object is NULL.
     */
    extern RTIJSONDllExport size_t RTIJSONObject_measureWithOptions(
            RTIJSONObject *self,
            const struct RTIJSONSerializeOptions *options);

    /**
     * @brief Serialize a JSON object into a buffer.
     *
     * @param self [inout] The JSON object to serialize.
     * @param buffer [out] The buffer to hold the serialized JSON.
     * @param bufferSize [in] The size of the buffer.
     * @return RTI_TRUE on success, or RTI_FALSE if the buffer is not large
     * enough or if the object is NULL.
     */
    extern RTIJSONDllExport RTIBool RTIJSONObject_serialize(
            RTIJSONObject *self,
            char *buffer,
            size_t bufferSize);

    /**
     * @brief Serialize a JSON object into a buffer with options.
     *
     * @param self [inout] The JSON object to serialize.
     * @param buffer [out] The buffer to hold the serialized JSON.
     * @param bufferSize [in] The size of the buffer.
     * @param options [in] The serialization options.
     * @return RTI_TRUE on success, or RTI_FALSE if the buffer is not
     * large enough or if the object is NULL.
     */
    extern RTIJSONDllExport RTIBool RTIJSONObject_serializeWithOptions(
            RTIJSONObject *self,
            char *buffer,
            size_t bufferSize,
            const struct RTIJSONSerializeOptions *options);

    /**
     * @brief Free a JSON that was modified by the builder.
     *
     * This function only deletes the object if it has no parents, although you
     * should still delete it even if the parent is deleted.
     *
     * @param self [inout] The JSON object to free.
     */
    extern RTIJSONDllExport void RTIJSONObject_builderDelete(
            RTIJSONObject *self);

#ifdef __cplusplus
    }	/* extern "C" */
#endif

#endif /* rtijson_builder_h */