json.h (6376B)
1/* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20#ifndef GUAC_COMMON_JSON_H 21#define GUAC_COMMON_JSON_H 22 23#include "config.h" 24 25#include <guacamole/stream.h> 26#include <guacamole/user.h> 27 28/** 29 * The current streaming state of an arbitrary JSON object, consisting of 30 * any number of property name/value pairs. 31 */ 32typedef struct guac_common_json_state { 33 34 /** 35 * Buffer of partial JSON data. The individual blobs which make up the JSON 36 * body of the object being sent over the Guacamole protocol will be 37 * built here. 38 */ 39 char buffer[4096]; 40 41 /** 42 * The number of bytes currently used within the JSON buffer. 43 */ 44 int size; 45 46 /** 47 * The number of property name/value pairs written to the JSON object thus 48 * far. 49 */ 50 int properties_written; 51 52} guac_common_json_state; 53 54/** 55 * Given a stream, the user to which it belongs, and the current stream state 56 * of a JSON object, flushes the contents of the JSON buffer to a blob 57 * instruction. Note that this will flush the JSON buffer only, and will not 58 * necessarily flush the underlying guac_socket of the user. 59 * 60 * @param user 61 * The user to which the data will be flushed. 62 * 63 * @param stream 64 * The stream through which the flushed data should be sent as a blob. 65 * 66 * @param json_state 67 * The state object whose buffer should be flushed. 68 */ 69void guac_common_json_flush(guac_user* user, guac_stream* stream, 70 guac_common_json_state* json_state); 71 72/** 73 * Given a stream, the user to which it belongs, and the current stream state 74 * of a JSON object, writes the contents of the given buffer to the JSON buffer 75 * of the stream state, flushing as necessary. 76 * 77 * @param user 78 * The user to which the data will be flushed as necessary. 79 * 80 * @param stream 81 * The stream through which the flushed data should be sent as a blob, if 82 * data must be flushed at all. 83 * 84 * @param json_state 85 * The state object containing the JSON buffer to which the given buffer 86 * should be written. 87 * 88 * @param buffer 89 * The buffer to write. 90 * 91 * @param length 92 * The number of bytes in the buffer. 93 * 94 * @return 95 * Non-zero if at least one blob was written, zero otherwise. 96 */ 97int guac_common_json_write(guac_user* user, guac_stream* stream, 98 guac_common_json_state* json_state, const char* buffer, int length); 99 100/** 101 * Given a stream, the user to which it belongs, and the current stream state 102 * of a JSON object state, writes the given string as a proper JSON string, 103 * including starting and ending quotes. The contents of the string will be 104 * escaped as necessary. 105 * 106 * @param user 107 * The user to which the data will be flushed as necessary. 108 * 109 * @param stream 110 * The stream through which the flushed data should be sent as a blob, if 111 * data must be flushed at all. 112 * 113 * @param json_state 114 * The state object containing the JSON buffer to which the given string 115 * should be written as a JSON name/value pair. 116 * 117 * @param str 118 * The string to write. 119 * 120 * @return 121 * Non-zero if at least one blob was written, zero otherwise. 122 */ 123int guac_common_json_write_string(guac_user* user, 124 guac_stream* stream, guac_common_json_state* json_state, 125 const char* str); 126 127/** 128 * Given a stream, the user to which it belongs, and the current stream state 129 * of a JSON object, writes the given JSON property name/value pair. The 130 * name and value will be written as proper JSON strings separated by a colon. 131 * 132 * @param user 133 * The user to which the data will be flushed as necessary. 134 * 135 * @param stream 136 * The stream through which the flushed data should be sent as a blob, if 137 * data must be flushed at all. 138 * 139 * @param json_state 140 * The state object containing the JSON buffer to which the given strings 141 * should be written as a JSON name/value pair. 142 * 143 * @param name 144 * The name of the property to write. 145 * 146 * @param value 147 * The value of the property to write. 148 * 149 * @return 150 * Non-zero if at least one blob was written, zero otherwise. 151 */ 152int guac_common_json_write_property(guac_user* user, guac_stream* stream, 153 guac_common_json_state* json_state, const char* name, 154 const char* value); 155 156/** 157 * Given a stream, the user to which it belongs, and the current stream state 158 * of a JSON object, initializes the state for writing a new JSON object. Note 159 * that although the user and stream must be provided, no instruction or 160 * blobs will be written due to any call to this function. 161 * 162 * @param user 163 * The user associated with the given stream. 164 * 165 * @param stream 166 * The stream associated with the JSON object being written. 167 * 168 * @param json_state 169 * The state object to initialize. 170 */ 171void guac_common_json_begin_object(guac_user* user, guac_stream* stream, 172 guac_common_json_state* json_state); 173 174/** 175 * Given a stream, the user to which it belongs, and the current stream state 176 * of a JSON object, completes writing that JSON object by writing the final 177 * terminating brace. This function must only be called following a 178 * corresponding call to guac_common_json_begin_object(). 179 * 180 * @param user 181 * The user associated with the given stream. 182 * 183 * @param stream 184 * The stream associated with the JSON object being written. 185 * 186 * @param json_state 187 * The state object whose in-progress JSON object should be terminated. 188 * 189 * @return 190 * Non-zero if at least one blob was written, zero otherwise. 191 */ 192int guac_common_json_end_object(guac_user* user, guac_stream* stream, 193 guac_common_json_state* json_state); 194 195#endif 196