<h3 id="model">Model</h3>
+ <p>
+ The responsibility of the application's "Model" module is to operate directly on the Event API and related data. The additional benefit of this module is the simplification of the API function calling:
+ error checking and message logging is performed here.
+ <br>
+ Some of the functions implemented within the "Model" module were briefly described in the <a href="#app-finit">Application termination</a> section
+ (<span style="font-family: Courier New,Courier,monospace">__model_release_system_events()</span>, <span style="font-family: Courier New,Courier,monospace">__model_release_custom_events()</span>,
+ <span style="font-family: Courier New,Courier,monospace">model_finit()</span>, <span style="font-family: Courier New,Courier,monospace">__model_free_system_event_info()</span>,
+ <span style="font-family: Courier New,Courier,monospace">__model_free_custom_event_info()</span>). Other, the most important functions, are described here.
+ </p>
+
+ <p>
+ Most of the Model functions operate on the <span style="font-family: Courier New,Courier,monospace">system_ev_info_s</span> or
+ <span style="font-family: Courier New,Courier,monospace">custom_ev_info_s</span> structures which represent the system or custom event internally.
+ </p>
+
+ <p>
+ Adding a handler to the specified event is performed by the <span style="font-family: Courier New,Courier,monospace">model_add_<b>#event_type#</b>_event_handler()</span> function, where
+ <span style="font-family: Courier New,Courier,monospace"><b>#event_type#</b></span> stands for <span style="font-family: Courier New,Courier,monospace">system</span>
+ or <span style="font-family: Courier New,Courier,monospace">custom</span>.
+ </p>
+
+<pre class="prettyprint">
+bool model_add_<b>#event_type#</b>_event_handler(<b>#event_type#</b>_ev_info_s *ev_info, event_cb callback, void *user_data)
+{
+ if (!ev_info || !callback) {
+ controller_log(DLOG_ERROR, "Wrong argument provided.");
+ return false;
+ }
+
+ /* Event's API function is called with name stored in the internal data structure.
+ The callback function is attached to the event's handler. */
+ int ret = event_add_event_handler(ev_info->name, callback, user_data, &ev_info->event_h);
+ if (ret != EVENT_ERROR_NONE) {
+ controller_log(DLOG_ERROR, "Function event_add_event_handler() failed with error = %d.", ret);
+ return false;
+ }
+
+ return true;
+}
+</pre>
+
+ <p>
+ Event's handler created with the <span style="font-family: Courier New,Courier,monospace">model_add_<b>#event_type#</b>_event_handler()</span> is released using
+ <span style="font-family: Courier New,Courier,monospace">__model_remove_event_handler()</span> regardless of its
+ <span style="font-family: Courier New,Courier,monospace"><b>#event_type#</b></span>.
+ </p>
+
+<pre class="prettyprint">
+bool __model_remove_event_handler(event_handler_h event_handler)
+{
+ int ret = event_remove_event_handler(event_handler);
+ if (ret != EVENT_ERROR_NONE) {
+ controller_log(DLOG_ERROR, "Function event_remove_event_handler() failed with error = %d.", ret);
+ return false;
+ }
+
+ return true;
+}
+</pre>
+
+ <p>
+ In order to publish a custom event, the <span style="font-family: Courier New,Courier,monospace">model_publish_event()</span> function must be called with event's name passed in the function's
+ argument.
+ </p>
+
+<pre class="prettyprint">
+bool model_publish_event(const char *event_name)
+{
+ static unsigned int custom_ev_counter = 0;
+
+ if (!event_name) {
+ controller_log(DLOG_ERROR, "Wrong argument provided.");
+ return false;
+ }
+
+ /* The bundle object is the carrier of the event's information.
+ It must be created and filled with proper data which describes event's status. */
+ bundle *bundle_ev = bundle_create();
+ if (!bundle_ev) {
+ controller_log(DLOG_ERROR, "Function bundle_create() failed.");
+ return false;
+ }
+
+ /* The custom event's status is created by simple concatenation of the status counter (custom_ev_counter) followed by the "status value" label. */
+ custom_ev_counter++;
+ char status[__STATUS_MSG_BUFF] = {0,};
+ snprintf(status, __STATUS_MSG_BUFF, "status value %u", custom_ev_counter);
+
+ /* The custom event's status string is added to the event's information carrier (bundle object)
+ with predefined key: CUSTOM_EVENT_KEY_STATUS == "custom_event_status". */
+ int ret = bundle_add_str(bundle_ev, CUSTOM_EVENT_KEY_STATUS, status);
+ if (ret != EVENT_ERROR_NONE) {
+ controller_log(DLOG_ERROR, "Function bundle_add_str() failed with error %d.", ret);
+ return false;
+ }
+
+ /* Finally, the event (identified by event_name) is published (broadcasted) with the bundle object previously created. */
+ ret = event_publish_app_event(event_name, bundle_ev);
+ /* Once the event is published, the associated bundle object is not necessary anymore - it must be freed. */
+ bundle_free(bundle_ev);
+
+ if (ret != EVENT_ERROR_NONE) {
+ controller_log(DLOG_ERROR, "Function event_publish_app_event() failed with error %d.", ret);
+ return false;
+ }
+
+ return true;
+}
+</pre>
+
+ <p>
+ The custom event's name must strictly follow the rule defined by the Event's API:
+ <br>
+ <center><span style="font-family: Courier New,Courier,monospace">event.<b>#app_id#</b>.<b>#custom_name#</b></span>,</center>
+ <br>
+ where:
+ <ul>
+ <li><span style="font-family: Courier New,Courier,monospace"><b>#app_id#</b></span> is the identifier of the calling application;</li>
+ <li><span style="font-family: Courier New,Courier,monospace"><b>#custom_name#</b></span> is a custom name assigned by the user/developer.</li>
+ </ul>
+ For this reason, the supporting <span style="font-family: Courier New,Courier,monospace">__model_format_custom_event_name()</span> function is implemented.
+ </p>
+
+<pre class="prettyprint">
+static void __model_format_custom_event_name(const char *custom_name, char **ev_name)
+{
+ /* Naming rule is applied. */
+ int ev_name_len = strlen("event") + strlen(APP_ID) + strlen(custom_name) + 3;
+ *ev_name = (char *)calloc(ev_name_len, sizeof(char));
+ snprintf(*ev_name, ev_name_len, "event.%s.%s", APP_ID, custom_name);
+
+ /* All whitespaces are removed from the <b>#custom_name#</b> and the string is converted to the lower case. */
+ int i;
+ for (i = 0; i < ev_name_len; i++) {
+ (*ev_name)[i] = tolower((*ev_name)[i]);
+
+ if ((*ev_name)[i] == 32)
+ (*ev_name)[i] = '_';
+ }
+}
+
+</pre>
+
+ <p>
+ Finally, the <span style="font-family: Courier New,Courier,monospace">model_get_bundle_str()</span> function is used to obtain event's status from the associated bundle object based on
+ known key <span style="font-family: Courier New,Courier,monospace">CUSTOM_EVENT_KEY_STATUS == "custom_event_status"</span>.
+ </p>
+
+<pre class="prettyprint">
+bool model_get_bundle_str(bundle *bundle_obj, const char *key, char **str)
+{
+ *str = NULL;
+
+ int ret = bundle_get_str(bundle_obj, key, str);
+ if (ret != BUNDLE_ERROR_NONE) {
+ controller_log(DLOG_ERROR, "Function bundle_get_str() failed with error = %d.", ret);
+ return false;
+ }
+
+ return true;
+}
+</pre>
+
+ <p>
+ The remaining functions play supportive roles only, are self-explanatory and do not need to be described here. Only brief information on their role is included below.
+ <ul>
+ <li>
+ <span style="font-family: Courier New,Courier,monospace">model_get_system_events_count()</span> - returns the number of registered system events based on the number of
+ relevant data stored internally.</li>
+ <li>
+ <span style="font-family: Courier New,Courier,monospace">model_get_system_event_info()</span> - returns the system event's information structure stored internally.
+ </li>
+ <li>
+ <span style="font-family: Courier New,Courier,monospace">model_create_custom_event_info()</span> - creates the custom event's information structure and stores it internally.
+ </li>
+ <li>
+ <span style="font-family: Courier New,Courier,monospace">model_assign_event_status()</span> - assigns the status message to the specified event's structure stored internally.
+ </li>
+ <li>
+ <span style="font-family: Courier New,Courier,monospace">model_check_event_exists()</span> - checks whether given event's name is already registered within internal data structure.
+ </li>
+ </ul>
+ </p>
+
+
+
<script type="text/javascript" src="../scripts/jquery.zclip.min.js"></script>
<script type="text/javascript" src="../scripts/showhide.js"></script>
</div></div></div>
projects / sdk / online-doc.git / commitdiff