include/ITapiSat.h

   1 /*
   2  * libslp-tapi
   3  *
   4  * Copyright (c) 2014 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Ja-young Gu <jygu@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  * @file ITapiSat.h
  23  */
  24
  25 /**
  26  * @internal
  27  * @addtogroup CAPI_TELEPHONY_SERVICE_SAT
  28  * @{
  29  */
  30
  31 #ifndef _ITAPI_SAT_H_
  32 #define _ITAPI_SAT_H_
  33
  34 #include <tapi_common.h>
  35 #include <TelSat.h>
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #endif
  41
  42 /**
  43  * @brief Sends the user choice of the main menu options to the USIM.
  44  *
  45  * @details <b> Notes: </b>
  46  *          A set of possible menu options are supplied by the USIM
  47  *          using the proactive command SET UP MENU. The telephony server receives the command
  48  *          and publishes this information. The SAT UI application should list the menu when it is initially launched.
  49  *          If the user subsequently chooses an option, then the SAT UI application replies to
  50  *          the command with the user's choice using this API. \n
  51  *
  52  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
  53  *          However it just means that the API request has been transfered to the CP successfully.
  54  *          The actual operation result is delivered with the async response as below. \n
  55  *
  56  *          <b> Sync (or) Async: </b> This is an Asynchronous API. \n
  57  *
  58  *          <b> Prospective Clients: </b> SAT-UI.
  59  *
  60  * @since_tizen 2.3
  61  * @privlevel platform
  62  * @privilege %http://tizen.org/privilege/telephony.admin
  63  *
  64  * @remarks You must not use this function. This function is dedicated to the SAT UI embedded application only.
  65  *
  66  * @param[in] handle The handle from tel_init()
  67  *
  68  * @param[in] pMenuSelect #TelSatMenuSelectionReqInfo_t contains information like which SAT menu item has been selected or whether help is required
  69  *
  70  * @param[in] callback To register a callback function for result
  71  *
  72  * @param[in] user_data The user data for user specification
  73  *
  74  * @return The return type (int)\n
  75  *         #TAPI_API_SUCCESS - indicates that the operation has completed successfully,\n
  76  *         else it will return failure and an error code (Refer #TapiResult_t).
  77  *
  78  * @pre This function is supposed to be called after getting the #TAPI_EVENT_SAT_SETUP_MENU_IND event from the telephony server.
  79  *
  80  * @see tel_get_sat_main_menu_info()
  81  */
  82 int tel_select_sat_menu(TapiHandle *handle, const TelSatMenuSelectionReqInfo_t* pMenuSelect, tapi_response_cb callback, void *user_data);
  83
  84 /**
  85  * @brief Downloads SAT events to the USIM.
  86  *
  87  * @details <b> Notes: </b>
  88  *          A set of events for the terminal to monitor can be supplied by the USIM using the proactive command SET UP EVENT
  89  *          LIST. If the USIM has sent this command, and an event which is part of the list subsequently occurs, the terminal
  90  *          informs the USIM using this function, relevant for that event.
  91  *          If the USIM commands to monitor a browser termination event, the SAT-UI application has to call this function. \n
  92  *
  93  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
  94  *          However it just means that the API request has been transfered to the CP successfully.
  95  *          The actual operation result is delivered with the async response as below. \n
  96  *
  97  *          <b> Sync (or) Async: </b> This is an Asynchronous API. \n
  98  *
  99  *          <b> Prospective Clients: </b> SAT-UI \n
 100  *
 101  * @since_tizen 2.3
 102  * @privlevel platform
 103  * @privilege %http://tizen.org/privilege/telephony.admin
 104  *
 105  * @remarks You must not use this function. This function is dedicated to the SAT UI embedded application only.
 106  *
 107  * @param[in] handle The handle from tel_init()
 108  *
 109  * @param[in] pEventData #TelSatEventDownloadReqInfo_t contains the necessary parameters like event types and information associated with it
 110  *
 111  * @param[in] callback To register a callback function for result
 112  *
 113  * @param[in] user_data The user data for user specification
 114  *
 115  * @return The return type (int) \n
 116  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully, \n
 117  *         else it will return failure and an error code (Refer #TapiResult_t).
 118  *
 119  * @pre A SET UP EVENT LIST proactive command supplies a set of events to monitor.
 120  */
 121 int tel_download_sat_event(TapiHandle *handle, const TelSatEventDownloadReqInfo_t*  pEventData, tapi_response_cb callback, void *user_data);
 122
 123 /**
 124  * @brief Sends the UI display status of the alpha identifier of a specific proactive command to the Telephony Server.
 125  *
 126  * @details When SAT-UI receives a proactive command, SAT-UI should draw a UI for the relevant command.
 127  *          As it completes, SAT-UI informs the USIM by calling this function. Afterwards, the USIM is getting ready to send another command. \n
 128  *
 129  *          This function makes a Dbus method call to the Telephony Server and gets an immediate feedback. \n
 130  *
 131  *          <b> Sync (or) Async: </b> This is a Synchronous API. \n
 132  *
 133  *          <b> Prospective Clients: </b> SAT-UI \n
 134  *
 135  * @since_tizen 2.3
 136  * @privlevel platform
 137  * @privilege %http://tizen.org/privilege/telephony.admin
 138  *
 139  * @remarks You must not use this function. This function is dedicated to the SAT UI embedded application only.
 140  *
 141  * @param[in] handle The handle from tel_init()
 142  *
 143  * @param[in] commandId The proactive command ID from the application
 144  *
 145  * @param[in] status #TelSatUiDisplayStatusType_t contains the display status(SUCCESS/FAIL)
 146  *
 147  * @return The return type (int)\n
 148  *         #TAPI_API_SUCCESS - indicates that the operation has completed successfully,\n
 149  *         else it will return failure and an error code (Refer #TapiResult_t).
 150  *
 151  * @pre The display request for the alpha identifier of a Proactive Command should be sent by the Telephony Server.
 152  *
 153  * @post If the display status is SUCCESS, the Telephony Server sends a request to the application for Proactive Command Execution.
 154  *       If the display status is FAIL, the Telephony Server sends a Terminal Response for the Proactive Command.
 155  */
 156 int tel_send_sat_ui_display_status(TapiHandle *handle, int commandId, TelSatUiDisplayStatusType_t status);
 157
 158 /**
 159  * @brief Sends UI User confirmation data for a specific Proactive Command to the Telephony Server.
 160  *
 161  * @details In case the proactive commands need user response, SAT-UI can send it using this function.
 162  *          The response can be 'OK', 'Cancel', 'Move Back', and 'End Session'. Upon this response, the USIM can send
 163  *          a proactive command subsequently to indicate the next UI action. \n
 164  *
 165  *          This function makes a Dbus method call to the Telephony Server and gets an immediate feedback. \n
 166  *
 167  *          <b> Sync (or) Async: </b> This is a synchronous API. \n
 168  *
 169  *          <b> Prospective Clients: </b> SAT-UI. \n
 170  *
 171  * @since_tizen 2.3
 172  * @privlevel platform
 173  * @privilege %http://tizen.org/privilege/telephony.admin
 174  *
 175  * @remarks You must not use this function. This function is dedicated to the SAT UI embedded application only.
 176  *
 177  * @param[in] handle The handle from tel_init()
 178  *
 179  * @param[in] pUserConfirmData #TelSatUiUserConfirmInfo_t contains specific user confirmation data
 180  *
 181  * @return The return type (int)\n
 182  *         #TAPI_API_SUCCESS - indicates that the operation has completed successfully,\n
 183  *         else it will return failure and an error code (Refer #TapiResult_t).
 184  *
 185  * @pre The User Confirmation request for a specific Proactive Command should be sent to the application by the Telephony Server.
 186  *
 187  * @post If the User Confirmation is positive, the Telephony Server sends a request to the application for Proactive Command Execution.
 188  *       If the User Confirmation is negative, the Telephony Server sends a Terminal Response for the Proactive Command.
 189  */
 190 int tel_send_sat_ui_user_confirm(TapiHandle *handle, TelSatUiUserConfirmInfo_t *pUserConfirmData);
 191
 192 /**
 193  * @brief Provides SAT(Sim Application toolkit) Main Menu information for SAT-UI.
 194  *
 195  * @details Once the USIM supplies the SET UP MENU proactive command, the telephony server not only publishes the
 196  *          #TAPI_EVENT_SAT_SETUP_MENU_IND event but also caches the menu information.
 197  *          The SAT-UI application can get the menu list using this function. \n
 198  *
 199  *          This function makes a Dbus method call to the Telephony Server and gets an immediate feedback. \n
 200  *
 201  *         <b> Sync (or) Async: </b> This is a Synchronous API. \n
 202  *
 203  *         <b> Prospective Clients: </b> SAT-UI.
 204  *
 205  * @since_tizen 2.3
 206  * @privlevel public
 207  * @privilege %http://tizen.org/privilege/telephony
 208  *
 209  * @remarks You must not use this function. This function is dedicated to the SAT UI embedded application only.
 210  *
 211  * @param[in] handle The handle from tel_init()
 212  *
 213  * @param[out] pMainMenu #TelSatSetupMenuInfo_t contains all menu related information which is required such as a menu title, an icon, an item count, and so on
 214  *
 215  * @return The return type (int)\n
 216  *         #TAPI_API_SUCCESS - indicates that the operation has completed successfully,\n
 217  *         else it will return failure and an error code (Refer #TapiResult_t).
 218  *
 219  * @pre When SAT SIM is inserted we can get meaningful data. Without SAT SIM, null is returned.
 220  *
 221  * @see tel_select_sat_menu()
 222  */
 223 int tel_get_sat_main_menu_info(TapiHandle *handle, TelSatSetupMenuInfo_t *pMainMenu);
 224
 225 /**
 226  * @brief Provides the Operation result(s) for Proactive Command execution by the Application(s) to the Telephony Server.
 227  *
 228  * @details The USIM commands the terminal to do some predefined action, such as sending a short message,
 229  *          making a voice call, launching an Internet browser, and so on. Those actions are defined by 3GPP TS31.111.
 230  *          Once an application executes the requested action by USIM, it reports the operation result to the USIM using this function. \n
 231  *
 232  *          This function makes a Dbus method call to the Telephony Server and gets an immediate feedback. \n
 233  *
 234  *          <b> Sync (or) Async: </b> This is a Synchronous API. \n
 235  *
 236  *          <b> Prospective Clients: </b> Embeded applications which are predefined by 3GPP TS31.111.
 237  *
 238  * @since_tizen 2.3
 239  * @privlevel platform
 240  * @privilege %http://tizen.org/privilege/telephony.admin
 241  *
 242  * @remarks You must not use this function. This function is dedicated to the SAT UI embedded application only.
 243  *
 244  * @param[in] handle The handle from tel_init()
 245  *
 246  * @param[out] pAppRetInfo #TelSatAppsRetInfo_t contains an execution result of a specific proactive command by the application
 247  *
 248  * @return The return type (int)\n
 249  *         #TAPI_API_SUCCESS - indicates that the operation has completed successfully,\n
 250  *         else it will return failure and an error code (Refer #TapiResult_t).
 251  *
 252  * @pre The Proactive Command execution request should be sent by the Telephony Server to SAT related applications.
 253  */
 254 int tel_send_sat_app_exec_result(TapiHandle *handle, TelSatAppsRetInfo_t *pAppRetInfo);
 255
 256 #ifdef __cplusplus
 257 }
 258 #endif
 259
 260 #endif  /* _ITAPI_SAT_H_ */
 261
 262 /**
 263  * @}
 264  */