include/instance.h

   1 /*
   2  * Copyright 2013  Samsung Electronics Co., Ltd
   3  *
   4  * Licensed under the Flora License, Version 1.1 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://floralicense.org/license/
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /*!
  18  * \note
  19  * An instance has three states.
  20  * ACTIVATED, DEACTIVATED, DESTROYED
  21  *
  22  * When the master is launched and someone requires to create this instance,
  23  * The master just allocate a heap for new instance.
  24  * We defined this as "DEACTIVATED" state.
  25  *
  26  * After master successfully allocate heap for an instance,
  27  * It will send a load request to a specified slave
  28  * (The slave will be specified when a package informaion is
  29  * prepared via configuration file of each livebox packages.)
  30  * We defined this as "REQUEST_TO_ACTIVATE" state.
  31  *
  32  * After the slave create a new instance, it will sends back
  33  * "created" event to the master.
  34  * Then the master will change the state of the instance to
  35  * "ACTIVATED".
  36  *
  37  * Sometimes, slaves can meet some unexpected problems then
  38  * it will tries to clear all problems and tries to keep them in safe env.
  39  * To do this, master or slave can be terminated.
  40  * In this case, the master has to find the fault module(crashed livebox)
  41  * and prevent it from loading at the slave.
  42  * And it will send requests for re-creating all other normal liveboxes.
  43  * We defined this as "REQUEST_TO_REACTIVATE".
  44  *
  45  * After slave is launched again(recovered from fault situation), it will
  46  * receives "re-create" event from the master, then it will create all
  47  * instances of requested liveboxes.
  48  *
  49  * When the master receives "created" event from the slaves,
  50  * It will change the instance's state to "ACTIVATED"
  51  * But now, the master will not send "created" event to the clients.
  52  *
  53  * Because the clients don't want to know the re-created liveboxes.
  54  * They just want to know about fault liveboxes to display deactivated
  55  * message.
  56  *
  57  * Sometimes the master can send requests to the slave to unload instances.
  58  * We defined this as "REQUEST_TO_DEACTIVATE".
  59  *
  60  * After the slave successfully destroy instances,
  61  * The master will change the instance's state to "DEACTIVATED"
  62  * It is same state with the first time when it is created in the master.
  63  *
  64  * Sometimes, the instances can be deleted permanently from the master and slave.
  65  * We called this "destorying an instance".
  66  * So we defined its states as "DESTROYED".
  67  * It can make confusing us, the "DESTROYED" means like the instance is already deleted from the
  68  * heap,.
  69  * Yes, it is right. But the instance cannot be deleted directly.
  70  * Because some callbacks still reference it to complete its job.
  71  * So the instance needs to keep this DESTROYED state for a while
  72  * until all callbacks are done for their remained jobs.
  73  *
  74  * To unload the instance from the slave,
  75  * The master should send a request to the slave,
  76  * And the master should keep the instance until it receives "deleted" event from the slave.
  77  * We defined this state as "REQUEST_TO_DESTROY".
  78  *
  79  * After master receives "deleted" event from the slave,
  80  * It will change the state of an master to "DESTROYED"
  81  *
  82  * There is one more event to change the state of an instance to "DESTROYED".
  83  * In case of system created livebox, it could be destroyed itself.
  84  * So the slave will send "deleted" event to the master directly.
  85  * Even if the master doesn't requests to delete it.
  86  *
  87  * In this case, the master will change the state of an instance to
  88  * "DESTROYED" state. but it will wait to delete it from the heap until
  89  * reference count of an instance reaches to ZERO.
  90  */
  91
  92 enum instance_event {
  93         INSTANCE_EVENT_DESTROY,
  94         INSTNACE_EVENT_UNKNOWN
  95 };
  96
  97 enum instance_destroy_type {
  98         INSTANCE_DESTROY_DEFAULT = 0x00,
  99         INSTANCE_DESTROY_UPGRADE = 0x01,
 100         INSTANCE_DESTROY_UNINSTALL = 0x02,
 101         INSTANCE_DESTROY_TERMINATE = 0x03,
 102         INSTANCE_DESTROY_FAULT = 0x04,
 103         INSTANCE_DESTROY_TEMPORARY = 0x05,
 104         INSTANCE_DESTROY_UNKNOWN = 0x06
 105 };
 106
 107 enum instance_state {
 108         INST_INIT = 0x0, /*!< Only keeps in the master */
 109
 110         /*!
 111          */
 112         INST_ACTIVATED, /*!< This instance is loaded to the slave */
 113         INST_REQUEST_TO_ACTIVATE, /*!< Sent a request to a slave to load this */
 114         INST_REQUEST_TO_REACTIVATE, /*!< Sent a request to a slave to load this without "created" event for clients(viewer) */
 115
 116         /*!
 117          */
 118         INST_DESTROYED, /*!< Instance is unloaded and also it requires to be deleted from the master */
 119         INST_REQUEST_TO_DESTROY /*!< Sent a request to a slave, when the master receives deleted event, the master will delete this */
 120 };
 121
 122 enum livebox_visible_state { /*!< Must be sync'd with livebox-viewer */
 123         LB_SHOW = 0x00, /*!< Livebox is showed. Default state */
 124         LB_HIDE = 0x01, /*!< Livebox is hide, with no update event, but keep update timer */
 125
 126         LB_HIDE_WITH_PAUSE = 0x02, /*!< Livebix is hide, it needs to be paused (with freezed update timer) */
 127
 128         LB_VISIBLE_ERROR = 0xFFFFFFFF /* To enlarge the size of this enumeration type */
 129 };
 130
 131 #define IS_PD   1
 132 #define IS_LB   0
 133
 134 struct inst_info;
 135 struct pkg_info;
 136 struct script_handle;
 137 struct client_node;
 138
 139 extern struct inst_info *instance_create(struct client_node *client, double timestamp, const char *pkgname, const char *content, const char *cluster, const char *category, double period, int width, int height);
 140 extern int instance_destroy(struct inst_info *inst, enum instance_destroy_type type);
 141 extern int instance_reload(struct inst_info *inst, enum instance_destroy_type type);
 142
 143 extern struct inst_info * instance_ref(struct inst_info *inst);
 144 extern struct inst_info * instance_unref(struct inst_info *inst);
 145
 146 extern int instance_state_reset(struct inst_info *inst);
 147 extern int instance_destroyed(struct inst_info *inst, int reason);
 148
 149 extern int instance_reactivate(struct inst_info *inst);
 150 extern int instance_activate(struct inst_info *inst);
 151
 152 extern int instance_recover_state(struct inst_info *inst);
 153 extern int instance_need_slave(struct inst_info *inst);
 154
 155 extern void instance_set_lb_info(struct inst_info *inst, double priority, const char *content, const char *title);
 156 extern void instance_set_lb_size(struct inst_info *inst, int w, int h);
 157 extern void instance_set_pd_size(struct inst_info *inst, int w, int h);
 158 extern void instance_set_alt_info(struct inst_info *inst, const char *icon, const char *name);
 159
 160 extern int instance_set_pinup(struct inst_info *inst, int pinup);
 161 extern int instance_resize(struct inst_info *inst, int w, int h);
 162 extern int instance_hold_scroll(struct inst_info *inst, int seize);
 163 extern int instance_set_period(struct inst_info *inst, double period);
 164 extern int instance_clicked(struct inst_info *inst, const char *event, double timestamp, double x, double y);
 165 extern int instance_text_signal_emit(struct inst_info *inst, const char *emission, const char *source, double sx, double sy, double ex, double ey);
 166 extern int instance_signal_emit(struct inst_info *inst, const char *emission, const char *source, double sx, double sy, double ex, double ey, double x, double y, int down);
 167 extern int instance_change_group(struct inst_info *inst, const char *cluster, const char *category);
 168 extern int instance_set_visible_state(struct inst_info *inst, enum livebox_visible_state state);
 169 extern enum livebox_visible_state instance_visible_state(struct inst_info *inst);
 170 extern int instance_set_update_mode(struct inst_info *inst, int active_update);
 171 extern int instance_active_update(struct inst_info *inst);
 172
 173 /*!
 174  * \note
 175  * getter
 176  */
 177 extern const double const instance_timestamp(const struct inst_info *inst);
 178 extern struct pkg_info * const instance_package(const struct inst_info *inst);
 179 extern struct script_info * const instance_lb_script(const struct inst_info *inst);
 180 extern struct script_info * const instance_pd_script(const struct inst_info *inst);
 181 extern struct buffer_info * const instance_pd_buffer(const struct inst_info *inst);
 182 extern struct buffer_info * const instance_lb_buffer(const struct inst_info *inst);
 183 extern const char * const instance_id(const struct inst_info *inst);
 184 extern const char * const instance_content(const struct inst_info *inst);
 185 extern const char * const instance_category(const struct inst_info *inst);
 186 extern const char * const instance_cluster(const struct inst_info *inst);
 187 extern const char * const instance_title(const struct inst_info *inst);
 188 extern const char * const instance_auto_launch(const struct inst_info *inst);
 189 extern const int const instance_priority(const struct inst_info *inst);
 190 extern const struct client_node * const instance_client(const struct inst_info *inst);
 191 extern const double const instance_period(const struct inst_info *inst);
 192 extern const int const instance_timeout(const struct inst_info *inst);
 193 extern const int const instance_lb_width(const struct inst_info *inst);
 194 extern const int const instance_lb_height(const struct inst_info *inst);
 195 extern const int const instance_pd_width(const struct inst_info *inst);
 196 extern const int const instance_pd_height(const struct inst_info *inst);
 197 extern const enum instance_state const instance_state(const struct inst_info *inst);
 198
 199 /*!
 200  * event
 201  */
 202 extern int instance_unicast_created_event(struct inst_info *inst, struct client_node *client);
 203 extern int instance_unicast_deleted_event(struct inst_info *inst, struct client_node *client, int reason);
 204
 205 extern int instance_create_lb_buffer(struct inst_info *inst, int pixels);
 206 extern int instance_create_pd_buffer(struct inst_info *inst, int pixels);
 207
 208 extern void instance_slave_set_pd_pos(struct inst_info *inst, double x, double y);
 209 extern void instance_slave_get_pd_pos(struct inst_info *inst, double *x, double *y);
 210
 211 extern int instance_slave_open_pd(struct inst_info *inst, struct client_node *client);
 212 extern int instance_slave_close_pd(struct inst_info *inst, struct client_node *client, int reason);
 213
 214 extern int instance_freeze_updator(struct inst_info *inst);
 215 extern int instance_thaw_updator(struct inst_info *inst);
 216
 217 extern int instance_send_access_event(struct inst_info *inst, int status);
 218
 219 extern int instance_lb_update_begin(struct inst_info *inst, double priority, const char *content, const char *title);
 220 extern int instance_lb_update_end(struct inst_info *inst);
 221
 222 extern int instance_pd_update_begin(struct inst_info *inst);
 223 extern int instance_pd_update_end(struct inst_info *inst);
 224
 225 extern void instance_pd_updated(const char *pkgname, const char *id, const char *descfile);
 226 extern void instance_lb_updated_by_instance(struct inst_info *inst, const char *safe_file);
 227 extern void instance_pd_updated_by_instance(struct inst_info *inst, const char *descfile);
 228
 229 /*!
 230  * \note
 231  * if the status is LB_STATUS_ERROR_FAULT (slave is faulted)
 232  * even though the PD is not created, this will forcely send the PD_DESTROYED event to the client.
 233  */
 234 extern int instance_client_pd_destroyed(struct inst_info *inst, int status);
 235 extern int instance_client_pd_created(struct inst_info *inst, int status);
 236
 237 extern int instance_send_access_status(struct inst_info *inst, int status);
 238 extern int instance_send_key_status(struct inst_info *inst, int status);
 239 extern int instance_forward_packet(struct inst_info *inst, struct packet *packet);
 240
 241 extern struct client_node *instance_pd_owner(struct inst_info *inst);
 242
 243 /*!
 244  * Multiple viewer
 245  */
 246 extern int instance_add_client(struct inst_info *inst, struct client_node *client);
 247 extern int instance_del_client(struct inst_info *inst, struct client_node *client);
 248 extern int instance_has_client(struct inst_info *inst, struct client_node *client);
 249 extern void *instance_client_list(struct inst_info *inst);
 250
 251 extern int instance_init(void);
 252 extern int instance_fini(void);
 253
 254 extern int instance_event_callback_add(struct inst_info *inst, enum instance_event type, int (*event_cb)(struct inst_info *inst, void *data), void *data);
 255 extern int instance_event_callback_del(struct inst_info *inst, enum instance_event type, int (*event_cb)(struct inst_info *inst, void *data), void *data);
 256
 257 /*!
 258  */
 259 extern int instance_set_data(struct inst_info *inst, const char *tag, void *data);
 260 extern void *instance_del_data(struct inst_info *inst, const char *tag);
 261 extern void *instance_get_data(struct inst_info *inst, const char *tag);
 262
 263 extern void instance_reload_period(struct inst_info *inst, double period);
 264 /* End of a file */