include/json-c/json_patch.h

0001 /*
0002  * Copyright (c) 2021 Alexadru Ardelean.
0003  *
0004  * This is free software; you can redistribute it and/or modify
0005  * it under the terms of the MIT license. See COPYING for details.
0006  *
0007  */
0008
0009 /**
0010  * @file
0011  * @brief JSON Patch (RFC 6902) implementation for manipulating JSON objects
0012  */
0013 #ifndef _json_patch_h_
0014 #define _json_patch_h_
0015
0016 #include "json_pointer.h"
0017
0018 #ifdef __cplusplus
0019 extern "C" {
0020 #endif
0021
0022 /**
0023  * Details of an error that occurred during json_patch_apply()
0024  */
0025 struct json_patch_error {
0026     /**
0027      * An errno value indicating what kind of error occurred.
0028      * Possible values include:
0029      * - ENOENT - A path referenced in the operation does not exist.
0030      * - EINVAL - An invalid operation or with invalid path was attempted
0031      * - ENOMEM - Unable to allocate memory
0032      * - EFAULT - Invalid arguments were passed to json_patch_apply()
0033      *             (i.e. a C API error, vs. a data error like EINVAL)
0034      */
0035     int errno_code;
0036
0037     /**
0038      * The index into the patch array of the operation that failed,
0039      * or SIZE_T_MAX for overall errors.
0040      */
0041     size_t patch_failure_idx;
0042
0043     /**
0044      * A human readable error message.
0045      * Allocated from static storage, does not need to be freed.
0046      */
0047     const char *errmsg;
0048 };
0049
0050 /**
0051  * Apply the JSON patch to the base object.
0052  * The patch object must be formatted as per RFC 6902, i.e.
0053  * a json_type_array containing patch operations.
0054  * If the patch is not correctly formatted, an error will
0055  * be returned.
0056  *
0057  * The json_object at *base will be modified in place.
0058  * Exactly one of *base or copy_from must be non-NULL.
0059  * If *base is NULL, a new copy of copy_from will allocated and populated
0060  * using json_object_deep_copy().  In this case json_object_put() _must_ be
0061  * used to free *base even if the overall patching operation fails.
0062  *
0063  * If anything fails during patching a negative value will be returned,
0064  * and patch_error (if non-NULL) will be populated with error details.
0065  *
0066  * @param base a pointer to the JSON object which to patch
0067  * @param patch the JSON object that describes the patch to be applied
0068  * @param copy_from a JSON object to copy to *base
0069  * @param patch_error optional, details about errors
0070  *
0071  * @return negative if an error (or not found), or 0 if patch completely applied
0072  */
0073 JSON_EXPORT int json_patch_apply(struct json_object *copy_from, struct json_object *patch,
0074                                  struct json_object **base, struct json_patch_error *patch_error);
0075
0076 #ifdef __cplusplus
0077 }
0078 #endif
0079
0080 #endif