1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to you under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * https://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 14 * implied. See the License for the specific language governing 15 * permissions and limitations under the License. 16 */ 17 18 #ifndef AVRO_VALUE_H 19 #define AVRO_VALUE_H 20 #ifdef __cplusplus 21 extern "C" { 22 #define CLOSE_EXTERN } 23 #else 24 #define CLOSE_EXTERN 25 #endif 26 27 #include <errno.h> 28 #include <avro/platform.h> 29 #include <stdlib.h> 30 31 #include <avro/data.h> 32 #include <avro/schema.h> 33 34 /* 35 * This file defines an interface struct for Avro data. Most of the 36 * interesting parts of this library will work with Avro data values 37 * that are expressed in whatever C type you want, as long as you can 38 * provide an implementation of this interface for that type. 39 */ 40 41 typedef struct avro_value_iface avro_value_iface_t; 42 43 typedef struct avro_value { 44 avro_value_iface_t *iface; 45 void *self; 46 } avro_value_t; 47 48 struct avro_value_iface { 49 /*------------------------------------------------------------- 50 * "class" methods 51 */ 52 53 /** 54 * Increment the reference count of the interface struct. This 55 * should be a no-op for static structs, since they don't need 56 * reference counts. 57 */ 58 avro_value_iface_t * 59 (*incref_iface)(avro_value_iface_t *iface); 60 61 /** 62 * Decrement the reference count of the interface struct. If 63 * the count falls to 0, free the struct. This should be a 64 * no-op for static structs, since they don't need reference 65 * counts. 66 */ 67 void 68 (*decref_iface)(avro_value_iface_t *iface); 69 70 /*------------------------------------------------------------- 71 * General "instance" methods 72 */ 73 74 /** 75 * Increments the reference count of a value. 76 */ 77 78 void 79 (*incref)(avro_value_t *value); 80 81 /** 82 * Decrements the reference count of a value, and frees the 83 * value if the reference count drops to 0. After calling this 84 * method, your value instance is undefined, and cannot be used 85 * anymore. 86 */ 87 88 void 89 (*decref)(avro_value_t *value); 90 91 /** 92 * Reset the instance to its "empty", default value. You don't 93 * have to free the underlying storage, if you want to keep it 94 * around for later values. 95 */ 96 int 97 (*reset)(const avro_value_iface_t *iface, void *self); 98 99 /** 100 * Return the general Avro type of a value instance. 101 */ 102 avro_type_t 103 (*get_type)(const avro_value_iface_t *iface, const void *self); 104 105 /** 106 * Return the Avro schema that a value is an instance of. 107 */ 108 avro_schema_t 109 (*get_schema)(const avro_value_iface_t *iface, const void *self); 110 111 /*------------------------------------------------------------- 112 * Primitive value getters 113 */ 114 int (*get_boolean)(const avro_value_iface_t *iface, 115 const void *self, int *out); 116 int (*get_bytes)(const avro_value_iface_t *iface, 117 const void *self, const void **buf, size_t *size); 118 int (*grab_bytes)(const avro_value_iface_t *iface, 119 const void *self, avro_wrapped_buffer_t *dest); 120 int (*get_double)(const avro_value_iface_t *iface, 121 const void *self, double *out); 122 int (*get_float)(const avro_value_iface_t *iface, 123 const void *self, float *out); 124 int (*get_int)(const avro_value_iface_t *iface, 125 const void *self, int32_t *out); 126 int (*get_long)(const avro_value_iface_t *iface, 127 const void *self, int64_t *out); 128 int (*get_null)(const avro_value_iface_t *iface, 129 const void *self); 130 /* The result will be NUL-terminated; the size will INCLUDE the 131 * NUL terminator. str will never be NULL unless there's an 132 * error. */ 133 int (*get_string)(const avro_value_iface_t *iface, 134 const void *self, const char **str, size_t *size); 135 int (*grab_string)(const avro_value_iface_t *iface, 136 const void *self, avro_wrapped_buffer_t *dest); 137 138 int (*get_enum)(const avro_value_iface_t *iface, 139 const void *self, int *out); 140 int (*get_fixed)(const avro_value_iface_t *iface, 141 const void *self, const void **buf, size_t *size); 142 int (*grab_fixed)(const avro_value_iface_t *iface, 143 const void *self, avro_wrapped_buffer_t *dest); 144 145 /*------------------------------------------------------------- 146 * Primitive value setters 147 */ 148 149 /* 150 * The "give" setters can be used to give control of an existing 151 * buffer to a bytes, fixed, or string value. The free function 152 * will be called when the buffer is no longer needed. (It's 153 * okay for free to be NULL; that just means that nothing 154 * special needs to be done to free the buffer. That's useful 155 * for a static string, for instance.) 156 * 157 * If your class can't take control of an existing buffer, then 158 * your give functions should pass the buffer into the 159 * corresponding "set" method and then immediately free the 160 * buffer. 161 * 162 * Note that for strings, the free function will be called with 163 * a size that *includes* the NUL terminator, even though you 164 * provide a size that does *not*. 165 */ 166 167 int (*set_boolean)(const avro_value_iface_t *iface, 168 void *self, int val); 169 int (*set_bytes)(const avro_value_iface_t *iface, 170 void *self, void *buf, size_t size); 171 int (*give_bytes)(const avro_value_iface_t *iface, 172 void *self, avro_wrapped_buffer_t *buf); 173 int (*set_double)(const avro_value_iface_t *iface, 174 void *self, double val); 175 int (*set_float)(const avro_value_iface_t *iface, 176 void *self, float val); 177 int (*set_int)(const avro_value_iface_t *iface, 178 void *self, int32_t val); 179 int (*set_long)(const avro_value_iface_t *iface, 180 void *self, int64_t val); 181 int (*set_null)(const avro_value_iface_t *iface, void *self); 182 /* The input must be NUL-terminated */ 183 int (*set_string)(const avro_value_iface_t *iface, 184 void *self, const char *str); 185 /* and size must INCLUDE the NUL terminator */ 186 int (*set_string_len)(const avro_value_iface_t *iface, 187 void *self, const char *str, size_t size); 188 int (*give_string_len)(const avro_value_iface_t *iface, 189 void *self, avro_wrapped_buffer_t *buf); 190 191 int (*set_enum)(const avro_value_iface_t *iface, 192 void *self, int val); 193 int (*set_fixed)(const avro_value_iface_t *iface, 194 void *self, void *buf, size_t size); 195 int (*give_fixed)(const avro_value_iface_t *iface, 196 void *self, avro_wrapped_buffer_t *buf); 197 198 /*------------------------------------------------------------- 199 * Compound value getters 200 */ 201 202 /* Number of elements in array/map, or the number of fields in a 203 * record. */ 204 int (*get_size)(const avro_value_iface_t *iface, 205 const void *self, size_t *size); 206 207 /* 208 * For arrays and maps, returns the element with the given 209 * index. (For maps, the "index" is based on the order that the 210 * keys were added to the map.) For records, returns the field 211 * with that index in the schema. 212 * 213 * For maps and records, the name parameter (if given) will be 214 * filled in with the key or field name of the returned value. 215 * For arrays, the name parameter will always be ignored. 216 */ 217 int (*get_by_index)(const avro_value_iface_t *iface, 218 const void *self, size_t index, 219 avro_value_t *child, const char **name); 220 221 /* 222 * For maps, returns the element with the given key. For 223 * records, returns the element with the given field name. If 224 * index is given, it will be filled in with the numeric index 225 * of the returned value. 226 */ 227 int (*get_by_name)(const avro_value_iface_t *iface, 228 const void *self, const char *name, 229 avro_value_t *child, size_t *index); 230 231 /* Discriminant of current union value */ 232 int (*get_discriminant)(const avro_value_iface_t *iface, 233 const void *self, int *out); 234 /* Current union value */ 235 int (*get_current_branch)(const avro_value_iface_t *iface, 236 const void *self, avro_value_t *branch); 237 238 /*------------------------------------------------------------- 239 * Compound value setters 240 */ 241 242 /* 243 * For all of these, the value class should know which class to 244 * use for its children. 245 */ 246 247 /* Creates a new array element. */ 248 int (*append)(const avro_value_iface_t *iface, 249 void *self, avro_value_t *child_out, size_t *new_index); 250 251 /* Creates a new map element, or returns an existing one. */ 252 int (*add)(const avro_value_iface_t *iface, 253 void *self, const char *key, 254 avro_value_t *child, size_t *index, int *is_new); 255 256 /* Select a union branch. */ 257 int (*set_branch)(const avro_value_iface_t *iface, 258 void *self, int discriminant, 259 avro_value_t *branch); 260 }; 261 262 263 /** 264 * Increments the reference count of a value instance. Normally you 265 * don't need to call this directly; you'll have a reference whenever 266 * you create the value, and @ref avro_value_copy and @ref 267 * avro_value_move update the reference counts correctly for you. 268 */ 269 270 void 271 avro_value_incref(avro_value_t *value); 272 273 /** 274 * Decremenets the reference count of a value instance, freeing it if 275 * its reference count drops to 0. 276 */ 277 278 void 279 avro_value_decref(avro_value_t *value); 280 281 /** 282 * Copies a reference to a value. This does not copy any of the data 283 * in the value; you get two avro_value_t references that point at the 284 * same underlying value instance. 285 */ 286 287 void 288 avro_value_copy_ref(avro_value_t *dest, const avro_value_t *src); 289 290 /** 291 * Moves a reference to a value. This does not copy any of the data in 292 * the value. The @ref src value is invalidated by this function; its 293 * equivalent to the following: 294 * 295 * <code> 296 * avro_value_copy_ref(dest, src); 297 * avro_value_decref(src); 298 * </code> 299 */ 300 301 void 302 avro_value_move_ref(avro_value_t *dest, avro_value_t *src); 303 304 /** 305 * Compares two values for equality. The two values don't need to have 306 * the same implementation of the value interface, but they do need to 307 * represent Avro values of the same schema. This function ensures that 308 * the schemas match; if you want to skip this check, use 309 * avro_value_equal_fast. 310 */ 311 312 int 313 avro_value_equal(avro_value_t *val1, avro_value_t *val2); 314 315 /** 316 * Compares two values for equality. The two values don't need to have 317 * the same implementation of the value interface, but they do need to 318 * represent Avro values of the same schema. This function assumes that 319 * the schemas match; if you can't guarantee this, you should use 320 * avro_value_equal, which compares the schemas before comparing the 321 * values. 322 */ 323 324 int 325 avro_value_equal_fast(avro_value_t *val1, avro_value_t *val2); 326 327 /** 328 * Compares two values using the sort order defined in the Avro 329 * specification. The two values don't need to have the same 330 * implementation of the value interface, but they do need to represent 331 * Avro values of the same schema. This function ensures that the 332 * schemas match; if you want to skip this check, use 333 * avro_value_cmp_fast. 334 */ 335 336 int 337 avro_value_cmp(avro_value_t *val1, avro_value_t *val2); 338 339 /** 340 * Compares two values using the sort order defined in the Avro 341 * specification. The two values don't need to have the same 342 * implementation of the value interface, but they do need to represent 343 * Avro values of the same schema. This function assumes that the 344 * schemas match; if you can't guarantee this, you should use 345 * avro_value_cmp, which compares the schemas before comparing the 346 * values. 347 */ 348 349 int 350 avro_value_cmp_fast(avro_value_t *val1, avro_value_t *val2); 351 352 353 354 /** 355 * Copies the contents of src into dest. The two values don't need to 356 * have the same implementation of the value interface, but they do need 357 * to represent Avro values of the same schema. This function ensures 358 * that the schemas match; if you want to skip this check, use 359 * avro_value_copy_fast. 360 */ 361 362 int 363 avro_value_copy(avro_value_t *dest, const avro_value_t *src); 364 365 /** 366 * Copies the contents of src into dest. The two values don't need to 367 * have the same implementation of the value interface, but they do need 368 * to represent Avro values of the same schema. This function assumes 369 * that the schemas match; if you can't guarantee this, you should use 370 * avro_value_copy, which compares the schemas before comparing the 371 * values. 372 */ 373 374 int 375 avro_value_copy_fast(avro_value_t *dest, const avro_value_t *src); 376 377 /** 378 * Returns a hash value for a given Avro value. 379 */ 380 381 uint32_t 382 avro_value_hash(avro_value_t *value); 383 384 /* 385 * Returns a string containing the JSON encoding of an Avro value. You 386 * must free this string when you're done with it, using the standard 387 * free() function. (*Not* using the custom Avro allocator.) 388 */ 389 390 int 391 avro_value_to_json(const avro_value_t *value, 392 int one_line, char **json_str); 393 394 395 /** 396 * A helper macro for calling a given method in a value instance, if 397 * it's present. If the value's class doesn't implement the given 398 * method, we return dflt. You usually won't call this directly; it's 399 * just here to implement the macros below. 400 */ 401 402 #define avro_value_call0(value, method, dflt) \ 403 ((value)->iface->method == NULL? (dflt): \ 404 (value)->iface->method((value)->iface, (value)->self)) 405 406 #define avro_value_call(value, method, dflt, ...) \ 407 ((value)->iface->method == NULL? (dflt): \ 408 (value)->iface->method((value)->iface, (value)->self, __VA_ARGS__)) 409 410 411 #define avro_value_iface_incref(cls) \ 412 ((cls)->incref_iface == NULL? (cls): (cls)->incref_iface((cls))) 413 #define avro_value_iface_decref(cls) \ 414 ((cls)->decref_iface == NULL? (void) 0: (cls)->decref_iface((cls))) 415 416 #define avro_value_reset(value) \ 417 avro_value_call0(value, reset, EINVAL) 418 #define avro_value_get_type(value) \ 419 avro_value_call0(value, get_type, (avro_type_t) -1) 420 #define avro_value_get_schema(value) \ 421 avro_value_call0(value, get_schema, NULL) 422 423 #define avro_value_get_boolean(value, out) \ 424 avro_value_call(value, get_boolean, EINVAL, out) 425 #define avro_value_get_bytes(value, buf, size) \ 426 avro_value_call(value, get_bytes, EINVAL, buf, size) 427 #define avro_value_grab_bytes(value, dest) \ 428 avro_value_call(value, grab_bytes, EINVAL, dest) 429 #define avro_value_get_double(value, out) \ 430 avro_value_call(value, get_double, EINVAL, out) 431 #define avro_value_get_float(value, out) \ 432 avro_value_call(value, get_float, EINVAL, out) 433 #define avro_value_get_int(value, out) \ 434 avro_value_call(value, get_int, EINVAL, out) 435 #define avro_value_get_long(value, out) \ 436 avro_value_call(value, get_long, EINVAL, out) 437 #define avro_value_get_null(value) \ 438 avro_value_call0(value, get_null, EINVAL) 439 #define avro_value_get_string(value, str, size) \ 440 avro_value_call(value, get_string, EINVAL, str, size) 441 #define avro_value_grab_string(value, dest) \ 442 avro_value_call(value, grab_string, EINVAL, dest) 443 #define avro_value_get_enum(value, out) \ 444 avro_value_call(value, get_enum, EINVAL, out) 445 #define avro_value_get_fixed(value, buf, size) \ 446 avro_value_call(value, get_fixed, EINVAL, buf, size) 447 #define avro_value_grab_fixed(value, dest) \ 448 avro_value_call(value, grab_fixed, EINVAL, dest) 449 450 #define avro_value_set_boolean(value, val) \ 451 avro_value_call(value, set_boolean, EINVAL, val) 452 #define avro_value_set_bytes(value, buf, size) \ 453 avro_value_call(value, set_bytes, EINVAL, buf, size) 454 #define avro_value_give_bytes(value, buf) \ 455 avro_value_call(value, give_bytes, EINVAL, buf) 456 #define avro_value_set_double(value, val) \ 457 avro_value_call(value, set_double, EINVAL, val) 458 #define avro_value_set_float(value, val) \ 459 avro_value_call(value, set_float, EINVAL, val) 460 #define avro_value_set_int(value, val) \ 461 avro_value_call(value, set_int, EINVAL, val) 462 #define avro_value_set_long(value, val) \ 463 avro_value_call(value, set_long, EINVAL, val) 464 #define avro_value_set_null(value) \ 465 avro_value_call0(value, set_null, EINVAL) 466 #define avro_value_set_string(value, str) \ 467 avro_value_call(value, set_string, EINVAL, str) 468 #define avro_value_set_string_len(value, str, size) \ 469 avro_value_call(value, set_string_len, EINVAL, str, size) 470 #define avro_value_give_string_len(value, buf) \ 471 avro_value_call(value, give_string_len, EINVAL, buf) 472 #define avro_value_set_enum(value, val) \ 473 avro_value_call(value, set_enum, EINVAL, val) 474 #define avro_value_set_fixed(value, buf, size) \ 475 avro_value_call(value, set_fixed, EINVAL, buf, size) 476 #define avro_value_give_fixed(value, buf) \ 477 avro_value_call(value, give_fixed, EINVAL, buf) 478 479 #define avro_value_get_size(value, size) \ 480 avro_value_call(value, get_size, EINVAL, size) 481 #define avro_value_get_by_index(value, idx, child, name) \ 482 avro_value_call(value, get_by_index, EINVAL, idx, child, name) 483 #define avro_value_get_by_name(value, name, child, index) \ 484 avro_value_call(value, get_by_name, EINVAL, name, child, index) 485 #define avro_value_get_discriminant(value, out) \ 486 avro_value_call(value, get_discriminant, EINVAL, out) 487 #define avro_value_get_current_branch(value, branch) \ 488 avro_value_call(value, get_current_branch, EINVAL, branch) 489 490 #define avro_value_append(value, child, new_index) \ 491 avro_value_call(value, append, EINVAL, child, new_index) 492 #define avro_value_add(value, key, child, index, is_new) \ 493 avro_value_call(value, add, EINVAL, key, child, index, is_new) 494 #define avro_value_set_branch(value, discriminant, branch) \ 495 avro_value_call(value, set_branch, EINVAL, discriminant, branch) 496 497 CLOSE_EXTERN 498 #endif 499