Improve documentation for include callbacks.
@@ -73,11 +73,13 @@ The callback receives the following parameters:
* ``calling_rule_filename``: the requesting file name (NULL if not a file).
* ``calling_rule_namespace``: namespace (NULL if undefined).
* ``user_data`` pointer is the same you passed to :c:func:`yr_compiler_set_include_callback`.
-It should return the requested file's content as a string. The memory for this
-string should be allocated by the callback function. Once it is safe to free the
-memory used to return the callback's result, the include_free function passed to
-:c:func:`yr_compiler_set_include_callback` will be called. If the memory does
-not need to be freed, NULL can be passed as include_free instead.
+It should return the requested file's content as a null-terminated string. The
+memory for this string should be allocated by the callback function. Once it is
+safe to free the memory used to return the callback's result, the include_free
+function passed to :c:func:`yr_compiler_set_include_callback` will be called.
+If the memory does not need to be freed, NULL can be passed as include_free
+instead. You can completely disable support for includes by setting a NULL
+callback function with :c:func:`yr_compiler_set_include_callback`.
The callback function has the following prototype:
@@ -438,11 +440,14 @@ Functions
.. c:function:: void yr_compiler_set_include_callback(YR_COMPILER* compiler, YR_COMPILER_INCLUDE_CALLBACK_FUNC callback, YR_COMPILER_INCLUDE_FREE_FUNC include_free, void* user_data)
+ .. versionadded:: 3.7.0
+
Set a callback to provide rules from a custom source when ``include``
directive is invoked. The *user_data* pointer is untouched and passed back to
the callback function and to the free function. Once the callback's result
is no longer needed, the include_free function will be called. If the memory
- does not need to be freed, include_free can be set to NULL.
+ does not need to be freed, include_free can be set to NULL. If *callback* is
+ set to ``NULL`` support for include directives is disabled.
.. c:function:: int yr_compiler_add_file(YR_COMPILER* compiler, FILE* file, const char* namespace, const char* file_name)
