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 wanted 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 creation, committing and activation of surfaces
  19 (and these are 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 in context of policy
  25 rules.
  26
  27 The current, installed hooks, permit all the above, but users can customize
  28 this behaviour by using some sort of database to retrieve the application name
  29 to compare against, or incorporate some kind of policy rule engine.
  30
  31
  32 ### Policy rules
  33
  34 Policy (injection) rules can be added using the agl-shell-policy protocol.  The
  35 protocol allows to define policy rules that should be executed by using the
  36 ivi_policy_api::policy_rule_try_event callback. These are particularly useful
  37 when handling state changes. The protocol supports adding new states and events
  38 and the default implementation has code for handling events like showing or
  39 hiding the application specified in the policy rule. The protocol XML file on
  40 contains a few more details than written here.
  41
  42 ivi_policy_api::policy_rule_try_event callback should be adapted and correlated
  43 with the client shell in case additional events and states are added.
  44
  45 By default the server side implementations adds the 'show', and 'hide' events
  46 and the 'start', 'stop' and 'reverse' states. An special type, assigned by
  47 default is 'invalid'. A state change has to be propaged from the client to the
  48 compositor to signal the compositor the change itself, in order to apply the
  49 policy rules.