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