1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 /* include/k5-json.h - JSON declarations */ 3 /* 4 * Copyright (c) 2010 Kungliga Tekniska Högskolan 5 * (Royal Institute of Technology, Stockholm, Sweden). 6 * All rights reserved. 7 * 8 * Portions Copyright (c) 2010 Apple Inc. All rights reserved. 9 * 10 * Redistribution and use in source and binary forms, with or without 11 * modification, are permitted provided that the following conditions 12 * are met: 13 * 14 * 1. Redistributions of source code must retain the above copyright 15 * notice, this list of conditions and the following disclaimer. 16 * 17 * 2. Redistributions in binary form must reproduce the above copyright 18 * notice, this list of conditions and the following disclaimer in the 19 * documentation and/or other materials provided with the distribution. 20 * 21 * 3. Neither the name of the Institute nor the names of its contributors 22 * may be used to endorse or promote products derived from this software 23 * without specific prior written permission. 24 * 25 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 26 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 29 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35 * SUCH DAMAGE. 36 */ 37 /* 38 * Copyright (C) 2012 by the Massachusetts Institute of Technology. 39 * All rights reserved. 40 * 41 * Redistribution and use in source and binary forms, with or without 42 * modification, are permitted provided that the following conditions 43 * are met: 44 * 45 * * Redistributions of source code must retain the above copyright 46 * notice, this list of conditions and the following disclaimer. 47 * 48 * * Redistributions in binary form must reproduce the above copyright 49 * notice, this list of conditions and the following disclaimer in 50 * the documentation and/or other materials provided with the 51 * distribution. 52 * 53 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 54 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 55 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 56 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 57 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 58 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 59 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 60 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 61 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 62 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 63 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 64 * OF THE POSSIBILITY OF SUCH DAMAGE. 65 */ 66 67 #ifndef K5_JSON_H 68 #define K5_JSON_H 69 70 #include <stddef.h> 71 72 #define K5_JSON_TID_NUMBER 0 73 #define K5_JSON_TID_NULL 1 74 #define K5_JSON_TID_BOOL 2 75 #define K5_JSON_TID_MEMORY 128 76 #define K5_JSON_TID_ARRAY 129 77 #define K5_JSON_TID_OBJECT 130 78 #define K5_JSON_TID_STRING 131 79 80 /* 81 * The k5_json_value C type can represent any kind of JSON value. It has no 82 * static type safety since it is represented using a void pointer, so be 83 * careful with it. Its type can be checked dynamically with k5_json_get_tid() 84 * and the above constants. 85 */ 86 typedef void *k5_json_value; 87 typedef unsigned int k5_json_tid; 88 89 k5_json_tid k5_json_get_tid(k5_json_value val); 90 91 /* 92 * k5_json_value objects are reference-counted. These functions increment and 93 * decrement the refcount, possibly freeing the value. k5_json_retain returns 94 * its argument and always succeeds. Both functions gracefully accept NULL. 95 */ 96 k5_json_value k5_json_retain(k5_json_value val); 97 void k5_json_release(k5_json_value val); 98 99 /* 100 * If a k5_json_* function can fail, it returns 0 on success and an errno value 101 * on failure. 102 */ 103 104 /* 105 * Null 106 */ 107 108 typedef struct k5_json_null_st *k5_json_null; 109 110 int k5_json_null_create(k5_json_null *null_out); 111 112 /* Create a null value as a k5_json_value, for polymorphic convenience. */ 113 int k5_json_null_create_val(k5_json_value *val_out); 114 115 /* 116 * Boolean 117 */ 118 119 typedef struct k5_json_bool_st *k5_json_bool; 120 121 int k5_json_bool_create(int truth, k5_json_bool *val_out); 122 int k5_json_bool_value(k5_json_bool bval); 123 124 /* 125 * Array 126 */ 127 128 typedef struct k5_json_array_st *k5_json_array; 129 130 int k5_json_array_create(k5_json_array *val_out); 131 size_t k5_json_array_length(k5_json_array array); 132 133 /* Both of these functions increment the reference count on val. */ 134 int k5_json_array_add(k5_json_array array, k5_json_value val); 135 void k5_json_array_set(k5_json_array array, size_t idx, k5_json_value val); 136 137 /* Get an alias to the idx-th element of array, without incrementing the 138 * reference count. The caller must check idx against the array length. */ 139 k5_json_value k5_json_array_get(k5_json_array array, size_t idx); 140 141 /* 142 * Create an array from a template and a variable argument list. template 143 * characters are: 144 * v: a k5_json_value argument is read, retained, and stored 145 * n: no argument is read; a null value is stored 146 * b: an int argument is read and stored as a boolean value 147 * i: an int argument is read and stored as a number value 148 * L: a long long argument is read and stored as a number value 149 * s: a const char * argument is read and stored as a null or string value 150 * B: const void * and size_t arguments are read and stored as a base64 151 * string value 152 */ 153 int 154 k5_json_array_fmt(k5_json_array *array_out, const char *template, ...); 155 156 /* 157 * Object 158 */ 159 160 typedef struct k5_json_object_st *k5_json_object; 161 typedef void (*k5_json_object_iterator_fn)(void *arg, const char *key, 162 k5_json_value val); 163 164 int k5_json_object_create(k5_json_object *val_out); 165 void k5_json_object_iterate(k5_json_object obj, 166 k5_json_object_iterator_fn func, void *arg); 167 168 /* Return the number of mappings in an object. */ 169 size_t k5_json_object_count(k5_json_object obj); 170 171 /* 172 * Store val into object at key, incrementing val's reference count and 173 * releasing any previous value at key. If val is NULL, key is removed from 174 * obj if it exists, and obj remains unchanged if it does not. 175 */ 176 int k5_json_object_set(k5_json_object obj, const char *key, k5_json_value val); 177 178 /* Get an alias to the object's value for key, without incrementing the 179 * reference count. Returns NULL if there is no value for key. */ 180 k5_json_value k5_json_object_get(k5_json_object obj, const char *key); 181 182 /* 183 * String 184 */ 185 186 typedef struct k5_json_string_st *k5_json_string; 187 188 int k5_json_string_create(const char *cstring, k5_json_string *val_out); 189 int k5_json_string_create_len(const void *data, size_t len, 190 k5_json_string *val_out); 191 const char *k5_json_string_utf8(k5_json_string string); 192 193 194 /* Create a base64 string value from binary data. */ 195 int k5_json_string_create_base64(const void *data, size_t len, 196 k5_json_string *val_out); 197 198 /* Decode the base64 contents of string. */ 199 int k5_json_string_unbase64(k5_json_string string, unsigned char **data_out, 200 size_t *len_out); 201 202 /* 203 * Number 204 */ 205 206 typedef struct k5_json_number_st *k5_json_number; 207 208 int k5_json_number_create(long long number, k5_json_number *val_out); 209 long long k5_json_number_value(k5_json_number number); 210 211 /* 212 * JSON encoding and decoding 213 */ 214 215 int k5_json_encode(k5_json_value val, char **json_out); 216 int k5_json_decode(const char *str, k5_json_value *val_out); 217 218 #endif /* K5_JSON_H */ 219