rtp_engine: rtcp_report_to_json can overflow the ssrc integer value
[asterisk/asterisk.git] / include / asterisk / json.h
index a735fd3..227afbb 100644 (file)
@@ -27,7 +27,7 @@
  * \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.
+ * see its docs at http://www.digip.org/jansson/doc/2.11/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
@@ -43,6 +43,8 @@
  * wrap them with json_ref() when passing them to other \c ast_json_*()
  * functions.
  *
+ * \par Example code
+ *
  * \code
  *     // Example of how to use the Asterisk JSON API
  *     static struct ast_json *foo(void) {
 /*!@{*/
 
 /*!
+ * \brief Primarily used to cast when packing to an "I" type.
+ */
+typedef AST_JSON_INT_T ast_json_int_t;
+
+/*!
  * \brief Initialize the JSON library.
  */
 void ast_json_init(void);
@@ -107,6 +114,20 @@ void ast_json_set_alloc_funcs(void *(*malloc_fn)(size_t), void (*free_fn)(void*)
 void ast_json_reset_alloc_funcs(void);
 
 /*!
+ * \brief Asterisk's custom JSON allocator. Exposed for use by unit tests.
+ * \since 12.0.0
+ * \internal
+ */
+void *ast_json_malloc(size_t size);
+
+/*!
+ * \brief Asterisk's custom JSON allocator. Exposed for use by unit tests.
+ * \since 12.0.0
+ * \internal
+ */
+void ast_json_free(void *p);
+
+/*!
  * \struct ast_json
  * \brief Abstract JSON element (object, array, string, int, ...).
  * \since 12.0.0
@@ -172,6 +193,41 @@ const char *ast_json_typename(enum ast_json_type type);
 /*!@{*/
 
 /*!
+ * \brief Check the string of the given length for UTF-8 format.
+ * \since 13.12.0
+ *
+ * \param str String to check.
+ * \param len Length of string to check.
+ *
+ * \retval 0 if not UTF-8 encoded or str is NULL.
+ * \retval 1 if UTF-8 encoded.
+ */
+int ast_json_utf8_check_len(const char *str, size_t len);
+
+/*!
+ * \brief Check the nul terminated string for UTF-8 format.
+ * \since 13.12.0
+ *
+ * \param str String to check.
+ *
+ * \retval 0 if not UTF-8 encoded or str is NULL.
+ * \retval 1 if UTF-8 encoded.
+ */
+int ast_json_utf8_check(const char *str);
+
+/*!
+ * \brief Check str for UTF-8 and replace with an empty string if fails the check.
+ *
+ * \note The convenience macro is normally used with ast_json_pack()
+ * or a function wrapper that calls ast_json_vpack().
+ */
+#define AST_JSON_UTF8_VALIDATE(str) (ast_json_utf8_check(str) ? (str) : "")
+
+/*!@}*/
+
+/*!@{*/
+
+/*!
  * \brief Get the JSON true value.
  * \since 12.0.0
  *
@@ -398,8 +454,8 @@ struct ast_json *ast_json_array_get(const struct ast_json *array, size_t index);
  * \brief Change an element in an array.
  * \since 12.0.0
  *
- * The \a array steals the \a value reference; use ast_json_ref() to safely keep a pointer
- * to it.
+ * \note The \a array steals the \a value reference even if it returns error;
+ * use ast_json_ref() to safely keep a pointer to it.
  *
  * \param array JSON array to modify.
  * \param index Zero-based index into array.
@@ -413,8 +469,8 @@ int ast_json_array_set(struct ast_json *array, size_t index, struct ast_json *va
  * \brief Append to an array.
  * \since 12.0.0
  *
- * The array steals the \a value reference; use ast_json_ref() to safely keep a pointer
- * to it.
+ * \note The \a array steals the \a value reference even if it returns error;
+ * use ast_json_ref() to safely keep a pointer to it.
  *
  * \param array JSON array to modify.
  * \param value New JSON value to store at the end of \a array.
@@ -427,8 +483,8 @@ int ast_json_array_append(struct ast_json *array, struct ast_json *value);
  * \brief Insert into an array.
  * \since 12.0.0
  *
- * The array steals the \a value reference; use ast_json_ref() to safely keep a pointer
- * to it.
+ * \note The \a array steals the \a value reference even if it returns error;
+ * use ast_json_ref() to safely keep a pointer to it.
  *
  * \param array JSON array to modify.
  * \param index Zero-based index into array.
@@ -509,8 +565,8 @@ struct ast_json *ast_json_object_get(struct ast_json *object, const char *key);
  * \brief Set a field in a JSON object.
  * \since 12.0.0
  *
- * The object steals the \a value reference; use ast_json_ref() to safely keep a pointer
- * to it.
+ * \note The object steals the \a value reference even if it returns error;
+ * use ast_json_ref() to safely keep a pointer to it.
  *
  * \param object JSON object to modify.
  * \param key Key of field to set.
@@ -656,8 +712,8 @@ struct ast_json *ast_json_object_iter_value(struct ast_json_iter *iter);
  * \brief Set the value of the field pointed to by an iterator.
  * \since 12.0.0
  *
- * The array steals the value reference; use ast_json_ref() to safely keep a
- * pointer to it.
+ * \note The object steals the \a value reference even if it returns error;
+ * use ast_json_ref() to safely keep a pointer to it.
  *
  * \param object JSON object \a iter was obtained from.
  * \param iter JSON object iterator.
@@ -683,13 +739,23 @@ enum ast_json_encoding_format
        AST_JSON_PRETTY,
 };
 
+/*!
+ * \brief Encode a JSON value to a compact string.
+ * \since 12.0.0
+ *
+ * Returned string must be freed by calling ast_json_free().
+ *
+ * \param root JSON value.
+ * \return String encoding of \a root.
+ * \return \c NULL on error.
+ */
 #define ast_json_dump_string(root) ast_json_dump_string_format(root, AST_JSON_COMPACT)
 
 /*!
  * \brief Encode a JSON value to a string.
  * \since 12.0.0
  *
- * Returned string must be freed by calling ast_free().
+ * Returned string must be freed by calling ast_json_free().
  *
  * \param root JSON value.
  * \param format encoding format type.
@@ -817,7 +883,7 @@ struct ast_json *ast_json_load_new_file(const char *path, struct ast_json_error
  * \brief Helper for creating complex JSON values.
  * \since 12.0.0
  *
- * See original Jansson docs at http://www.digip.org/jansson/doc/2.4/apiref.html#apiref-pack
+ * See original Jansson docs at http://www.digip.org/jansson/doc/2.11/apiref.html#apiref-pack
  * for more details.
  */
 struct ast_json *ast_json_pack(char const *format, ...);
@@ -826,7 +892,7 @@ struct ast_json *ast_json_pack(char const *format, ...);
  * \brief Helper for creating complex JSON values simply.
  * \since 12.0.0
  *
- * See original Jansson docs at http://www.digip.org/jansson/doc/2.4/apiref.html#apiref-pack
+ * See original Jansson docs at http://www.digip.org/jansson/doc/2.11/apiref.html#apiref-pack
  * for more details.
  */
 struct ast_json *ast_json_vpack(char const *format, va_list ap);
@@ -955,6 +1021,49 @@ struct ast_party_id;
  */
 struct ast_json *ast_json_party_id(struct ast_party_id *party);
 
+enum ast_json_to_ast_vars_code {
+       /*! \brief Conversion successful */
+       AST_JSON_TO_AST_VARS_CODE_SUCCESS,
+       /*!
+        * \brief Conversion failed because invalid value type supplied.
+        * \note Only string values allowed.
+        */
+       AST_JSON_TO_AST_VARS_CODE_INVALID_TYPE,
+       /*! \brief Conversion failed because of allocation failure. (Out Of Memory) */
+       AST_JSON_TO_AST_VARS_CODE_OOM,
+};
+
+/*!
+ * \brief Convert a \c ast_json list of key/value pair tuples into a \c ast_variable list
+ * \since 12.5.0
+ *
+ * \param json_variables The JSON blob containing the variable
+ * \param variables An out reference to the variables to populate.
+ *
+ * \code
+ * struct ast_json *json_variables = ast_json_pack("[ { s: s } ]", "foo", "bar");
+ * struct ast_variable *variables = NULL;
+ * int res;
+ *
+ * res = ast_json_to_ast_variables(json_variables, &variables);
+ * \endcode
+ *
+ * \return Conversion enum ast_json_to_ast_vars_code status
+ */
+enum ast_json_to_ast_vars_code ast_json_to_ast_variables(struct ast_json *json_variables, struct ast_variable **variables);
+
+struct varshead;
+
+/*!
+ * \brief Construct a JSON object from a \c ast_var_t list
+ * \since 14.2.0
+ *
+ * \param channelvars The list of \c ast_var_t to represent as JSON
+ *
+ * \return JSON object with variable names as keys and variable values as values
+ */
+struct ast_json *ast_json_channel_vars(struct varshead *channelvars);
+
 /*!@}*/
 
 #endif /* _ASTERISK_JSON_H */