diff options
author | David M. Lee <dlee@digium.com> | 2013-05-07 18:12:26 +0000 |
---|---|---|
committer | David M. Lee <dlee@digium.com> | 2013-05-07 18:12:26 +0000 |
commit | 737a45f2f72185ea48e8f1e3d95e93ebc7cdfd50 (patch) | |
tree | 3937d7c83b937831204ca2ac15da35ea86f91572 /include | |
parent | 570d0c3139bf6caaa229b80b4b72980665d04acd (diff) |
Better explained the depths of reference stealing.
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@387803 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'include')
-rw-r--r-- | include/asterisk/json.h | 51 |
1 files changed, 48 insertions, 3 deletions
diff --git a/include/asterisk/json.h b/include/asterisk/json.h index 7b89d8270..8e646584d 100644 --- a/include/asterisk/json.h +++ b/include/asterisk/json.h @@ -24,9 +24,54 @@ * \brief Asterisk JSON abstraction layer. * \since 12.0.0 * - * This is a very thin wrapper around the Jansson API. For more details on it, see its - * docs at http://www.digip.org/jansson/doc/2.4/apiref.html. - + * This is a very thin wrapper around the Jansson API. For more details on it, + * see its docs at http://www.digip.org/jansson/doc/2.4/apiref.html. + * + * Rather than provide the multiple ways of doing things that the Jansson API + * does, the Asterisk wrapper is always reference-stealing, and always NULL + * safe. + * + * And by always, I mean that the reference is stolen even if the function + * fails. This avoids lots of conditional logic, and also avoids having to track + * zillions of local variables when building complex JSON objects. You can + * instead chain \c ast_json_* calls together safely and only worry about + * cleaning up the root object. + * + * In the cases where you have a need to introduce intermediate objects, just + * wrap them with json_ref() when passing them to other \c ast_json_*() + * functions. + * + * \code + * // Example of how to use the Asterisk JSON API + * static struct ast_json *foo(void) { + * RAII_VAR(struct ast_json *, array, NULL, ast_json_unref); + * RAII_VAR(struct ast_json *, obj, NULL, ast_json_unref); + * int i, res; + * + * array = ast_json_array_create(); + * if (!array) { return NULL; } + * + * for (i = 0; i < 10; ++i) { + * // NULL safety and object stealing means calls can + * // be chained together directly. + * res = ast_json_array_append(array, + * ast_json_integer_create(i)); + * if (res != 0) { return NULL; } + * } + * + * obj = ast_json_object_create(); + * if (!obj) { return NULL; } + * + * // If you already have an object reference, ast_json_ref() + * // can be used inline to bump the ref before passing it along + * // to a ref-stealing call + * res = ast_json_object_set(obj, "foo", ast_json_ref(array)); + * if (!res) { return NULL; } + * + * return obj; + * } + * \endcode + * * \author David M. Lee, II <dlee@digium.com> */ |