README.md

   1 # agl-compositor
   2
   3 ## Policy
   4
   5 The compositor contains an API useful for defining policy rules.  It contains
   6 the bare minimum and installs, by default, an allow-all kind of engine.
   7
   8 Users wanting  to create their own policy engine should create a specialized
   9 version and use `struct ivi_policy_api` where they can install their own
  10 callbacks.
  11
  12 The default policy found in src/policy-default.c should more than sufficient to
  13 get started. Users can either re-puporse the default policy or create a new one
  14 entirely different, based on their needs.
  15
  16 ### Hooks
  17
  18 These are hooks for allowing the creation, committing and activation of surfaces
  19 (ivi_policy_api::surface_create(), ivi_policy_api::surface_commited(),
  20  ivi_policy_api::surface_activate()).
  21
  22 Another hook, ivi_policy_api::policy_rule_allow_to_add can be used to control
  23 if policy rules (the next type) can be added or not. Finally, we have
  24 ivi_policy_api::policy_rule_try_event() which is executed for each policy
  25 rules currently added, by using the policy API ivi_policy_add().
  26
  27 Users can customize the hooks by using some sort of database to retrieve
  28 the application name to compare against, or incorporate some kind of policy
  29 rule engine.
  30
  31 ### Policy rules
  32
  33 Policy (injection) rules can be added using the policy API framework.  The
  34 protocol allows to define policy rules that should be executed by using the
  35 ivi_policy_api::policy_rule_try_event() callback. These are particularly useful
  36 when handling state changes. The framework API allows adding new states and
  37 events and the default implementation has code for handling events like showing
  38 or hiding the application specified in the policy rule.
  39
  40 #### Default events and states
  41
  42 By default the when creating the policy framework it will add the 'show', and
  43 'hide' events and the 'start', 'stop' and 'reverse' states. An special type,
  44 assigned by default is 'invalid'.
  45
  46 #### State changes
  47
  48 A state change has to be propaged from to the compositor, by using
  49 ivi_policy_state_change(), to signal the compositor the (state) change itself,
  50 in order to apply the policy rules, and implicitly to call the event
  51 handler ivi_policy_api::policy_rule_try_event().