include/ui-gadget-module.h

   1 /*
   2  * Copyright (c) 2000 - 2012 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * This file is part of the UI Gadget
   5  * Written by Jayoun Lee <airjany@samsung.com>, Jinwoo Nam <jwoo.nam@samsung.com>
   6  *
   7  * PROPRIETARY/CONFIDENTIAL
   8  *
   9  * This software is the confidential and proprietary information of
  10  * SAMSUNG ELECTRONICS (Confidential Information).
  11  * You shall not disclose such Confidential Information and shall
  12  * use it only in accordance with the terms of the license agreement
  13  * you entered into with SAMSUNG ELECTRONICS.  SAMSUNG make no
  14  * representations or warranties about the suitability
  15  * of the software, either express or implied, including but not
  16  * limited to the implied warranties of merchantability, fitness for a particular purpose, or non-
  17  * infringement. SAMSUNG shall not be liable for any damages suffered by licensee as
  18  * a result of using, modifying or distributing this software or its derivatives.
  19  *
  20  */
  21
  22 #ifndef __UI_GADGET_MODULE_H__
  23 #define __UI_GADGET_MODULE_H__
  24
  25 /**
  26  * @defgroup    UI_Gadget_For_Developer Developer API Reference Guide
  27  * @ingroup     UI_Gadget
  28  * @brief       A module to develop a UI gadget. Callees (UI gadgets) uses this modules and APIs. (callee -> caller)
  29  *
  30  * @section Header To Use Them:
  31  * @code
  32  * #include <ui-gadget-module.h>
  33  * @endcode
  34  */
  35
  36 /**
  37  * @addtogroup UI_Gadget_For_Developer
  38  * @{
  39  */
  40
  41 #include <bundle.h>
  42 #include "ui-gadget.h"
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 /**
  49  * UI gadget module operation type
  50  * @see @ref lifecycle_sec
  51  */
  52 struct ug_module_ops {
  53         /** create operation */
  54         void *(*create) (struct ui_gadget *ug, enum ug_mode mode, bundle *data,
  55                                         void *priv);
  56         /** start operation */
  57         void (*start) (struct ui_gadget *ug, bundle *data, void *priv);
  58         /** pause operation */
  59         void (*pause) (struct ui_gadget *ug, bundle *data, void *priv);
  60         /** resume operation */
  61         void (*resume) (struct ui_gadget *ug, bundle *data, void *priv);
  62         /** destroy operation */
  63         void (*destroy) (struct ui_gadget *ug, bundle *data, void *priv);
  64         /** message operation */
  65         void (*message) (struct ui_gadget *ug, bundle *msg, bundle *data, void *priv);
  66         /** event operation */
  67         void (*event) (struct ui_gadget *ug, enum ug_event event, bundle *data,
  68                                 void *priv);
  69         /** key event operation */
  70         void (*key_event) (struct ui_gadget *ug, enum ug_key_event event,
  71                                         bundle *data, void *priv);
  72         /** destroying operation */
  73         void (*destroying) (struct ui_gadget *ug, bundle *data, void *priv);
  74         /** reserved operations */
  75         void *reserved[3];
  76
  77         /** private data */
  78         void *priv;
  79
  80         /** option */
  81         enum ug_option opt;
  82 };
  83
  84 /**
  85  * \par Description:
  86  * This function makes a request that caller of the given UI gadget instance destroys the instance.
  87  * It just makes a request, but not destroys UI gadget
  88  *
  89  * \par Purpose:
  90  * This function is used for sending a request that caller of the given UI gadget instance destroys the instance.
  91  *
  92  * \par Typical use case:
  93  * UI gadget developer who want to send a request that caller of the given UI gadget instance destroys the instance could use the function.
  94  *
  95  * \par Method of function operation:
  96  * Destroy callback which is registered by caller with ug_create() is invoked.
  97  *
  98  * \par Context of function:
  99  * This function supposed to be called in the created UI gadget.
 100  *
 101  * @param[in] ug the UI gadget
 102  * @return 0 on success, -1 on error
 103  *
 104  * \pre None
 105  * \post None
 106  * \see None
 107  * \remarks The API just makes a request, but not destroys UI gadget
 108  *
 109  * \par Sample code:
 110  * \code
 111  * #include <ui-gadget-module.h>
 112  * ...
 113  * // send a "destroy me" request
 114  * ug_destroy_me(ug);
 115  * ...
 116  * \endcode
 117  */
 118 int ug_destroy_me(struct ui_gadget *ug);
 119
 120 /**
 121  * \par Description:
 122  * This function sends result to caller of the given UI gadget instance.
 123  *
 124  * \par Purpose:
 125  * This function is used for sending result to caller of the given UI gadget instance. The result have to be composed with bundle library.
 126  *
 127  * \par Typical use case:
 128  * UI gadget developer who want to send result to caller of the given UI gadget instance could use the function.
 129  *
 130  * \par Method of function operation:
 131  * Result callback which is registered by caller with ug_create() is invoked.
 132  *
 133  * \par Context of function:
 134  * This function supposed to be called in the created UI gadget.
 135  *
 136  * @param[in] ug the UI gadget
 137  * @param[in] result the result, which is bundle type (see \ref bundle_PG "bundle programming guide")
 138  * @return 0 on success, -1 on error
 139  *
 140  * \pre None
 141  * \post None
 142  * \see None
 143  * \remarks After send your message, you have to release it using bundle_free()
 144  *
 145  * \par Sample code:
 146  * \code
 147  * #include <ui-gadget-module.h>
 148  * ...
 149  * // make a result with bundle
 150  * bundle *b;
 151  * b = bundle_create();
 152  * bundle_add(b, "Content", "Hello");
 153  *
 154  * // send the result
 155  * ug_send_result(ug, b);
 156  *
 157  * // release the result
 158  * bundle_free(b);
 159  * ...
 160  * \endcode
 161  */
 162 int ug_send_result(struct ui_gadget *ug, bundle *result);
 163
 164 #ifdef __cplusplus
 165 }
 166 #endif
 167 /**
 168  * @}
 169  */
 170 #endif                          /* __UI_GADGET_MODULE_H__ */