10.0.0.21 Git - firmerware/blob - include/0cpm/app.h

   1 /*
   2  * http://devel.0cpm.org/ -- Open source firmware for SIP phones.
   3  *
   4  * Resource contention handlers.
   5  */
   6
   7
   8 #ifndef HEADER_APP
   9 #define HEADER_APP
  10
  11
  12 /* Hardware phones vary wildy in their configurations of buttons, screens and LEDs.
  13  * To handle all phones in the same way would imply that the simplest phone dictated
  14  * the facilities on all others.  Instead, it is more desirable to have the best
  15  * possible phone dictate what facilities are possible.  This is indeed possible by
  16  * exploitation of context sensitivity, generic buttons that can be dynamically
  17  * mapped to a function and of course the menu that is present on virtually all
  18  * phones.
  19  *
  20  * In cases where resources are really scarce, such as on an analog phone attached
  21  * to an ATA or a phone with a one-line display of 7-segment digits, another
  22  * tactic is applied.  Resources then line up according to their priority, which
  23  * is pretty much the same as their level of urgency.  An incoming call counts as
  24  * more urgent than a call being setup, and that in turn outranks a clock.  If
  25  * resources are tight, the resource access priority determines what is shown;
  26  * on more elaborate displays a layering setup may be shown, and so on.  Much of
  27  * this is generic resource contention handling, within constraints that depend
  28  * on the hardware platform.
  29  *
  30  * To make this even more interesting, we desire to do most of the work at
  31  * compile-time, in macros that expand to the best possible approach for a
  32  * given hardware phone.
  33  */
  34
  35
  36 /* The app_level_t type defines the various priority levels at which an end user
  37  * can experience a phone.  Note that this is totally unrelated to realtime
  38  * priorities, even if both are a sort of prioirity level with override.
  39  */
  40 typedef enum {
  41         APP_LEVEL_ZERO,         /* Nothing to do; this is a sleep mode */
  42         APP_LEVEL_BACKGROUNDED, /* Calls in progress, but the user detached from them */
  43         APP_LEVEL_REINVITE,     /* The user is transferring a call, or creating a conference */
  44         APP_LEVEL_DIALING,      /* The user is dialing, is entering the digits of a number */
  45         APP_LEVEL_PHONEBOOK,    /* The user is looking through a phonebook */
  46         APP_LEVEL_CONNECTING,   /* The phone is setting up a connection to another phone */
  47         APP_LEVEL_TALKING,      /* The user is on the phone, interacting with others */
  48         APP_LEVEL_ZRTPCHECK,    /* The user is verifying a ZRTP key hash */
  49         APP_LEVEL_SOFTBUTTON,   /* The user is engaged in a softbutton-initiated dialog */
  50         APP_LEVEL_MENU,         /* The user is looking through a menu */
  51         APP_LEVEL_RINGING,      /* A new call is coming into the system */
  52         APP_LEVEL_COUNT         /* The number of distinguished resource levels */
  53 } app_level_t;
  54
  55
  56
  57 /* Applications exist at each resource level.  Applications are aware
  58  * when they are being overruled by another application, and they
  59  * will make a choice whether to stop or wait for later continuation.
  60  *
  61  * Applications will lay claims on resources, such as keys and (partial)
  62  * display area, or the ability to output sound to the user's handset.
  63  * These claims may cause applications to be put aside, while in other
  64  * cases the claims can co-exist.  The more I/O facilities one has, the
  65  * more power one can deploy, basically.
  66  *
  67  * It is possible for a number of applications to share the same resource
  68  * level.  In that case, the one that prevails is the last one started.
  69  * An application can decide for itself it is will ever resume, or just
  70  * quit as soon as it is suspended (or decide on it later, when resumed).
  71  *
  72  * Resources may be wished or demanded by an application.  If they are
  73  * wished, then the removal of these keys by higher layers will not cause
  74  * suspending the application, like with demanded keys.  If a higher layer
  75  * wishes for resources that are demanded by the lower layer, then the
  76  * higher layer will not be given these resources.  If higher and lower
  77  * layer wish a resource, then the higher layer wins.
  78  */
  79
  80 typedef void (*app_action_t) (void);
  81 typedef void (*app_event_processor_t) (uint16_t);
  82
  83 typedef struct application app_t;
  84 struct application {
  85         app_t *app_stackdown;
  86         app_level_t app_resourcelevel;
  87         struct resource *res_wish;      /* NULL means: No wish for resources */
  88         struct resource *res_demand;    /* NULL means: No demanded resources */
  89
  90         app_action_t app_start;
  91         app_action_t app_stop;
  92         app_action_t app_suspend;       /* NULL means: use app_stop  */
  93         app_action_t app_resume;        /* NULL means: use app_start */
  94
  95         app_event_processor_t app_event;
  96
  97         app_level_t app_level;
  98
  99 };
 100
 101
 102 /* A routine to register an application structure.  This may only be
 103  * called once on an application structure.
 104  */
 105 void app_register (app_t *app);
 106
 107
 108 /* A routine to focus on an application, provided that nothing at a
 109  * higher resource level wins any demanded resources from this one.
 110  * This is used to compete with other applications at the same
 111  * resource level.
 112  */
 113 void app_focus (app_t *app);
 114
 115
 116 // TODO: API?  Unfocus, unregister?  When to start, how long to claim, and so on?
 117
 118
 119
 120
 121 #endif