json_util.h

   1 /*
   2  * $Id: json_util.h,v 1.4 2006/01/30 23:07:57 mclark Exp $
   3  *
   4  * Copyright (c) 2004, 2005 Metaparadigm Pte. Ltd.
   5  * Michael Clark <michael@metaparadigm.com>
   6  *
   7  * This library is free software; you can redistribute it and/or modify
   8  * it under the terms of the MIT license. See COPYING for details.
   9  *
  10  */
  11
  12 /**
  13  * @file
  14  * @brief Miscllaneous utility functions and macros.
  15  */
  16 #ifndef _json_util_h_
  17 #define _json_util_h_
  18
  19 #include "json_object.h"
  20
  21 #ifndef json_min
  22 #define json_min(a, b) ((a) < (b) ? (a) : (b))
  23 #endif
  24
  25 #ifndef json_max
  26 #define json_max(a, b) ((a) > (b) ? (a) : (b))
  27 #endif
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #define JSON_FILE_BUF_SIZE 4096
  34
  35 /* utility functions */
  36 /**
  37  * Read the full contents of the given file, then convert it to a
  38  * json_object using json_tokener_parse().
  39  *
  40  * Returns NULL on failure.  See json_util_get_last_err() for details.
  41  */
  42 JSON_EXPORT struct json_object *json_object_from_file(const char *filename);
  43
  44 /**
  45  * Create a JSON object from already opened file descriptor.
  46  *
  47  * This function can be helpful, when you opened the file already,
  48  * e.g. when you have a temp file.
  49  * Note, that the fd must be readable at the actual position, i.e.
  50  * use lseek(fd, 0, SEEK_SET) before.
  51  *
  52  * The depth argument specifies the maximum object depth to pass to
  53  * json_tokener_new_ex().  When depth == -1, JSON_TOKENER_DEFAULT_DEPTH
  54  * is used instead.
  55  *
  56  * Returns NULL on failure.  See json_util_get_last_err() for details.
  57  */
  58 JSON_EXPORT struct json_object *json_object_from_fd_ex(int fd, int depth);
  59
  60 /**
  61  * Create a JSON object from an already opened file descriptor, using
  62  * the default maximum object depth. (JSON_TOKENER_DEFAULT_DEPTH)
  63  *
  64  * See json_object_from_fd_ex() for details.
  65  */
  66 JSON_EXPORT struct json_object *json_object_from_fd(int fd);
  67
  68 /**
  69  * Equivalent to:
  70  *   json_object_to_file_ext(filename, obj, JSON_C_TO_STRING_PLAIN);
  71  *
  72  * Returns -1 if something fails.  See json_util_get_last_err() for details.
  73  */
  74 JSON_EXPORT int json_object_to_file(const char *filename, struct json_object *obj);
  75
  76 /**
  77  * Open and truncate the given file, creating it if necessary, then
  78  * convert the json_object to a string and write it to the file.
  79  *
  80  * Returns -1 if something fails.  See json_util_get_last_err() for details.
  81  */
  82 JSON_EXPORT int json_object_to_file_ext(const char *filename, struct json_object *obj, int flags);
  83
  84 /**
  85  * Convert the json_object to a string and write it to the file descriptor.
  86  * Handles partial writes and will keep writing until done, or an error
  87  * occurs.
  88  *
  89  * @param fd an open, writable file descriptor to write to
  90  * @param obj the object to serializer and write
  91  * @param flags flags to pass to json_object_to_json_string_ext()
  92  * @return -1 if something fails.  See json_util_get_last_err() for details.
  93  */
  94 JSON_EXPORT int json_object_to_fd(int fd, struct json_object *obj, int flags);
  95
  96 /**
  97  * Return the last error from various json-c functions, including:
  98  * json_object_to_file{,_ext}, json_object_to_fd() or
  99  * json_object_from_{file,fd}, or NULL if there is none.
 100  */
 101 JSON_EXPORT const char *json_util_get_last_err(void);
 102
 103 /* these parsing helpers return zero on success */
 104 JSON_EXPORT int json_parse_int64(const char *buf, int64_t *retval);
 105 JSON_EXPORT int json_parse_uint64(const char *buf, uint64_t *retval);
 106 /**
 107  * @deprecated
 108  */
 109 JSON_EXPORT int json_parse_double(const char *buf, double *retval);
 110
 111 /**
 112  * Return a string describing the type of the object.
 113  * e.g. "int", or "object", etc...
 114  */
 115 JSON_EXPORT const char *json_type_to_name(enum json_type o_type);
 116
 117 #ifdef __cplusplus
 118 }
 119 #endif
 120
 121 #endif