include/ui-gadget-module.h

   1 /*
   2  *  UI Gadget
   3  *
   4  * Copyright (c) 2000 - 2012 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jayoun Lee <airjany@samsung.com>, Jinwoo Nam <jwoo.nam@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  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 "ui-gadget.h"
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 /**
  48  * UI gadget module operation type
  49  * @see @ref lifecycle_sec
  50  */
  51 struct ug_module_ops {
  52         /** create operation */
  53         void *(*create) (ui_gadget_h ug, enum ug_mode mode, service_h service,
  54                                         void *priv);
  55         /** start operation */
  56         void (*start) (ui_gadget_h ug, service_h service, void *priv);
  57         /** pause operation */
  58         void (*pause) (ui_gadget_h ug, service_h service, void *priv);
  59         /** resume operation */
  60         void (*resume) (ui_gadget_h ug, service_h service, void *priv);
  61         /** destroy operation */
  62         void (*destroy) (ui_gadget_h ug, service_h service, void *priv);
  63         /** message operation */
  64         void (*message) (ui_gadget_h ug, service_h msg, service_h service, void *priv);
  65         /** event operation */
  66         void (*event) (ui_gadget_h ug, enum ug_event event, service_h service,
  67                                 void *priv);
  68         /** key event operation */
  69         void (*key_event) (ui_gadget_h ug, enum ug_key_event event,
  70                                         service_h service, void *priv);
  71         /** destroying operation */
  72         void (*destroying) (ui_gadget_h ug, service_h service, void *priv);
  73         /** reserved operations */
  74         void *reserved[3];
  75
  76         /** private data */
  77         void *priv;
  78
  79         /** option */
  80         enum ug_option opt;
  81 };
  82
  83 /**
  84  * \par Description:
  85  * This function makes a request that caller of the given UI gadget instance destroys the instance.
  86  * It just makes a request, but not destroys UI gadget
  87  *
  88  * \par Purpose:
  89  * This function is used for sending a request that caller of the given UI gadget instance destroys the instance.
  90  *
  91  * \par Typical use case:
  92  * UI gadget developer who want to send a request that caller of the given UI gadget instance destroys the instance could use the function.
  93  *
  94  * \par Method of function operation:
  95  * Destroy callback which is registered by caller with ug_create() is invoked.
  96  *
  97  * \par Context of function:
  98  * This function supposed to be called in the created UI gadget.
  99  *
 100  * @param[in] ug the UI gadget
 101  * @return 0 on success, -1 on error
 102  *
 103  * \pre None
 104  * \post None
 105  * \see None
 106  * \remarks The API just makes a request, but not destroys UI gadget
 107  *
 108  * \par Sample code:
 109  * \code
 110  * #include <ui-gadget-module.h>
 111  * ...
 112  * // send a "destroy me" request
 113  * ug_destroy_me(ug);
 114  * ...
 115  * \endcode
 116  */
 117 int ug_destroy_me(ui_gadget_h ug);
 118
 119 /**
 120  * \par Description:
 121  * This function sends result to caller of the given UI gadget instance.
 122  *
 123  * \par Purpose:
 124  * This function is used for sending result to caller of the given UI gadget instance. The result have to be composed with service handle.
 125  *
 126  * \par Typical use case:
 127  * UI gadget developer who want to send result to caller of the given UI gadget instance could use the function.
 128  *
 129  * \par Method of function operation:
 130  * Result callback which is registered by caller with ug_create() is invoked.
 131  *
 132  * \par Context of function:
 133  * This function supposed to be called in the created UI gadget.
 134  *
 135  * @param[in] ug the UI gadget
 136  * @param[in] result the result, which is service type (see \ref service_PG "Tizen managed api reference guide")
 137  * @return 0 on success, -1 on error
 138  *
 139  * \pre None
 140  * \post None
 141  * \see None
 142  * \remarks After send your message, you have to release it using service_destroy()
 143  *
 144  * \par Sample code:
 145  * \code
 146  * #include <ui-gadget-module.h>
 147  * ...
 148  * // make a result with service
 149  * service_h result;
 150  * service_create(&result);
 151  * service_add_extra_data(result, "Content", "Hello");
 152  *
 153  * // send the result
 154  * ug_send_result(ug, result);
 155  *
 156  * // release the result
 157  * service_destroy(result);
 158  * ...
 159  * \endcode
 160  */
 161 int ug_send_result(ui_gadget_h ug, service_h result);
 162
 163 #ifdef __cplusplus
 164 }
 165 #endif
 166 /**
 167  * @}
 168  */
 169 #endif                          /* __UI_GADGET_MODULE_H__ */