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