Event Broadcast and Subscription

The application can broadcast its own events to all listeners who want to listen. The events can either be predefined system events from the platform or user-defined events. Platform modules can broadcast system events whereas UI and service applications broadcast user-defined events.

The main features of the Event API are as follows:

The application can be suspended while in the background, causing a pause in event handling. Since the application cannot receive events in the suspended state, they are all delivered in series after the application exits the suspended state. Following are the two methods to manage this situation and prevent the application from being flooded with events:

  • To handle events in the background without going to a suspended state, declare a background category.
  • To avoid receiving any events that are triggered while the application is suspended, remove the event handler before entering the suspended state and add it back after exiting the suspended state. You can manage the event handler addition and removal in the APP_EVENT_SUSPENDED_STATE_CHANGED event callback, which is triggered each time the application enters and exist the suspended state.

Prerequisites

To enable your application to use the event functionality, follow these steps:

  1. To use the methods and properties of the Tizen.Applications.EventManager.ApplcationManager and Tizen.Applications.EventManager.EventReceiver classes, include the Tizen.Applications.EventManager namespace in your application:

    
                
    C#
    
                
    
                    
    Copy
    
                    
    
                
    
            
    using Tizen.Applications.EventManager

  2. To use Launch-On-Events in your application, 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}):

    
                
    XML
    
                
    
                    
    Copy
    
                    
    
                
    
            
    <app-control>
   <operation name="http://tizen.org/appcontrol/operation/launch_on_event"/>
   <uri name="event://tizen.system.event.battery_charger_status"/>
</app-control>

Publish an event

To publish an event to all receivers, follow these steps:

  1. Create the bundle for publishing the event data:

    
                
    C#
    
                
    
                    
    Copy
    
                    
    
                
    
            
    Bundle bundle = new Bundle();
bundle.AddItem("key", "value");

  2. Use the Publish() method to publish the event:

    
                
    C#
    
                
    
                    
    Copy
    
                    
    
                
    
            
    ApplicationEventManager.Publish("event.org.tizen.example.AppEventTestApp.AppEvent", bundle);

Subscribe to an event

To subscribe to a predefined system event or user-defined event, follow these steps:

  1. 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:

      
                
      C#
      
                
      
                    
      Copy
      
                    
      
                
      
            
      void OnReceived(object sender, EventManagerEventArgs e)
{
    LogUtils.Write(LogUtils.DEBUG, LOG_TAG, "On Received : " + e.Name);
}

/* Register the event handler */
EventReceiver receiver = new EventReceiver(SystemEvents.BatteryChargerStatus.EventName);
receiver.Received += OnReceived;

    • 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 include the following:

      • Contain only the ASCII characters “[A-Z][a-z][0-9]_” and not begin with a digit.
      • Not contain a ‘.’ (period) character.
      • Not exceed the maximum name length (127 bytes).
      • Be at least 1 byte in length.
      
                
      C#
      
                
      
                    
      Copy
      
                    
      
                
      
            
      EventReceiver receiver = new EventReceiver("event.org.tizen.example.AppEventTestApp.AppEvent");
receiver.Received += OnReceived;

  2. Remove the event handler when no longer needed.

    A registered handler can be removed when the application is running. All the registered handlers can be removed when the application is terminated:

    
                
    C#
    
                
    
                    
    Copy
    
                    
    
                
    
            
    receiver.Received -= OnReceived;

Manage Launch-On-Events

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.

Note

Only service applications can register and receive Launch-On-Events.

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

The following table shows the system events that support Launch-On-Event:

Table: System events supporting Launch-On-Event

You can scroll this table.
Name Condition
SystemEvents.BatteryChargerStatus.EventName When the charger state is SystemEvents.BatteryChargerStatus.StatusValueConnected.
SystemEvents.UsbStatus.EventName When the USB state is SystemEvents.UsbStatus.StatusValueConnected.
SystemEvents.EarjackStatus.EventName When the earjack state is SystemEvents.EarjackStatus.StatusValueConnected.
SystemEvents.IncomingMsg.EventName When the SystemEvents.IncomingMsg.TypeKey and SystemEvents.IncomingMsg.IdKey exist.
SystemEvents.WifiState.EventName When the Wi-Fi state is SystemEvents.WifiState.StateValueConnected.

To receive the Launch-On-Event:


                
C#

                

                    
Copy

                    

                

            
void AppControlReplyReceivedCallback(Tizen.Applications.AppControl launchRequest, Tizen.Applications.AppControl replyRequest, AppControlReplyResult result)
{
    string eventUri = "event://" + SystemEvents.BatteryChargerStatus.EventName;
        if (launchRequest.Operation.Equals(SystemEvents.BatteryChargerStatus.EventName))
        {
            if (launchRequest.Uri.Equals(eventUri))
            {
                string batteryValue = launchRequest.ExtraData.Get(SystemEvents.BatteryChargerStatus.StatusKey);
                LogUtils.Write(LogUtils.DEBUG, LOG_TAG, "Status value : " + batteryValue);
            }
        }
}

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

Platform event types

The following list shows the events of modules:

  • capi-system-device

    • battery

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.BatteryChargerStatus.EventName SystemEvents.BatteryChargerStatus.StatusKey - SystemEvents.BatteryChargerStatus.StatusValueDisconnected : Charger is not connected
      - SystemEvents.BatteryChargerStatus.StatusValueConnected: Charger is connected
      - SystemEvents.BatteryChargerStatus.StatusValueCharging: Charging is enabled
      - SystemEvents.BatteryChargerStatus.StatusValueDischarging: Charging is disabled (for example, 100% full state)      		 When the charger has been connected or disconnected, or when the charging state has changed (charging or not charging). If there is an earlier occurrence regarding this event, you receive the event as soon as you register an event handler for this event. You can use this earlier event data as the initial value.
      SystemEvents.BatteryLevelStatus.EventName SystemEvents.BatteryLevelStatus.StatusKey - SystemEvents.BatteryLevelStatus.StatusValueEmpty
      - SystemEvents.BatteryLevelStatus.StatusValueCritical
      - SystemEvents.BatteryLevelStatus.StatusValueLow
      - SystemEvents.BatteryLevelStatus.StatusValueHigh
      - SystemEvents.BatteryLevelStatus.StatusValueFull      		 When the battery level has changed. You can get the current value with the Tizen.System.Battery.Level property.

  • deviced

    • usb

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.UsbStatus.EventName SystemEvents.UsbStatus.StatusKey - SystemEvents.UsbStatus.StatusValueDisconnected: USB cable is not connected
      - SystemEvents.UsbStatus.StatusValueConnected: USB cable is connected, but the service is not available
      - SystemEvents.UsbStatus.StatusValueAvailable: USB service is available (for example, mtp or SDB)      		 When the USB cable has been connected or disconnected, or when the USB service state has changed. N/A

    • earjack

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.EarjackStatus.EventName SystemEvents.EarjackStatus.StatusKey - SystemEvents.EarjackStatus.StatusValueDisconnected: Earjack is not connected
      - SystemEvents.EarjackStatus.StatusValueConnected: Earjack is connected      		 When the earjack connection state has changed. You can get the current value using System.Information.SetCallback with the http://tizen.org/runtimefeature/audiojack.connected key.

    • display

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.DisplayState.EventName SystemEvents.DisplayState.StateKey - SystemEvents.DisplayState.StateValueNormal: Display on, normal brightness
      - SystemEvents.DisplayState.StateValueDim: Display on, dimmed brightness
      - SystemEvents.DisplayState.StateValueOff: Display off      		 When the display state has changed. You can get the current value with the System.Display.State property.

  • systemd

    • system

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.BootCompleted.EventName N/A N/A When the platform has completed booting. You can treat the initial value as false before you receive this event. If the application is already in a boot-completed state before you register an event handler, you receive the event as soon as you register the event handler.
      SystemEvents.SystemShutdown.EventName N/A N/A When the system power off has been started. You can treat the initial value as false before you receive this event. If the application is already in a shutting-down state before you register an event handler, you receive the event as soon as you register the event handler.

  • resourced

    • ram memory

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.LowMemory.EventName SystemEvents.LowMemory.Key - SystemEvents.LowMemory.ValueNormal: Available > 200MB
      - SystemEvents.LowMemory.ValueSoftWarning: 100MB < available <= 200MB
      - SystemEvents.LowMemory.ValueHardWarning: Available <= 100MB
      Note
      The above numbers can vary depending on the total RAM size of the target device.      		 When the size of available memory has changed. If there is an earlier occurrence regarding this event, you receive the event as soon as you register an event handler for this event. You can use this earlier event data as the initial value.

  • network

    • connectivity

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.WifiState.EventName SystemEvents.WifiState.StateKey - SystemEvents.WifiState.StateValueOn: Wi-Fi on
      - SystemEvents.WifiState.StateValueOff: Wi-Fi off
      - SystemEvents.WifiState.StateValueConnected: Wi-Fi connection established      		 When the Wi-Fi state has changed. You can get the current value with the Network.Connection.ConnectionManager.WiFiState property.
      SystemEvents.Btstate.EventName SystemEvents.Btstate.StateKey - SystemEvents.Btstate.StateValueOff: Legacy Bluetooth off
      - SystemEvents.Btstate.StateValueOn: Legacy Bluetooth on      		 When the Bluetooth state has changed. You can get the current value with the Network.Bluetooth.BluetoothAdapter.IsBluetoothEnabled property.
      SystemEvents.Btstate.EventName SystemEvents.Btstate.LeStateKey - SystemEvents.Btstate.LeStateValueOff: LE function off
      - SystemEvents.Btstate.LeStateValueOn: LE function on      		 When Bluetooth LE state has changed. -
      SystemEvents.Btstate.EventName SystemEvents.Btstate.TransferStateKey - SystemEvents.Btstate.TransferStateValueNontransfering: Idle state
      - SystemEvents.Btstate.TransferStateValueTransfering: File is transferring      		 When the file transfer state has changed. -

  • libslp-location

    • location

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.LocatingEnableState.EventName SystemEvents.LocatingEnableState.StateKey - SystemEvents.LocatingEnableState.StateValueDisabled: Location disabled
      - SystemEvents.LocatingEnableState.StateValueEnabled: Location enabled      		 When the location_enable_state has changed, for example, by the user toggling the location setting in the settings menu or quick panel. You can get the current value with the Location.LocatorHelper.IsEnabledType property.
      SystemEvents.GpsEnableState.EventName SystemEvents.GpsEnableState.StateKey - SystemEvents.GpsEnableState.StateValueDisabled: GPS disabled
      - SystemEvents.GpsEnableState.StateValueEnabled: GPS enabled      		 When the gps_enable_state has changed. You can get the current value with the Location.LocatorHelper.IsEnabledType property.
      SystemEvents.NpsEnableState.EventName SystemEvents.NpsEnableState.StateKey - SystemEvents.NpsEnableState.StateValueDisabled: NPS disabled
      - SystemEvents.NpsEnableState.StateValueEnabled: NPS enabled      		 When the NPS setting has changed, for example, by the user toggling the location settings. You can get the current value with the Location.LocatorHelper.IsEnabledType property.

  • msg-service

    • message

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.IncomingMsg.EventName SystemEvents.IncomingMsg.TypeKey - SystemEvents.IncomingMsg.TypeValueSms: SMS-type message
      - SystemEvents.IncomingMsg.TypeValueMms: MMS-type message
      - SystemEvents.IncomingMsg.TypeValuePush: Push-type message
      - SystemEvents.IncomingMsg.TypeValueCb: Cb-type message      		 When an SMS, MMS, push, or CB message has been received. -
      SystemEvents.IncomingMsg.EventName SystemEvents.IncomingMsg.IdKey msg_id: Message ID of the received message (string of the unsigned int type value) - -
      SystemEvents.OutgoingMsg.EventName SystemEvents.OutgoingMsg.TypeKey - SystemEvents.OutgoingMsg.TypeValueSms: SMS-type message
      - SystemEvents.OutgoingMsg.TypeValueMms: MMS-type message      		 When an SMS or MMS message has been sent. -
      SystemEvents.OutgoingMsg.EventName SystemEvents.OutgoingMsg.IdKey msg_id: Message ID of the sent message (string of the unsigned int type value) - -

  • alarm-manager

    • time

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.TimeChanged.EventName N/A N/A When the system time setting has changed. You can get the current value with the Applications.AlarmManager.GetCurrentTime method.

  • setting

    • time

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.TimeZone.EventName SystemEvents.TimeZone.Key The value of this key is the time zone value of the time zone database, for example, “Asia/Seoul”, “America/New_York”. For more information, see the IANA Time Zone Database. When the time zone has changed. You can get the current value with the System.SystemSettings.LocaleTimeZone property.

    • locale

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.HourFormat.EventName SystemEvents.HourFormat.Key - SystemEvents.HourFormat.Value12
      - SystemEvents.HourFormat.Value24      		 When the hour_format has changed, for example, by the user toggling the date and time settings for the 24-hour clock (where OFF stands for the 12-hour clock). You can get the current value with the System.SystemSettings.LocaleTimeFormat24HourEnabled property.
      SystemEvents.LanguageSet.EventName SystemEvents.LanguageSet.Key The value of this key is the full name of the locale, for example, ko_KR.UTF8 for Korean and en_US.UTF8 for American English. For more information, see the Linux locale information. When the language_set has changed. You can get the current value with the System.SystemSettings.LocaleLanguage property.
      SystemEvents.RegionFormat.EventName SystemEvents.RegionFormat.Key The value of this key is the full name of the locale, for example, ko_KR.UTF8 for the Korean region format and en_US.UTF8 for the USA region format. For more information, see the Linux locale information. When the region_format has changed. You can get the current value with the System.SystemSettings.LocaleCountry property.

    • sound

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.SilentMode.EventName SystemEvents.SilentMode.Key - SystemEvents.SilentMode.ValueOn
      - SystemEvents.SilentMode.ValueOff      		 When the ringtone has changed to 0 or another mode. For example, if the call slider has been changed to 0, silent_mode is "on". Otherwise, silent_mode is "off". You can get the current value with the System.SystemSettings.SoundSilentModeEnabled property.

    • vibration

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.VibrationState.EventName SystemEvents.VibrationState.StateKey - SystemEvents.VibrationState.StateValueOn
      - SystemEvents.VibrationState.StateValueOff      		 When the vibration state has changed. You can get the current value using System.Information.SetCallback with the http://tizen.org/runtimefeature/vibration property.

    • screen

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.AutoRotateState.EventName SystemEvents.AutoRotateState.StateKey - SystemEvents.AutoRotateState.StateOn
      - SystemEvents.AutoRotateState.StateOff      		 When the screen autorotate state has changed, for example, by the user toggling the display settings. You can get the current value with the System.SystemSettings.DisplayScreenRotationAutoEnabled property.

    • mobile

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.MobileDataState.EventName SystemEvents.MobileDataState.StateKey - SystemEvents.MobileDataState.StateValueOn
      - SystemEvents.MobileDataState.StateValueOff      		 When the mobile data state has changed, for example, by the user toggling the network settings. You can get the current value with the System.SystemSettings.Data3GNetworkEnabled property.
      SystemEvents.DataRoamingState.EventName SystemEvents.DataRoamingState.StateKey - SystemEvents.DataRoamingState.StateValueOn
      - SystemEvents.DataRoamingState.StateValueOff      		 When the data roaming state has changed, for example, by the user toggling the network settings. You can get the current value using System.Information.SetCallback with the http://tizen.org/runtimefeature/dataroaming key.

    • font

      You can scroll this table.
      Event name Event data key Event data value Condition Notes
      SystemEvents.FontSet.EventName SystemEvents.FontSet.Key The value of this key is the font name of the string type by font-config. When the font has changed. You can get the current value with the System.SystemSettings.FontType property.
  • Dependencies
    • Tizen 5.5 and Higher
Data Control
Next Message Port
Submit your feedback to GitHub