mobile/include/ITapiSat.h

   1 /*
   2  * libslp-tapi
   3  *
   4  * Copyright (c) 2011 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 * @open
  23 * @ingroup              TelephonyAPI
  24 * @addtogroup   SAT_TAPI        SAT
  25 * @{
  26 *
  27 * @file ITapiSat.h
  28
  29      @brief This file serves as a "C" header file defines functions for Tapi Sat Services.\n
  30       It contains a sample set of function prototypes that would be required by applications.
  31
  32       Note: Telephony SAT functionality is message relaying from USIM application to SAT related applications.
  33  */
  34
  35 #ifndef _ITAPI_SAT_H_
  36 #define _ITAPI_SAT_H_
  37
  38 #include <tapi_common.h>
  39 #include <TelSat.h>
  40 #include <TelDefines.h>
  41
  42 #ifdef __cplusplus
  43 extern "C"
  44 {
  45 #endif
  46
  47  /**
  48  * @brief Sends the user choice of the main menu options to the USIM.
  49  *
  50  * @par Notes:
  51  * A set of possible menu options is supplied by the USIM
  52  * using the proactive command SET UP MENU. Telephony server receives the command
  53  * and publishes this information.SAT UI application should list the menu when it initially launched.
  54  * If the user subsequently chooses an option, then SAT UI application replies
  55  * the command with user's choice using this API.
  56  *
  57  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
  58  * However it just means that the API request has been transfered to the CP successfully.
  59  * The actual operation result is delivered with the async response as below.
  60  *
  61  * @par Warning:
  62  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
  63  *
  64  * @par Sync (or) Async:
  65  * This is an Asynchronous API.
  66  *
  67  * @param [in] handle
  68  * - handle from tel_init().
  69  *
  70  * @param [in] pMenuSelect
  71  * - #TelSatMenuSelectionReqInfo_t contains information like which SAT menu item has been selected or whether Help is required.
  72  *
  73  * @param [in] callback
  74  * - To register callback function for result.
  75  *
  76  * @param [in] user_data
  77  * - user_data for user specification.
  78  *
  79  * @par Async Response Message:
  80  * - The event associated is TAPI_EVENT_SAT_MENU_SELECTION_CNF and the Asynchronous return status is indicated by #TelSatEnvelopeResp_t.
  81  *
  82  * @pre
  83  *  - This function supposed to be called after getting TAPI_EVENT_SAT_SETUP_MENU_IND event from telephony server\n
  84  *
  85  * @post
  86  *  - None
  87  *
  88  * @return Return Type (int) \n
  89  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
  90  * - Else it will return failure and error code (Refer #TapiResult_t)
  91  *
  92  * @par Prospective Clients:
  93  * SAT-UI
  94  *
  95  * @see tel_get_sat_main_menu_info
  96  *
  97  * @code
  98  * #include <ITapiSat.h>
  99  * int ret_status =0;
 100  * int pRequestID=0;
 101  * TelSatMenuSelectionReqInfo_t selected_menu;
 102  * selected_menu.itemIdentifier = '1'; //selected menu num
 103  * selected_menu.bIsHelpRequested = 0;
 104  * ret_status = tel_select_sat_menu(&selected_menu, &pRequestId);
 105  * @endcode
 106  *
 107  * @remarks None
 108  *
 109  *
 110  */
 111 /*================================================================================================*/
 112 int tel_select_sat_menu(TapiHandle *handle, const TelSatMenuSelectionReqInfo_t* pMenuSelect, tapi_response_cb callback, void *user_data);
 113
 114  /**
 115  * @brief  Download SAT events to USIM
 116  *
 117  * @par Notes:
 118  * A set of events for the terminal to monitor can be supplied by the USIM using the proactive command SET UP EVENT
 119  * LIST. If the USIM has sent this command, and an event which is part of the list subsequently occurs, the terminal
 120  * informs the USIM using this function, relevant for that event.
 121  * If USIM commands to monitor a browser termination event, the SAT-UI application has to call this function.
 122  *
 123  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 124  * However it just means that the API request has been transfered to the CP successfully.
 125  * The actual operation result is delivered with the async response as below.
 126  *
 127  * @par Warning:
 128  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 129  *
 130  * @par Sync (or) Async:
 131  * This is an Asynchronous API.
 132  *
 133  * @param [in] handle
 134  * - handle from tel_init().
 135  *
 136  * @param [in] pEventData
 137  * - #TelSatEventDownloadReqInfo_t contains the necessary parameters like event type and information associated with it.
 138  *
 139  * @param [in] callback
 140  * - To register callback function for result.
 141  *
 142  * @param [in] user_data
 143  * - user_data for user specification.
 144  *
 145  * @par Async Response Message:
 146  * - The event associated is TAPI_EVENT_SAT_EVENT_DOWNLOAD_CNF and the Asynchronous return status is indicated by #TelSatEnvelopeResp_t.
 147  *
 148  * @pre
 149  *  - A SET UP EVENT LIST proactive command supplies a set of event to monitor.
 150  *
 151  * @post
 152  *  - None.
 153  *
 154  * @return Return Type (int) \n
 155  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 156  * - Else it will return failure and error code (Refer #TapiResult_t)
 157  *
 158  * @par Prospective Clients:
 159  * SAT-UI
 160  *
 161  * @see None
 162  *
 163  * @code
 164  * #include <ITapiSat.h>
 165  * int ret_status =0;
 166  * int pRequestID=0;
 167  * TelSatEventDownloadReqInfo_t pEventData;
 168  * pEventData.eventDownloadType = TAPI_EVENT_SAT_DW_TYPE_IDLE_SCREEN_AVAILABLE;
 169  * pEventData.u.bIdleScreenAvailable = 1; //event occur or not
 170  * ret_status = tel_download_sat_event(&pEventData, &pRequestId);
 171  * @endcode
 172  *
 173  * @remarks None
 174  *
 175  *
 176  */
 177 /*================================================================================================*/
 178 int tel_download_sat_event(TapiHandle *handle, const TelSatEventDownloadReqInfo_t*  pEventData, tapi_response_cb callback, void *user_data);
 179
 180  /**
 181  * @brief  Send the UI display status of the alpha identifier of a specific proactive command to Telephony Server.
 182  *
 183  * When SAT-UI receives a proactive command, SAT-UI should draw a UI for relevant command.
 184  * As it completes , SAT-UI inform USIM with this function. Afterwards, USIM is getting ready to send another commands.
 185  *
 186  * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
 187  *
 188  * @par Warning:
 189  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 190  *
 191  * @par Sync (or) Async:
 192  * This is a Synchronous API.
 193  *
 194  * @param [in] handle
 195  * - handle from tel_init().
 196  *
 197  * @param [in] commandId
 198  * - Specific proactive command id from the Application
 199  *
 200  * @param [in] status
 201  * - #TelSatUiDisplayStatusType_t contain display status(SUCCESS/FAIL).
 202  *
 203  * @par Async Response Message:
 204  * - None.
 205  *
 206  * @pre
 207  *  - Display request for the alpha identifier of a Proactive Command should be sent by Telephony Server.
 208  *
 209  * @post
 210  *  - If the display status is SUCCESS Telephony Server sends a request to application for Proactive Command Execution.
 211  *  - If the display status is FAIL Telephony Server sends Terminal Response for the Proactive Command.
 212  *
 213  * @return Return Type (int) \n
 214  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 215  * - Else it will return failure and error code (Refer #TapiResult_t)
 216  *
 217  * @par Prospective Clients:
 218  * SAT-UI
 219  *
 220  * @see None
 221  *
 222  * @code
 223  * #include <ITapiSat.h>
 224  * int commandId = 1; //this value should be server given value
 225  * ret_status = 0;
 226  * ret_status = tel_send_ui_display_status(1, TAPI_SAT_DISPLAY_SUCCESS);
 227  * @endcode
 228  *
 229  * @remarks None
 230  *
 231  *
 232  */
 233 /*================================================================================================*/
 234 int tel_send_sat_ui_display_status(TapiHandle *handle, int commandId, TelSatUiDisplayStatusType_t status);
 235
 236  /**
 237  * @brief  This function sends the UI User confirmation data for a specific Proactive Command to the Telephony Server.
 238  *
 239  * In case that the proactive commands need user response, SAT-UI can send it using this function.
 240  * The response can be 'OK', 'Cancel', 'Move Back' and 'End Session'. Upon this response, USIM can send
 241  * a proactive command subsequently to indicate next UI action.
 242  *
 243  * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
 244  *
 245  * @par Warning:
 246  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 247  *
 248  * @par Sync (or) Async:
 249  * This is a synchronous API.
 250  *
 251  * @param [in] handle
 252  * - handle from tel_init().
 253  *
 254  *@param [in] pUserConfirmData
 255  * -#TelSatUiUserConfirmInfo_t contains Specific user confirmation data.
 256  *
 257  * @par Async Response Message:
 258  * - None
 259  *
 260  * @pre
 261  *  - User Confirmation request for a specific Proactive Command should be sent to application by Telephony Server.
 262  *
 263  * @post
 264  *  - If the User Confirmation is positive Telephony Server sends a request to application for Proactive Command Execution.
 265  *  - If the User Confirmation is negative Telephony Server sends Terminal Response for the Proactive Command.
 266  *
 267  * @return Return Type (int) \n
 268  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 269  * - Else it will return failure and error code (Refer #TapiResult_t)
 270  *
 271  * @par Prospective Clients:
 272  * SAT-UI
 273  *
 274  * @see None
 275  *
 276  * @code
 277  * #include <ITapiSat.h>
 278  * int ret_status =0;
 279  * TelSatUiUserConfirmInfo_t cfm_data;
 280  * cfm_data.commandId = '1'; //this value should be server given value
 281  * cfm_data.commandType = TAPI_SAT_CMD_TYPE_SETUP_CALL;
 282  * cfm_data.keyType = TAPI_SAT_USER_CONFIRM_YES;
 283  * ret_status = tel_send_sat_ui_user_confirm(&cfm_data);
 284  * @endcode
 285  *
 286  * @remarks None
 287  *
 288  *
 289  */
 290 /*================================================================================================*/
 291 int tel_send_sat_ui_user_confirm(TapiHandle *handle, TelSatUiUserConfirmInfo_t *pUserConfirmData);
 292
 293  /**
 294  * @brief  This function provides SAT(Sim Application toolkit) Main Menu information for SAT-UI.
 295  *
 296  * Once the USIM supplies the SET UP MENU proactivae command, telephony server not only publish
 297  * TAPI_EVENT_SAT_SETUP_MENU_IND event but also caches the menu information.
 298  * The SAT-UI applicatoin can get the menu list using this function.
 299  *
 300  * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
 301  *
 302  * @par Warning:
 303  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 304  *
 305  * @par Sync (or) Async:
 306  * This is a Synchronous API.
 307  *
 308  * @param [in] handle
 309  * - handle from tel_init().
 310  *
 311  * @param [out] pMainMenu
 312  * - #TelSatSetupMenuInfo_t contain all menu related information which are required like menu title, icon, item count, etc.
 313  *
 314  * @par Async Response Message:
 315  * - None
 316  *
 317  * @pre
 318  *  - When SAT SIM is inserted. we can get meaningful data. without SAT SIM, Null is returned
 319  *
 320  * @post
 321  *  - None.
 322  *
 323  * @return Return Type (int) \n
 324  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 325  * - Else it will return failure and error code (Refer #TapiResult_t)
 326  *
 327  * @par Prospective Clients:
 328  * SAT-UI
 329  *
 330  * @see tel_select_sat_menu
 331  *
 332  * @code
 333  * #include <ITapiSat.h>
 334  * int ret_status =0;
 335  * TelSatSetupMenuInfo_t menu; //this struct will be pull up with SIM menu info
 336  * ret_status = tel_get_sat_main_menu_info(&menu);
 337  * @endcode
 338  *
 339  * @remarks None
 340  *
 341  *
 342  */
 343 /*================================================================================================*/
 344 int tel_get_sat_main_menu_info(TapiHandle *handle, TelSatSetupMenuInfo_t *pMainMenu);
 345
 346  /**
 347  * @brief  This API provides the Operation result(s) for the Proactive Command execution by the Application(s) to the Telephony Server.
 348  *
 349  * The USIM commands the terminal to do some predefined action, such as sending short message,
 350  * making a voice call, launching an Internet browser and so on. Those actions are defined by 3GPP TS31.111.
 351  * Once a application executes the requested action by USIM, it reports the operation result to USIM using this function.
 352  *
 353  * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
 354  *
 355  * @par Warning:
 356  * Do not use this function. This function is dedicated to the SAT UI embedded application only.
 357  **
 358  * @par Sync (or) Async:
 359  * This is a Synchronous API.
 360  *
 361  * @param [in] handle
 362  * - handle from tel_init().
 363  *
 364  * @param [out] pAppRetInfo
 365  * - #TelSatAppsRetInfo_t contains execution result of a specific proactive command by application.
 366  *
 367  * @par Async Response Message:
 368  * - None
 369  *
 370  * @pre
 371  *  - Proactive Command execution request should be sent by Telephony Server to SAT related applications.
 372  *
 373  * @post
 374  *  - None.
 375  *
 376  * @return Return Type (int) \n
 377  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 378  * - Else it will return failure and error code (Refer #TapiResult_t)
 379  *
 380  * @par Prospective Clients:
 381  * Embeded applications which are predefined by 3GPP TS31.111
 382  *
 383  * @see None
 384  *
 385  * @code
 386  * #include <ITapiSat.h>
 387  * int ret_status =0;
 388  * TelSatAppsRetInfo_t app_ret;
 389  * app_ret.commandType = TAPI_SAT_CMD_TYPE_SETUP_CALL;
 390  * app_ret.commandId = 1; //this value should be server given value
 391  * app_ret.appsRet.setupCall.resp = TAPI_SAT_R_SUCCESS;
 392  * ret_status = tel_send_sat_app_exec_result(&app_ret);
 393  * @endcode
 394  *
 395  * @remarks None
 396  *
 397  *
 398  */
 399 /*================================================================================================*/
 400 int tel_send_sat_app_exec_result(TapiHandle *handle, TelSatAppsRetInfo_t *pAppRetInfo);
 401
 402
 403 #ifdef __cplusplus
 404 }
 405 #endif
 406
 407 #endif  /* _ITAPI_SAT_H_ */
 408
 409 /**
 410  * @}
 411  */