diff options
author | minfrin <minfrin@13f79535-47bb-0310-9956-ffa450edef68> | 2018-07-08 11:26:00 +0000 |
---|---|---|
committer | minfrin <minfrin@13f79535-47bb-0310-9956-ffa450edef68> | 2018-07-08 11:26:00 +0000 |
commit | 7822f42caaa6b65d5742b48b153f1e82543b8fe5 (patch) | |
tree | 8484d07ccaed8f5e7b5a0cd4e0af015e7163e3fe /include/apr_json.h | |
parent | 9d2258f6c89d82228e5146b7ab2846c357fbf116 (diff) | |
download | libapr-7822f42caaa6b65d5742b48b153f1e82543b8fe5.tar.gz |
apr_json: Add support for encoding and decoding RFC8259 JSON.
Submitted by: Moriyoshi Koizumi <mozo mozo jp>
git-svn-id: http://svn.apache.org/repos/asf/apr/apr/trunk@1835348 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'include/apr_json.h')
-rw-r--r-- | include/apr_json.h | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/include/apr_json.h b/include/apr_json.h new file mode 100644 index 000000000..a1342c836 --- /dev/null +++ b/include/apr_json.h @@ -0,0 +1,248 @@ +/* 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. + */ +/** + * @file apr_json.h + * @brief APR-UTIL JSON Library + */ +#ifndef APR_JSON_H +#define APR_JSON_H + +/** + * @defgroup APR_Util_JSON JSON Encoding and Decoding + * @ingroup APR_Util + * @{ + */ +#include "apr.h" +#include "apr_pools.h" +#include "apr_tables.h" +#include "apr_hash.h" +#include "apr_strings.h" +#include "apr_buckets.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @package Apache JSON library + * + * RFC8259 compliant JSON encoding and decoding library. + * + * https://tools.ietf.org/html/rfc8259 + * + * This API generates UTF-8 encoded JSON, and writes it to the + * bucket brigade specified. All strings are verified as valid UTF-8 + * before processing, with invalid UTF-8 characters replaced. + * + * This API parses UTF-8 encoded JSON, and returns the result as + * a set of structures. All JSON strings are unescaped. Any bad + * characters or formatting will cause parsing to be terminated + * and an error returned, along with the offset of the error. + * + * Whitespace may be optionally preserved or ignored as required + * during generation and parsing. + * + * The ordering of object keys is preserved, allowing the decode and + * encode process to reproduce an identical result. This maintains + * stable behaviour during unit tests. + */ + +/** + * When passing a string to one of the encode functions, this value can be + * passed to indicate a string-valued key, and have the length computed + * automatically. + */ +#define APR_JSON_VALUE_STRING (-1) + +/** + * Flag indicating no special processing. + */ +#define APR_JSON_FLAGS_NONE 0 + +/** + * Flag indicating include whitespace. + */ +#define APR_JSON_FLAGS_WHITESPACE 1 + +/** + * A structure to hold a JSON object. + */ +typedef struct apr_json_object_t apr_json_object_t; + +/** + * Enum that represents the type of the given JSON value. + */ +typedef enum apr_json_type_e { + APR_JSON_OBJECT, + APR_JSON_ARRAY, + APR_JSON_STRING, + APR_JSON_LONG, + APR_JSON_DOUBLE, + APR_JSON_BOOLEAN, + APR_JSON_NULL +} apr_json_type_e; + +/** + * A structure to hold a UTF-8 encoded JSON string. + */ +typedef struct apr_json_string_t { + /** pointer to the string */ + const char *p; + /** string length */ + apr_size_t len; +} apr_json_string_t; + +/** + * A structure that holds a JSON value. + * + * Use apr_json_value_create() to allocate. + */ +typedef struct apr_json_value_t { + /** preceding whitespace, if any */ + const char *pre; + /** trailing whitespace, if any */ + const char *post; + /** type of the value */ + apr_json_type_e type; + /** actual value. which member is valid depends on type. */ + union { + /** JSON object */ + apr_json_object_t *object; + /** JSON array */ + apr_array_header_t *array; + /** JSON floating point value */ + double dnumber; + /** JSON long integer value */ + apr_int64_t lnumber; + /** JSON UTF-8 encoded string value */ + apr_json_string_t string; + /** JSON boolean value */ + int boolean; + } value; +} apr_json_value_t; + +/** + * A structure to hold a JSON object key value pair. + * + * Use apr_json_object_set() to allocate. + */ +typedef struct apr_json_kv_t { + /** Links to the rest of the kv pairs */ + APR_RING_ENTRY(apr_json_kv_t) link; + /** the key */ + apr_json_value_t *k; + /** the value */ + apr_json_value_t *v; +} apr_json_kv_t; + +/** + * A structure to hold a JSON object. + * + * Use apr_json_object_create() to allocate. + */ +typedef struct apr_json_object_t { + /** The key value pairs in the object are in this list */ + APR_RING_HEAD(apr_json_object_list_t, apr_json_kv_t) list; + /** JSON object */ + apr_hash_t *hash; +} apr_json_object_t; + +/** + * Allocate and return a apr_json_value_t structure. + * + * @param pool The pool to allocate from. + * @return The apr_json_value_t structure. + */ +APR_DECLARE(apr_json_value_t *) apr_json_value_create(apr_pool_t *pool) + __attribute__((nonnull(1))); + +/** + * Allocate and return a apr_json_object_t structure. + * + * @param pool The pool to allocate from. + * @return The apr_json_object_t structure. + */ +APR_DECLARE(apr_json_object_t *) apr_json_object_create(apr_pool_t *pool) + __attribute__((nonnull(1))); + +/** + * Associate a value with a key in a JSON object. + * @param obj The JSON object. + * @param key Pointer to the key. + * @param val Value to associate with the key. + * @remark If the value is NULL the key value pair is deleted. + */ +APR_DECLARE(void) apr_json_object_set(apr_json_object_t *obj, + apr_json_value_t *key, apr_json_value_t *val, + apr_pool_t *pool) __attribute__((nonnull(1, 2, 4))); + +/** + * Look up the value associated with a key in a JSON object. + * @param ht The hash table + * @param key Pointer to the key + * @return Returns NULL if the key is not present. + */ +APR_DECLARE(apr_json_kv_t *) + apr_json_object_get(apr_json_object_t *obj, const char *key) + __attribute__((nonnull(1, 2))); + +/** + * Decode utf8-encoded JSON string into apr_json_value_t. + * @param retval the result + * @param injson utf8-encoded JSON string. + * @param size length of the input string. + * @param offset number of characters processed. + * @param flags set to APR_JSON_FLAGS_WHITESPACE to preserve whitespace, + * or APR_JSON_FLAGS_NONE to filter whitespace. + * @param level maximum nesting level we are prepared to decode. + * @param pool pool used to allocate the result from. + * @return APR_SUCCESS on success, APR_EOF if the JSON text is truncated. + * APR_BADCH when a decoding error has occurred (the location of the error + * is at offset), APR_EINVAL if the level has been exceeded, or + * APR_ENOTIMPL on platforms where not implemented. + */ +APR_DECLARE(apr_status_t) apr_json_decode(apr_json_value_t ** retval, + const char *injson, apr_ssize_t size, apr_off_t * offset, + int flags, int level, apr_pool_t * pool) + __attribute__((nonnull(1, 2, 7))); + +/** + * Encode data represented as apr_json_value_t to utf8-encoded JSON string + * and append it to the specified brigade. + * + * All JSON strings are checked for invalid UTF-8 character sequences, + * and if found invalid sequences are replaced with the replacement + * character "�" (U+FFFD). + * + * @param brigade brigade the result will be appended to. + * @param flush optional flush function for the brigade. Can be NULL. + * @param ctx optional contaxt for the flush function. Can be NULL. + * @param json the JSON data. + * @param flags set to APR_JSON_FLAGS_WHITESPACE to preserve whitespace, + * or APR_JSON_FLAGS_NONE to filter whitespace. + * @param pool pool used to allocate the buckets from. + * @return APR_SUCCESS on success, or APR_ENOTIMPL on platforms where not + * implemented. + */ +APR_DECLARE(apr_status_t) apr_json_encode(apr_bucket_brigade * brigade, + apr_brigade_flush flush, void *ctx, const apr_json_value_t * json, + int flags, apr_pool_t * pool) __attribute__((nonnull(1, 4, 6))); + +#ifdef __cplusplus +} +#endif +/** @} */ +#endif /* APR_JSON_H */ |