json_patch.h

   1 /*
   2  * Copyright (c) 2021 Alexadru Ardelean.
   3  *
   4  * This is free software; you can redistribute it and/or modify
   5  * it under the terms of the MIT license. See COPYING for details.
   6  *
   7  */
   8
   9 /**
  10  * @file
  11  * @brief JSON Patch (RFC 6902) implementation for manipulating JSON objects
  12  */
  13 #ifndef _json_patch_h_
  14 #define _json_patch_h_
  15
  16 #include "json_pointer.h"
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /**
  23  * Details of an error that occurred during json_patch_apply()
  24  */
  25 struct json_patch_error {
  26         /**
  27          * An errno value indicating what kind of error occurred.
  28          * Possible values include:
  29          * - ENOENT - A path referenced in the operation does not exist.
  30          * - EINVAL - An invalid operation or with invalid path was attempted
  31          * - ENOMEM - Unable to allocate memory
  32          * - EFAULT - Invalid arguments were passed to json_patch_apply()
  33          *             (i.e. a C API error, vs. a data error like EINVAL)
  34          */
  35         int errno_code;
  36
  37         /**
  38          * The index into the patch array of the operation that failed,
  39          * or SIZE_T_MAX for overall errors.
  40          */
  41         size_t patch_failure_idx;
  42
  43         /**
  44          * A human readable error message.
  45          * Allocated from static storage, does not need to be freed.
  46          */
  47         const char *errmsg;
  48 };
  49
  50 /**
  51  * Apply the JSON patch to the base object.
  52  * The patch object must be formatted as per RFC 6902, i.e.
  53  * a json_type_array containing patch operations.
  54  * If the patch is not correctly formatted, an error will
  55  * be returned.
  56  *
  57  * The json_object at *base will be modified in place.
  58  * Exactly one of *base or copy_from must be non-NULL.
  59  * If *base is NULL, a new copy of copy_from will allocated and populated
  60  * using json_object_deep_copy().  In this case json_object_put() _must_ be
  61  * used to free *base even if the overall patching operation fails.
  62  *
  63  * If anything fails during patching a negative value will be returned,
  64  * and patch_error (if non-NULL) will be populated with error details.
  65  *
  66  * @param base a pointer to the JSON object which to patch
  67  * @param patch the JSON object that describes the patch to be applied
  68  * @param copy_from a JSON object to copy to *base
  69  * @param patch_error optional, details about errors
  70  *
  71  * @return negative if an error (or not found), or 0 if patch completely applied
  72  */
  73 JSON_EXPORT int json_patch_apply(struct json_object *copy_from, struct json_object *patch,
  74                                  struct json_object **base, struct json_patch_error *patch_error);
  75
  76 #ifdef __cplusplus
  77 }
  78 #endif
  79
  80 #endif