Update copyright dates

[src/app-framework-binder.git] / include / afb / afb-req-x2.h

diff --git a/include/afb/afb-req-x2.h b/include/afb/afb-req-x2.h
index 70ffab8..4d090bb 100644 (file)
--- a/include/afb/afb-req-x2.h
+++ b/include/afb/afb-req-x2.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2016, 2017, 2018 "IoT.bzh"
+ * Copyright (C) 2015-2020 "IoT.bzh"
  * Author: José Bollo <jose.bollo@iot.bzh>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -20,6 +20,9 @@
 #include "afb-req-x2-itf.h"
 #include "afb-api-x3.h"
 
+/** @defgroup AFB_REQ
+ *  @{ */
+
 /**
  * Checks whether the request 'req' is valid or not.
  *
@@ -455,6 +458,8 @@ int afb_req_x2_session_set_LOA(
  * Establishes for the client link identified by 'req' a subscription
  * to the 'event'.
  *
+ * Establishing subscription MUST be called BEFORE replying to the request.
+ *
  * @param req the request
  * @param event the event to subscribe
  *
@@ -473,6 +478,8 @@ int afb_req_x2_subscribe(
  * link identified by 'req'.
  * Returns 0 in case of successful subscription or -1 in case of error.
  *
+ * Revoking subscription MUST be called BEFORE replying to the request.
+ *
  * @param req the request
  * @param event the event to revoke
  *
@@ -559,6 +566,46 @@ int afb_req_x2_subcall_sync_legacy(
        return req->itf->legacy_subcallsync(req, api, verb, args, result);
 }
 
+/**
+ * Send associated to 'req' a message described by 'fmt' and its 'args'
+ * to the journal for the verbosity 'level'.
+ *
+ * 'file', 'line' and 'func' are indicators of position of the code in source files
+ * (see macros __FILE__, __LINE__ and __func__).
+ *
+ * 'level' is defined by syslog standard:
+ *      EMERGENCY         0        System is unusable
+ *      ALERT             1        Action must be taken immediately
+ *      CRITICAL          2        Critical conditions
+ *      ERROR             3        Error conditions
+ *      WARNING           4        Warning conditions
+ *      NOTICE            5        Normal but significant condition
+ *      INFO              6        Informational
+ *      DEBUG             7        Debug-level messages
+ *
+ * @param req the request
+ * @param level the level of the message
+ * @param file the source filename that emits the message or NULL
+ * @param line the line number in the source filename that emits the message
+ * @param func the name of the function that emits the message or NULL
+ * @param fmt the message format as for printf
+ * @param args the arguments to the format 'fmt'
+ *
+ * @see printf
+ * @see afb_req_x2_verbose
+ */
+static inline
+void afb_req_x2_vverbose(
+                       struct afb_req_x2 *req,
+                       int level, const char *file,
+                       int line,
+                       const char * func,
+                       const char *fmt,
+                       va_list args)
+{
+       req->itf->vverbose(req, level, file, line, func, fmt, args);
+}
+
 /**
  * Send associated to 'req' a message described by 'fmt' and following parameters
  * to the journal for the verbosity 'level'.
@@ -582,9 +629,10 @@ int afb_req_x2_subcall_sync_legacy(
  * @param line the line number in the source filename that emits the message
  * @param func the name of the function that emits the message or NULL
  * @param fmt the message format as for printf
- * @param ... the arguments of the printf
+ * @param ... the arguments of the format 'fmt'
  *
  * @see printf
+ * @see afb_req_x2_vverbose
  */
 __attribute__((format(printf, 6, 7)))
 static inline
@@ -598,7 +646,7 @@ void afb_req_x2_verbose(
 {
        va_list args;
        va_start(args, fmt);
-       req->itf->vverbose(req, level, file, line, func, fmt, args);
+       afb_req_x2_vverbose(req, level, file, line, func, fmt, args);
        va_end(args);
 }
 
@@ -695,6 +743,9 @@ struct json_object *afb_req_x2_get_client_info(
  *  4. 'info'    a string handling some info (can be NULL)
  *  5. 'req'     the req
  *
+ * 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 req      The request
  * @param api      The api name of the method to call
  * @param verb     The verb name of the method to call
@@ -756,3 +807,6 @@ int afb_req_x2_subcall_sync(
 {
        return req->itf->subcallsync(req, api, verb, args, flags, object, error, info);
 }
+
+
+/** @} */