Mobile native Wearable native

Event: Managing Events

This tutorial demonstrates how you can publish and subscribe to events.

Warm-up

Become familiar with the Event API basics by learning about:

Subscribing to an Event

To subscribe to a predefined system event or user-defined event:

  1. To use the functions and data types of the Event API (in mobile and wearable applications), include the <app_event.h> header file in your application: 
    #include <app_event.h>
  2. Add an event handler.

    One event can have multiple event handlers, and one handler can be registered multiple times.

    • Add an event handler for a system event: 
      static void 
battery_event_callback(const char *event_name, bundle *event_data, void *user_data) 
{
   // event_name is the event name 
   dlog_print(DLOG_INFO, LOG_TAG, "event_name is [%s]", event_name);

   // event_data is the event data, its type is bundle
   char *battery_level_status = NULL;
   battery_level_status = bundle_get_val(event_data, EVENT_KEY_BATTERY_LEVEL_STATUS);
}

event_handler_h handler;

// Register the event handler
int ret = event_add_event_handler(&handler, SYSTEM_EVENT_BATTERY_LEVEL_STATUS,
                                  (event_cb)battery_event_cb, user_data);
if (ret != EVENT_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "err: [%d]", ret);
    • Add an event handler for a user-defined event:

      When defining an event name for a user event (such as event.org.tizen.senderapp.user_event), the name format is event.{sender appid}.{user-defined name}. The {user-defined name} must:

      • Contain only the ASCII characters "[A-Z][a-z][0-9]_" and not begin with a digit.
      • Not contain the '.' (period) character.
      • Not exceed the maximum name length (127 bytes).
      • Be at least 1 byte in length.
      ret = event_add_event_handler("event.org.tizen.senderapp.user_event",
                              utc_event_cb_with_valid_check,
                              "CUSTOM_EVENT_KEY", &event_handler);

if (ret != EVENT_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "err: [%d]", ret);
  3. When no longer needed, remove the event handler.

    A registered handler can be removed when application is running, and all registered handlers are removed when the application is terminated.

    ret = event_remove_event_handler(handler);
if (ret != EVENT_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "err: [%d]", ret);

Publishing an Event

To publish an event to all listeners:

  1. To use the functions and data types of the Event API (in mobile and wearable applications), include the <app_event.h> header file in your application: 
    #include <app_event.h>
  2. Create the callback for handling the event: 
    static void 
user_event_cb(const char *event_name, bundle *event_data, void *user_data)
{
   dlog_print(DLOG_INFO, LOG_TAG, "user_event_cb : %s \n", event_name);

   return;
}
  3. Register the event handler and create the bundle for handling the event data: 
    int ret = EVENT_ERROR_NONE;
event_handler_h event_handler;
bundle *event_data = NULL;

ret = event_add_event_handler("event.org.tizen.senderapp.user_event",
                              user_event_cb, "CUSTOM_EVENT_KEY", &event_handler);

if (ret != EVENT_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "err: [%d]", ret);

event_data = bundle_create();

ret = bundle_add_str(event_data, user_data_key, user_data);
  4. Use the event_publish_app_event() function to publish the event: 
    ret = event_publish_app_event("event.org.tizen.senderapp.user_event", event_data);

if (ret != EVENT_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "err: [%d]", ret);
  5. When no longer needed, free the bundle: 
    ret = bundle_free(event_data);

Managing Launch-On-Events

To manage a Launch-On-Event:

Note
Only service applications can register and receive Launch-On-Events.
  1. To register an interest in a Launch-On-Event, define the http://tizen.org/appcontrol/operation/launch_on_event operation in the tizen-manifest.xml file. The URI name for the operation represents the event name in the Launch-On-Event format (event://{Event_Name}). 
    <app-control>
   <operation name="http://tizen.org/appcontrol/operation/launch_on_event"/>
   <uri name="event://tizen.system.event.battery_charger_status"/>
</app-control>

    The Launch-On-Event operation cannot be requested using the app_control_send_launch_request() function, unlike other application control operations.

  2. Receive the event: 
    static void 
*app_control(app_control_h app_control, void *data)
{
   char *event_uri = "event://tizen.system.event.battery_charger_status";
   char *operation, char *uri, char *event_value;
   ret = app_control_get_operation(app_control, &operation);

   if (ret == APP_CONTROL_ERROR_NONE && operation &&
       strcmp(operation, APP_CONTROL_OPERATION_LAUNCH_ON_EVENT) == 0) 
   {
      ret = app_control_get_uri(app_control, &uri);
      if (ret == APP_CONTROL_ERROR_NONE && uri) 
      {
         if (strncmp(uri, event_uri, strlen(event_uri) + 1) == 0) 
         {
            ret = app_control_get_extra_data(app_control, "battery_charger_status", &event_value);
            if (ret == APP_CONTROL_ERROR_NONE && event_value) 
            {
               free(event_value);
            }
            // Use event_add_event_handler() for further event subscriptions here
         }
         free(uri);
      }
      free(operation);
   }
}

    The application can get the event name and data in the first app_control_cb() callback, which is called after the application state changes to created.

Go to top