afb-evt: send events in separate job

[src/app-framework-binder.git] / docs / reference-v3 / func-api.md

diff --git a/docs/reference-v3/func-api.md b/docs/reference-v3/func-api.md
index 0ba141d..66dd4c9 100644 (file)
--- a/docs/reference-v3/func-api.md
+++ b/docs/reference-v3/func-api.md
@@ -56,9 +56,9 @@ void afb_api_set_userdata(
 ```C
 /**
  * Check that it requires the API of 'name'.
- * If 'initialized' is not zero it request the API to be
+ * If 'initialized' is not zero it requests the API to be
  * initialized, implying its initialization if needed.
- * 
+ *
  * Calling this function is only allowed within init.
  *
  * A single request allows to require multiple apis.
@@ -199,7 +199,7 @@ void afb_api_verbose(
  * Get the root directory file descriptor. This file descriptor can
  * be used with functions 'openat', 'fstatat', ...
  *
- * CAUTION, manipulate this this descriptor with care, in particular, don't close
+ * CAUTION, manipulate this descriptor with care, in particular, don't close
  * it.
  *
  * This can be used to get the path of the root directory using:
@@ -255,13 +255,31 @@ int afb_api_rootdir_open_locale(
                        const char *locale);
 ```
 
+### afb_api_settings
+
+```C
+/**
+ * Settings of the api.
+ *
+ * Get the settings of the API. The settings are recorded
+ * as a JSON object. The returned object should not be modified.
+ * It MUST NOT be released using json_object_put.
+ *
+ * @param api the api whose settings are required
+ *
+ * @returns The setting object.
+ */
+struct json_object *afb_api_settings(
+                       struct afb_api_x3 *api);
+```
+
 ## Calls and job functions
 
 ### afb_api_call
 
 ```C
 /**
- * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
+ * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
  *
  * For convenience, the function calls 'json_object_put' for 'args'.
@@ -275,6 +293,9 @@ int afb_api_rootdir_open_locale(
  *  4. 'info'    a string handling some info (can be NULL)
  *  5. 'api'     the api
  *
+ * NOTE: For convenience, *json_object_put* is called on 'object' after the
+ * callback returns. So, it is wrong to call *json_object_put* in the callback.
+ *
  * @param api      The api that makes the call
  * @param apiname  The api name of the method to call
  * @param verb     The verb name of the method to call
@@ -305,7 +326,7 @@ void afb_api_call(
 
 ```C
 /**
- * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
+ * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
  * 'result' will receive the response.
  *
  * For convenience, the function calls 'json_object_put' for 'args'.
@@ -407,7 +428,7 @@ int afb_api_queue_job(
  * @param name the event name suffix
  * @param object the object that comes with the event
  *
- * @return the count of clients that received the event.
+ * @return 0 in case of success or -1 in case of error
  */
 int afb_api_broadcast_event(
                        afb_api_t api,
@@ -579,9 +600,9 @@ struct sd_bus *afb_api_get_system_bus(
  * @param info the brief description of the new api (can be NULL)
  * @param noconcurrency zero or not zero whether the new api is reentrant or not
  * @param preinit the pre-initialization function if any (can be NULL)
- * @param closure the closure for the pre-initialization \ref preinit
+ * @param closure the closure for the pre-initialization preinit
  *
- * @return 0 in case of success or -1 on failure with errno set
+ * @return the created api in case of success or NULL on error
  *
  * @see afb_api_delete_api
  */
@@ -862,8 +883,10 @@ of work.
 /**
  * @deprecated try to use @ref afb_api_call instead
  *
- *  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
- * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
+ * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb'
+ * in the name of the binding.
+ * The result of the call is delivered to the 'callback' function
+ * with the 'callback_closure'.
  *
  * For convenience, the function calls 'json_object_put' for 'args'.
  * Thus, in the case where 'args' should remain available after
@@ -906,7 +929,8 @@ void afb_api_call_legacy(
 /**
  * @deprecated try to use @ref afb_api_call_sync instead
  *
- * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
+ * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb'
+ * in the name of the binding.
  * 'result' will receive the response.
  *
  * For convenience, the function calls 'json_object_put' for 'args'.