Merge pull request #3 from Weining2019/master

add comments for app lib and fix bug of sensor_config_with_attr

core/iwasm/lib/app-libs/base/request.c

@@ -101,7 +101,7 @@ static void transaction_remove(transaction_t *trans)
     }
 }
 
-bool is_event_type(request_t * req)
+static bool is_event_type(request_t * req)
 {
     return req->action == COAP_EVENT;
 }

core/iwasm/lib/app-libs/base/request.h

@@ -24,22 +24,108 @@
 extern "C" {
 #endif
 
-bool is_event_type(request_t * req);
+/**
+ * @typedef request_handler_f
+ *
+ * @brief Define the signature of callback function for API
+ * api_register_resource_handler() to handle request or for API
+ * api_subscribe_event() to handle event.
+ *
+ * @param request pointer of the request to be handled
+ *
+ * @see api_register_resource_handler
+ * @see api_subscribe_event
+ */
+typedef void (*request_handler_f)(request_t *request);
+
+/**
+ * @typedef response_handler_f
+ *
+ * @brief Define the signature of callback function for API
+ * api_send_request() to handle response of a request.
+ *
+ * @param response pointer of the response to be handled
+ * @param user_data user data associated with the request which is set when
+ * calling api_send_request().
+ *
+ * @see api_send_request
+ */
+typedef void (*response_handler_f)(response_t *response, void *user_data);
+
+
+/*
+ *****************
+ * Request APIs
+ *****************
+ */
 
-typedef void (*request_handler_f)(request_t *);
-typedef void (*response_handler_f)(response_t *, void *);
+/**
+ * @brief Register resource.
+ *
+ * @param url url of the resource
+ * @param handler callback function to handle the request to the resource
+ *
+ * @return true if success, false otherwise
+ */
+bool api_register_resource_handler(const char *url, request_handler_f handler);
 
-// Request APIs
-bool api_register_resource_handler(const char *url, request_handler_f);
+/**
+ * @brief Send request asynchronously.
+ *
+ * @param request pointer of the request to be sent
+ * @param response_handler callback function to handle the response
+ * @param user_data user data
+ */
 void api_send_request(request_t * request, response_handler_f response_handler,
         void * user_data);
 
+/**
+ * @brief Send response.
+ *
+ * @param response pointer of the response to be sent
+ *
+ * @par
+ * @code
+ * void res1_handler(request_t *request)
+ * {
+ *     response_t response[1];
+ *     make_response_for_request(request, response);
+ *     set_response(response, DELETED_2_02, 0, NULL, 0);
+ *     api_response_send(response);
+ * }
+ * @endcode
+ */
 void api_response_send(response_t *response);
 
-// event API
+
+/*
+ *****************
+ * Event APIs
+ *****************
+ */
+
+/**
+ * @brief Publish an event.
+ *
+ * @param url url of the event
+ * @param fmt format of the event payload
+ * @param payload payload of the event
+ * @param payload_len length in bytes of the event payload
+ *
+ * @return true if success, false otherwise
+ */
 bool api_publish_event(const char *url, int fmt, void *payload,
         int payload_len);
 
+
+/**
+ * @brief Subscribe an event.
+ *
+ * @param url url of the event
+ * @param handler callback function to handle the event.
+ *
+ * @return true if success, false otherwise
+ */
 bool api_subscribe_event(const char * url, request_handler_f handler);
 
 #ifdef __cplusplus

core/iwasm/lib/app-libs/base/timer.c

@@ -35,7 +35,7 @@ struct user_timer {
 struct user_timer * g_timers = NULL;
 
 user_timer_t api_timer_create(int interval, bool is_period, bool auto_start,
-        void (*on_timer_update)(user_timer_t))
+        on_user_timer_update_f on_timer_update)
 {
 
     int timer_id = wasm_create_timer(interval, is_period, auto_start);

core/iwasm/lib/app-libs/base/timer_wasm_app.h

@@ -23,17 +23,53 @@
 extern "C" {
 #endif
 
-//TODO:
-#define bh_queue_t void
-
 /* board producer define user_timer */
 struct user_timer;
 typedef struct user_timer * user_timer_t;
 
-// Timer APIs
+/**
+ * @typedef on_user_timer_update_f
+ *
+ * @brief Define the signature of callback function for API api_timer_create().
+ *
+ * @param timer the timer
+ *
+ * @see api_timer_create
+ */
+typedef void (*on_user_timer_update_f)(user_timer_t timer);
+
+/*
+ *****************
+ * Timer APIs
+ *****************
+ */
+
+/**
+ * @brief Create timer.
+ *
+ * @param interval timer interval
+ * @param is_period whether the timer is periodic
+ * @param auto_start whether start the timer immediately after created
+ * @param on_timer_update callback function called when timer expired
+ *
+ * @return the timer created if success, NULL otherwise
+ */
 user_timer_t api_timer_create(int interval, bool is_period, bool auto_start,
-        void (*on_user_timer_update)(user_timer_t));
+        on_user_timer_update_f on_timer_update);
+
+/**
+ * @brief Cancel timer.
+ *
+ * @param timer the timer to cancel
+ */
 void api_timer_cancel(user_timer_t timer);
+
+/**
+ * @brief Restart timer.
+ *
+ * @param timer the timer to cancel
+ * @param interval the timer interval
+ */
 void api_timer_restart(user_timer_t timer, int interval);
 
 #ifdef __cplusplus

core/iwasm/lib/app-libs/extension/sensor/sensor.c

@@ -28,7 +28,7 @@ typedef struct _sensor {
 static sensor_t g_sensors = NULL;
 
 sensor_t sensor_open(const char* name, int index,
-        void (*sensor_event_handler)(sensor_t, attr_container_t *, void *),
+        sensor_event_handler_f sensor_event_handler,
         void *user_data)
 {
     uint32 id = wasm_sensor_open(name, index);
@@ -63,12 +63,10 @@ sensor_t sensor_open(const char* name, int index,
 
 bool sensor_config_with_attr_container(sensor_t sensor, attr_container_t *cfg)
 {
-    char * buffer;
-    int len;
+    char *buffer = (char *)cfg;
+    int len = attr_container_get_serialize_length(cfg);
 
-    bool ret = wasm_sensor_config_with_attr_container(sensor->handle, buffer,
-            len);
-    return ret;
+    return wasm_sensor_config_with_attr_container(sensor->handle, buffer, len);
 }
 
 bool sensor_config(sensor_t sensor, int interval, int bit_cfg, int delay)
@@ -79,7 +77,6 @@ bool sensor_config(sensor_t sensor, int interval, int bit_cfg, int delay)
 
 bool sensor_close(sensor_t sensor)
 {
-
     wasm_sensor_close(sensor->handle);
 
     // remove local node
@@ -114,8 +111,6 @@ void on_sensor_event(uint32 sensor_id, char * buffer, int len)
 {
     attr_container_t * sensor_data = (attr_container_t *) buffer;
 
-    // ??? use buffer or the attributs struct?
-
     // lookup the sensor and call the handlers
     sensor_t s = g_sensors;
     sensor_t prev = NULL;

core/iwasm/lib/app-libs/extension/sensor/sensor.h

@@ -23,19 +23,77 @@
 extern "C" {
 #endif
 
-//TODO:
-#define bh_queue_t void
-
 /* board producer define sensor */
 struct _sensor;
 typedef struct _sensor *sensor_t;
 
-// Sensor APIs
-sensor_t sensor_open(const char* name, int index,
-        void (*on_sensor_event)(sensor_t, attr_container_t *, void *),
-        void *user_data);
+/**
+ * @typedef sensor_event_handler_f
+ *
+ * @brief Define the signature of callback function for API
+ * sensor_open() to handle sensor event.
+ *
+ * @param sensor the sensor which the event belong to
+ * @param sensor_event the sensor event
+ * @param user_data user data associated with the sensor which is set when
+ * calling sensor_open().
+ *
+ * @see sensor_open
+ */
+typedef void (*sensor_event_handler_f)(sensor_t sensor,
+                                     attr_container_t *sensor_event,
+                                     void *user_data);
+
+/*
+ *****************
+ * Sensor APIs
+ *****************
+ */
+
+/**
+ * @brief Open sensor.
+ *
+ * @param name sensor name
+ * @param index sensor index
+ * @param handler callback function to handle the sensor event
+ * @param user_data user data
+ *
+ * @return the sensor opened if success, NULL otherwise
+ */
+sensor_t sensor_open(const char* name,
+                     int index,
+                     sensor_event_handler_f handler,
+                     void *user_data);
+
+/**
+ * @brief Configure sensor with interval/bit_cfg/delay values.
+ *
+ * @param sensor the sensor to be configured
+ * @param interval sensor event interval
+ * @param bit_cfg sensor bit config
+ * @param delay sensor delay
+ *
+ * @return true if success, false otherwise
+ */
 bool sensor_config(sensor_t sensor, int interval, int bit_cfg, int delay);
+
+/**
+ * @brief Configure sensor with attr_container_t object.
+ *
+ * @param sensor the sensor to be configured
+ * @param cfg the configuration
+ *
+ * @return true if success, false otherwise
+ */
 bool sensor_config_with_attr_container(sensor_t sensor, attr_container_t *cfg);
+
+/**
+ * @brief Close sensor.
+ *
+ * @param sensor the sensor to be closed
+ *
+ * @return true if success, false otherwise
+ */
 bool sensor_close(sensor_t sensor);
 
 #ifdef __cplusplus

core/iwasm/lib/native-interface/shared_utils.h

@@ -26,6 +26,7 @@ extern "C" {
 #define FMT_ATTR_CONTAINER  99
 #define FMT_APP_RAW_BINARY  98
 
+/* the request structure */
 typedef struct request {
     // message id
     uint32 mid;
@@ -42,11 +43,14 @@ typedef struct request {
     // payload of the request, currently only support attr_container_t type
     void *payload;
 
+    //length in bytes of the payload
     int payload_len;
 
+    //sender of the request
     unsigned long sender;
 } request_t;
 
+/* the response structure */
 typedef struct response {
     // message id
     uint32 mid;
@@ -60,8 +64,10 @@ typedef struct response {
     // payload of the response,
     void *payload;
 
+    //length in bytes of the payload
     int payload_len;
 
+    //receiver of the response
     unsigned long reciever;
 } response_t;
 
@@ -76,11 +82,49 @@ void request_cleaner(request_t *request);
 response_t * clone_response(response_t * response);
 void response_cleaner(response_t * response);
 
+/**
+ * @brief Set fields of response.
+ *
+ * @param response pointer of the response to be set
+ * @param status status of response
+ * @param fmt format of the response payload
+ * @param payload payload of the response
+ * @param payload_len length in bytes of the response payload
+ *
+ * @return pointer to the response
+ *
+ * @warning the response pointer MUST NOT be NULL
+ */
 response_t * set_response(response_t * response, int status, int fmt,
         const char *payload, int payload_len);
+
+/**
+ * @brief Make a response for a request.
+ *
+ * @param request pointer of the request
+ * @param response pointer of the response to be made
+ *
+ * @return pointer to the response
+ *
+ * @warning the request and response pointers MUST NOT be NULL
+ */
 response_t * make_response_for_request(request_t * request,
         response_t * response);
 
+/**
+ * @brief Initialize a request.
+ *
+ * @param request pointer of the request to be initialized
+ * @param url url of the request
+ * @param action action of the request
+ * @param fmt format of the request payload
+ * @param payload payload of the request
+ * @param payload_len length in bytes of the request payload
+ *
+ * @return pointer to the request
+ *
+ * @warning the request pointer MUST NOT be NULL
+ */
 request_t * init_request(request_t * request, char *url, int action, int fmt,
         void *payload, int payload_len);
 

core/iwasm/lib/native/extension/sensor/runtime_sensor.c

@@ -197,8 +197,7 @@ bool wasm_sensor_config_with_attr_container(uint32 sensor, int32 buffer_offset,
     buffer = addr_app_to_native(buffer_offset);
 
     if (buffer != NULL) {
-        attr_container_t * cfg;
-
+        attr_container_t *cfg = (attr_container_t *)buffer;
         sensor_obj_t s = find_sys_sensor_id(sensor);
         if (s == NULL)
             return false;