include/tapi_sat.h

   1 /*
   2  * libtapi
   3  *
   4  * Copyright (c) 2013 Samsung Electronics Co. Ltd. All rights reserved.
   5  * Copyright (c) 2013 Intel Corporation. All rights reserved.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 /**
  21 *  @addtogroup TAPI_SAT
  22 *  @{
  23 *
  24 *  @file tapi_sat.h
  25 *  @brief TAPI SAT Interface
  26 */
  27
  28 #ifndef __TAPI_SAT_H__
  29 #define __TAPI_SAT_H__
  30
  31 #include <tapi.h>
  32 #include <tel_sat.h>
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #endif
  38
  39  /**
  40  * @brief Sends the user choice of the main menu options to the USIM.
  41  *
  42  * @par Notes:
  43  * A set of possible menu options is supplied by the USIM
  44  * using the proactive command SET UP MENU. Telephony server receives the command
  45  * and publishes this information.SAT UI application should list the menu when it initially launched.
  46  * If the user subsequently chooses an option, then SAT UI application replies
  47  * the command with user's choice using this API.
  48  *
  49  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
  50  * However it just means that the API request has been transfered to the CP successfully.
  51  * The actual operation result is delivered with the async response as below.
  52  *
  53  * @par Warning:
  54  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
  55  *
  56  * @par Sync (or) Async:
  57  * This is an Asynchronous API.
  58  *
  59  * @param [in] handle - #TelHandle obtained from tapi_init()
  60  * @param [in] menu_select - #TelSatMenuSelectionReqInfo contains information like which SAT menu item has been selected or whether Help is required.
  61  * @param [in] callback - Response callback
  62  * @param [in] user_data - user_data for user specification.
  63  *
  64  * @par Async Response Message:
  65  * - The event associated is TEL_EVENT_SAT_MENU_SELECTION_CNF and the Asynchronous return status is indicated by #TelSatEnvelopeResp.
  66  *
  67  * @pre
  68  *  - This function supposed to be called after getting TEL_EVENT_SAT_SETUP_MENU_IND event from telephony server\n
  69  *
  70  * @post
  71  *  - None
  72  *
  73  *  @return Possible #TelReturn values:\n
  74  *  <b>TEL_RETURN_SUCCESS</b>: Operation completed successfully\n
  75  *  <b>TEL_RETURN_INVALID_PARAMETER</b>: Invalid input parameters
  76  *  <b>TEL_RETURN_FAILURE</b>: Operation Failed\n
  77  *
  78  * @par Prospective Clients:
  79  * SAT-UI
  80  *
  81  * @see tapi_sat_get_main_menu_info
  82  *
  83  * @code
  84  * #include <tapi_sat.h>
  85  * TelHandle *handle;  //obtained from tapi_init()
  86  * TapiResponseCb callback; //Response callback
  87  * void *user_data; // user_data for user specification
  88  * TelReturn ret_status = TEL_RETURN_SUCCESS;
  89  * TelSatMenuSelectionReqInfo selected_menu;
  90  * selected_menu.item_identifier = '1'; //selected menu num
  91  * selected_menu.b_is_help_requested = 0;
  92  * ret_status = tapi_sat_select_menu(handle, &selected_menu, callback, user_data);
  93  * @endcode
  94  *
  95  * @remarks None
  96  *
  97  *
  98  */
  99 /*================================================================================================*/
 100 TelReturn tapi_sat_select_menu(TelHandle *handle, const TelSatMenuSelectionReqInfo* menu_select, TapiResponseCb callback, void *user_data);
 101
 102  /**
 103  * @brief  Download SAT events to USIM
 104  *
 105  * @par Notes:
 106  * A set of events for the terminal to monitor can be supplied by the USIM using the proactive command SET UP EVENT
 107  * LIST. If the USIM has sent this command, and an event which is part of the list subsequently occurs, the terminal
 108  * informs the USIM using this function, relevant for that event.
 109  * If USIM commands to monitor a browser termination event, the SAT-UI application has to call this function.
 110  *
 111  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 112  * However it just means that the API request has been transfered to the CP successfully.
 113  * The actual operation result is delivered with the async response as below.
 114  *
 115  * @par Warning:
 116  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 117  *
 118  * @par Sync (or) Async:
 119  * This is an Asynchronous API.
 120  *
 121  * @param [in] handle - #TelHandle obtained from tapi_init()
 122  * @param [in] event_data - #TelSatEventDownloadReqInfo contains the necessary parameters like event type and information associated with it.
 123  * @param [in] callback - Response callback
 124  * @param [in] user_data - user_data for user specification.
 125  *
 126  * @par Async Response Message:
 127  * - The event associated is TEL_EVENT_SAT_EVENT_DOWNLOAD_CNF and the Asynchronous return status is indicated by #TelSatEnvelopeResp.
 128  *
 129  * @pre
 130  *  - A SET UP EVENT LIST proactive command supplies a set of event to monitor.
 131  *
 132  * @post
 133  *  - None.
 134  *
 135  *  @return Possible #TelReturn values:\n
 136  *  <b>TEL_RETURN_SUCCESS</b>: Operation completed successfully\n
 137  *  <b>TEL_RETURN_INVALID_PARAMETER</b>: Invalid input parameters
 138  *  <b>TEL_RETURN_FAILURE</b>: Operation Failed\n
 139  *
 140  * @par Prospective Clients:
 141  * SAT-UI
 142  *
 143  * @see None
 144  *
 145  * @code
 146  * #include <tapi_sat.h>
 147  * TelHandle *handle;  //obtained from tapi_init()
 148  * TapiResponseCb callback; //Response callback
 149  * void *user_data; // user_data for user specification
 150  * TelReturn ret_status = TEL_RETURN_SUCCESS;
 151  * TelSatEventDownloadReqInfo event_data;
 152  * event_data.event_download_type = TEL_SAT_EVENT_IDLE_SCREEN_AVAILABLE;
 153  * event_data.u.b_idle_screen_available = 1; //event occur or not
 154  * ret_status = tapi_sat_download_event(handle, &event_data, callback, user_data);
 155  * @endcode
 156  *
 157  * @remarks None
 158  *
 159  *
 160  */
 161 /*================================================================================================*/
 162 TelReturn tapi_sat_download_event(TelHandle *handle, const TelSatEventDownloadReqInfo*  event_data, TapiResponseCb callback, void *user_data);
 163
 164 /**
 165  * @brief  Send the UI display status of the alpha identifier of a specific proactive command to Telephony Server.
 166  *
 167  * When SAT-UI receives a proactive command, SAT-UI should draw a UI for relevant command.
 168  * As it completes , SAT-UI inform USIM with this function. Afterwards, USIM is getting ready to send another commands.
 169  *
 170  * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
 171  *
 172  * @par Warning:
 173  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 174  *
 175  * @par Sync (or) Async:
 176  * This is a Synchronous API.
 177  *
 178  * @param [in] handle - #TelHandle obtained from tapi_init()
 179  * @param [in] command_id - Specific proactive command id from the Application
 180  * @param [in] status - #TelSatUiDisplayStatusType contain display status(SUCCESS/FAIL).
 181  *
 182  * @par Async Response Message:
 183  * - None.
 184  *
 185  * @pre
 186  *  - Display request for the alpha identifier of a Proactive Command should be sent by Telephony Server.
 187  *
 188  * @post
 189  *  - If the display status is SUCCESS Telephony Server sends a request to application for Proactive Command Execution.
 190  *  - If the display status is FAIL Telephony Server sends Terminal Response for the Proactive Command.
 191  *
 192  *  @return Possible #TelReturn values:\n
 193  *  <b>TEL_RETURN_SUCCESS</b>: Operation completed successfully\n
 194  *  <b>TEL_RETURN_FAILURE</b>: Operation Failed\n
 195  *
 196  * @par Prospective Clients:
 197  * SAT-UI
 198  *
 199  * @see None
 200  *
 201  * @code
 202  * #include <tapi_sat.h>
 203  * TelHandle *handle;  //obtained from tapi_init()
 204  * int command_id; //this value should be server given value
 205  * TelReturn ret_status = TEL_RETURN_SUCCESS;
 206  * ret_status = tapi_sat_send_ui_display_status(handle, command_id, TEL_SAT_DISPLAY_SUCCESS);
 207  * @endcode
 208  *
 209  * @remarks None
 210  *
 211  *
 212  */
 213 /*================================================================================================*/
 214 TelReturn tapi_sat_send_ui_display_status(TelHandle *handle, int command_id, TelSatUiDisplayStatusType status);
 215
 216  /**
 217  * @brief  This function sends the UI User confirmation data for a specific Proactive Command to the Telephony Server.
 218  *
 219  * In case that the proactive commands need user response, SAT-UI can send it using this function.
 220  * The response can be 'OK', 'Cancel', 'Move Back' and 'End Session'. Upon this response, USIM can send
 221  * a proactive command subsequently to indicate next UI action.
 222  *
 223  * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
 224  *
 225  * @par Warning:
 226  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 227  *
 228  * @par Sync (or) Async:
 229  * This is a synchronous API.
 230  *
 231  * @param [in] handle - #TelHandle obtained from tapi_init()
 232  * @param [in] pUserConfirmData -#TelSatUiUserConfirmInfo contains Specific user confirmation data.
 233  *
 234  * @par Async Response Message:
 235  * - None
 236  *
 237  * @pre
 238  *  - User Confirmation request for a specific Proactive Command should be sent to application by Telephony Server.
 239  *
 240  * @post
 241  *  - If the User Confirmation is positive Telephony Server sends a request to application for Proactive Command Execution.
 242  *  - If the User Confirmation is negative Telephony Server sends Terminal Response for the Proactive Command.
 243  *
 244  *  @return Possible #TelReturn values:\n
 245  *  <b>TEL_RETURN_SUCCESS</b>: Operation completed successfully\n
 246  *  <b>TEL_RETURN_FAILURE</b>: Operation Failed\n
 247  *
 248  * @par Prospective Clients:
 249  * SAT-UI
 250  *
 251  * @see None
 252  *
 253  * @code
 254  * #include <tapi_sat.h>
 255  * TelHandle *handle;  //obtained from tapi_init()
 256  * TelReturn ret_status = TEL_RETURN_SUCCESS;
 257  * TelSatUiUserConfirmInfo cfm_data;
 258  * cfm_data.command_id = '1'; //this value should be server given value
 259  * cfm_data.command_type = TEL_SAT_CMD_TYPE_SETUP_CALL;
 260  * cfm_data.key_type = TEL_SAT_USER_CONFIRM_YES;
 261  * ret_status = tapi_sat_send_ui_user_confirm(handle, &cfm_data);
 262  * @endcode
 263  *
 264  * @remarks None
 265  *
 266  *
 267  */
 268 /*================================================================================================*/
 269 TelReturn tapi_sat_send_ui_user_confirm(TelHandle *handle, TelSatUiUserConfirmInfo *user_confirm_data);
 270
 271  /**
 272  * @brief  This function provides SAT(Sim Application toolkit) Main Menu information for SAT-UI.
 273  *
 274  * Once the USIM supplies the SET UP MENU proactivae command, telephony server not only publish
 275  * TAPI_EVENT_SAT_SETUP_MENU_IND event but also caches the menu information.
 276  * The SAT-UI applicatoin can get the menu list using this function.
 277  *
 278  * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
 279  *
 280  * @par Warning:
 281  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 282  *
 283  * @par Sync (or) Async:
 284  * This is a Synchronous API.
 285  *
 286  * @param [in] handle - #TelHandle obtained from tapi_init()
 287  * @param [out] main_menu - #TelSatSetupMenuInfo contain all menu related information which are required like menu title, icon, item count, etc.
 288  *
 289  * @par Async Response Message:
 290  * - None
 291  *
 292  * @pre
 293  *  - When SAT SIM is inserted. we can get meaningful data. without SAT SIM, Null is returned
 294  *
 295  * @post
 296  *  - None.
 297  *
 298  *  @return Possible #TelReturn values:\n
 299  *  <b>TEL_RETURN_SUCCESS</b>: Operation completed successfully\n
 300  *  <b>TEL_RETURN_FAILURE</b>: Operation Failed\n
 301  *
 302  * @par Prospective Clients:
 303  * SAT-UI
 304  *
 305  * @see tapi_sat_select_menu
 306  *
 307  * @code
 308  * #include <tapi_sat.h>
 309  * TelHandle *handle;  //obtained from tapi_init()
 310  * TelReturn ret_status = TEL_RETURN_SUCCESS;
 311  * TelSatSetupMenuInfo menu; //this struct will be pull up with SIM menu info
 312  * ret_status = tapi_sat_get_main_menu_info(handle, &menu);
 313  * @endcode
 314  *
 315  * @remarks None
 316  *
 317  *
 318  */
 319 /*================================================================================================*/
 320 TelReturn tapi_sat_get_main_menu_info(TelHandle *handle, TelSatSetupMenuInfo *main_menu);
 321
 322  /**
 323  * @brief  This API provides the Operation result(s) for the Proactive Command execution by the Application(s) to the Telephony Server.
 324  *
 325  * The USIM commands the terminal to do some predefined action, such as sending short message,
 326  * making a voice call, launching an Internet browser and so on. Those actions are defined by 3GPP TS31.111.
 327  * Once a application executes the requested action by USIM, it reports the operation result to USIM using this function.
 328  *
 329  * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
 330  *
 331  * @par Warning:
 332  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 333  **
 334  * @par Sync (or) Async:
 335  * This is a Synchronous API.
 336  *
 337  * @param [in] handle - #TelHandle obtained from tapi_init()
 338  * @param [out] app_ret_info - #TelSatAppsRetInfo contains execution result of a specific proactive command by application.
 339  *
 340  * @par Async Response Message:
 341  * - None
 342  *
 343  * @pre
 344  *  - Proactive Command execution request should be sent by Telephony Server to SAT related applications.
 345  *
 346  * @post
 347  *  - None.
 348  *
 349  *  @return Possible #TelReturn values:\n
 350  *  <b>TEL_RETURN_SUCCESS</b>: Operation completed successfully\n
 351  *  <b>TEL_RETURN_FAILURE</b>: Operation Failed\n
 352  *
 353  * @par Prospective Clients:
 354  * Embeded applications which are predefined by 3GPP TS31.111
 355  *
 356  * @see None
 357  *
 358  * @code
 359  * #include <tapi_sat.h>
 360  * TelHandle *handle;  //obtained from tapi_init()
 361  * TelReturn ret_status = TEL_RETURN_SUCCESS;
 362  * TelSatAppsRetInfo app_ret;
 363  * app_ret.command_type = TEL_SAT_CMD_TYPE_SETUP_CALL;
 364  * app_ret.command_id = 1; //this value should be server given value
 365  * app_ret.apps_ret.setup_call.resp = TEL_SAT_R_SUCCESS;
 366  * ret_status = tapi_sat_send_app_exec_result(handle, &app_ret);
 367  * @endcode
 368  *
 369  * @remarks None
 370  *
 371  *
 372  */
 373 /*================================================================================================*/
 374 TelReturn tapi_sat_send_app_exec_result(TelHandle *handle, TelSatAppsRetInfo *app_ret_info);
 375
 376 #ifdef __cplusplus
 377 }
 378 #endif
 379
 380 #endif  /* __TAPI_SAT_H__ */
 381
 382 /**
 383  * @}
 384  */