src/include/k5-json.h

   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 */