include/tapi/ITapiSat.h

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