src/common/common/json.h

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

#ifndef GUAC_COMMON_JSON_H
#define GUAC_COMMON_JSON_H

#include "config.h"

#include <guacamole/stream.h>
#include <guacamole/user.h>

/**
 * The current streaming state of an arbitrary JSON object, consisting of
 * any number of property name/value pairs.
 */
typedef struct guac_common_json_state {

    /**
     * Buffer of partial JSON data. The individual blobs which make up the JSON
     * body of the object being sent over the Guacamole protocol will be
     * built here.
     */
    char buffer[4096];

    /**
     * The number of bytes currently used within the JSON buffer.
     */
    int size;

    /**
     * The number of property name/value pairs written to the JSON object thus
     * far.
     */
    int properties_written;

} guac_common_json_state;

/**
 * Given a stream, the user to which it belongs, and the current stream state
 * of a JSON object, flushes the contents of the JSON buffer to a blob
 * instruction. Note that this will flush the JSON buffer only, and will not
 * necessarily flush the underlying guac_socket of the user.
 *
 * @param user
 *     The user to which the data will be flushed.
 *
 * @param stream
 *     The stream through which the flushed data should be sent as a blob.
 *
 * @param json_state
 *     The state object whose buffer should be flushed.
 */
void guac_common_json_flush(guac_user* user, guac_stream* stream,
        guac_common_json_state* json_state);

/**
 * Given a stream, the user to which it belongs, and the current stream state
 * of a JSON object, writes the contents of the given buffer to the JSON buffer
 * of the stream state, flushing as necessary.
 *
 * @param user
 *     The user to which the data will be flushed as necessary.
 *
 * @param stream
 *     The stream through which the flushed data should be sent as a blob, if
 *     data must be flushed at all.
 *
 * @param json_state
 *     The state object containing the JSON buffer to which the given buffer
 *     should be written.
 *
 * @param buffer
 *     The buffer to write.
 *
 * @param length
 *     The number of bytes in the buffer.
 *
 * @return
 *     Non-zero if at least one blob was written, zero otherwise.
 */
int guac_common_json_write(guac_user* user, guac_stream* stream,
        guac_common_json_state* json_state, const char* buffer, int length);

/**
 * Given a stream, the user to which it belongs, and the current stream state
 * of a JSON object state, writes the given string as a proper JSON string,
 * including starting and ending quotes. The contents of the string will be
 * escaped as necessary.
 *
 * @param user
 *     The user to which the data will be flushed as necessary.
 *
 * @param stream
 *     The stream through which the flushed data should be sent as a blob, if
 *     data must be flushed at all.
 *
 * @param json_state
 *     The state object containing the JSON buffer to which the given string
 *     should be written as a JSON name/value pair.
 *
 * @param str
 *     The string to write.
 *
 * @return
 *     Non-zero if at least one blob was written, zero otherwise.
 */
int guac_common_json_write_string(guac_user* user,
        guac_stream* stream, guac_common_json_state* json_state,
        const char* str);

/**
 * Given a stream, the user to which it belongs, and the current stream state
 * of a JSON object, writes the given JSON property name/value pair. The
 * name and value will be written as proper JSON strings separated by a colon.
 *
 * @param user
 *     The user to which the data will be flushed as necessary.
 *
 * @param stream
 *     The stream through which the flushed data should be sent as a blob, if
 *     data must be flushed at all.
 *
 * @param json_state
 *     The state object containing the JSON buffer to which the given strings
 *     should be written as a JSON name/value pair.
 *
 * @param name
 *     The name of the property to write.
 *
 * @param value
 *     The value of the property to write.
 *
 * @return
 *     Non-zero if at least one blob was written, zero otherwise.
 */
int guac_common_json_write_property(guac_user* user, guac_stream* stream,
        guac_common_json_state* json_state, const char* name,
        const char* value);

/**
 * Given a stream, the user to which it belongs, and the current stream state
 * of a JSON object, initializes the state for writing a new JSON object. Note
 * that although the user and stream must be provided, no instruction or
 * blobs will be written due to any call to this function.
 *
 * @param user
 *     The user associated with the given stream.
 *
 * @param stream
 *     The stream associated with the JSON object being written.
 *
 * @param json_state
 *     The state object to initialize.
 */
void guac_common_json_begin_object(guac_user* user, guac_stream* stream,
        guac_common_json_state* json_state);

/**
 * Given a stream, the user to which it belongs, and the current stream state
 * of a JSON object, completes writing that JSON object by writing the final
 * terminating brace. This function must only be called following a
 * corresponding call to guac_common_json_begin_object().
 *
 * @param user
 *     The user associated with the given stream.
 *
 * @param stream
 *     The stream associated with the JSON object being written.
 *
 * @param json_state
 *     The state object whose in-progress JSON object should be terminated.
 *
 * @return
 *     Non-zero if at least one blob was written, zero otherwise.
 */
int guac_common_json_end_object(guac_user* user, guac_stream* stream,
        guac_common_json_state* json_state);

#endif