X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fafb-binding-references.md;h=0e30ffe7c40598fa6ddd38eea8b9d03ce25d6b4e;hb=c8558c8a28966110aa3a356f95d3c60afe32b64a;hp=97ed14a7fba0def988a91e741aba1ef72b403d07;hpb=fee037ca12807a45527b78ca6bcffcdc9a7afabc;p=src%2Fapp-framework-binder.git

diff --git a/docs/afb-binding-references.md b/docs/afb-binding-references.md
index 97ed14a7..0e30ffe7 100644
--- a/docs/afb-binding-references.md
+++ b/docs/afb-binding-references.md
@@ -142,6 +142,8 @@ Broadcasting an event send it to any possible listener.
  * Thus, in the case where 'object' should remain available after
  * the function returns, the function 'json_object_get' shall be used.
  *
+ * Calling this function is only forbidden during preinit.
+ *
  * Returns the count of clients that received the event.
  */
 int afb_daemon_broadcast_event(const char *name, struct json_object *object);
@@ -149,6 +151,8 @@ int afb_daemon_broadcast_event(const char *name, struct json_object *object);
 /*
  * Creates an event of 'name' and returns it.
  *
+ * Calling this function is only forbidden during preinit.
+ *
  * See afb_event_is_valid to check if there is an error.
  */
 struct afb_event afb_daemon_make_event(const char *name);
@@ -228,11 +232,24 @@ bindings at its initialization.
 /*
  * Tells that it requires the API of "name" to exist
  * and if 'initialized' is not null to be initialized.
+ * Calling this function is only allowed within init.
  * Returns 0 in case of success or -1 in case of error.
  */
 int afb_daemon_require_api(const char *name, int initialized)
 ```
 
+This function allows to give a different name to the binding.
+It can be called during pre-init.
+
+```C
+/*
+ * Set the name of the API to 'name'.
+ * Calling this function is only allowed within preinit.
+ * Returns 0 in case of success or -1 in case of error.
+ */
+int afb_daemon_rename_api(const char *name);
+```
+
 ## Functions of class afb_service
 
 The following functions allow services to call verbs of other
@@ -586,6 +603,10 @@ client (with its permissions).
  * For convenience, the function calls 'json_object_put' for 'args'.
  * Thus, in the case where 'args' should remain available after
  * the function returns, the function 'json_object_get' shall be used.
+ *
+ * See also:
+ *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
+ *  - 'afb_req_subcall_sync' the synchronous version
  */
 void afb_req_subcall(
                 struct afb_req req,
@@ -595,6 +616,29 @@ void afb_req_subcall(
                 void (*callback)(void *closure, int status, struct json_object *result),
                 void *closure);
 
+/*
+ * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
+ * This call is made in the context of the request 'req'.
+ * On completion, the function 'callback' is invoked with the
+ * original request 'req', the 'closure' given at call and two
+ * other parameters: 'iserror' and 'result'.
+ * 'status' is 0 on success or negative when on an error reply.
+ * 'result' is the json object of the reply, you must not call json_object_put
+ * on the result.
+ *
+ * For convenience, the function calls 'json_object_put' for 'args'.
+ * Thus, in the case where 'args' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ *
+ * See also:
+ *  - 'afb_req_subcall' that doesn't keep request alive automatically.
+ *  - 'afb_req_subcall_sync' the synchronous version
+ */
+static inline void afb_req_subcall_req(struct afb_req req, const char *api, const char *verb, struct json_object *args, void (*callback)(void *closure, int iserror, struct json_object *result, struct afb_req req), void *closure)
+{
+	req.itf->subcall_req(req.closure, api, verb, args, callback, closure);
+}
+
 /*
  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
  * This call is made in the context of the request 'req'.
@@ -606,6 +650,10 @@ void afb_req_subcall(
  * For convenience, the function calls 'json_object_put' for 'args'.
  * Thus, in the case where 'args' should remain available after
  * the function returns, the function 'json_object_get' shall be used.
+ *
+ * See also:
+ *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
+ *  - 'afb_req_subcall' that doesn't keep request alive automatically.
  */
 int afb_req_subcall_sync(
                 struct afb_req req,
@@ -646,6 +694,39 @@ Instead, you should use the macros:
 void afb_req_verbose(struct afb_req req, int level, const char *file, int line, const char * func, const char *fmt, ...);
 ```
 
+The functions below allow a binding involved in the platform security
+to explicitely check a permission of a client or to get the calling
+application identity.
+
+```C
+/*
+ * Check whether the 'permission' is granted or not to the client
+ * identified by 'req'.
+ *
+ * Returns 1 if the permission is granted or 0 otherwise.
+ */
+int afb_req_has_permission(struct afb_req req, const char *permission);
+
+/*
+ * Get the application identifier of the client application for the
+ * request 'req'.
+ *
+ * Returns the application identifier or NULL when the application
+ * can not be identified.
+ *
+ * The returned value if not NULL must be freed by the caller
+ */
+char *afb_req_get_application_id(struct afb_req req);
+
+/*
+ * Get the user identifier (UID) of the client application for the
+ * request 'req'.
+ *
+ * Returns -1 when the application can not be identified.
+ */
+int afb_req_get_uid(struct afb_req req);
+```
+
 ## Logging macros
 
 The following macros must be used for logging: