4 * Copyright (c) 2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Ja-young Gu <jygu@samsung.com>
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
23 * @ingroup TelephonyAPI
24 * @addtogroup SAT_TAPI SAT
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.
32 Note: Telephony SAT functionality is message relaying from USIM application to SAT related applications.
38 #include <tapi_common.h>
40 #include <TelDefines.h>
48 * @brief Sends the user choice of the main menu options to the USIM.
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.
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.
62 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
64 * @par Sync (or) Async:
65 * This is an Asynchronous API.
68 * - handle from tel_init().
70 * @param [in] pMenuSelect
71 * - #TelSatMenuSelectionReqInfo_t contains information like which SAT menu item has been selected or whether Help is required.
73 * @param [in] callback
74 * - To register callback function for result.
76 * @param [in] user_data
77 * - user_data for user specification.
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.
83 * - This function supposed to be called after getting TAPI_EVENT_SAT_SETUP_MENU_IND event from telephony server\n
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)
92 * @par Prospective Clients:
95 * @see tel_get_sat_main_menu_info
98 * #include <ITapiSat.h>
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);
111 /*================================================================================================*/
112 int tel_select_sat_menu(TapiHandle *handle, const TelSatMenuSelectionReqInfo_t* pMenuSelect, tapi_response_cb callback, void *user_data);
115 * @brief Download SAT events to USIM
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.
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.
128 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
130 * @par Sync (or) Async:
131 * This is an Asynchronous API.
134 * - handle from tel_init().
136 * @param [in] pEventData
137 * - #TelSatEventDownloadReqInfo_t contains the necessary parameters like event type and information associated with it.
139 * @param [in] callback
140 * - To register callback function for result.
142 * @param [in] user_data
143 * - user_data for user specification.
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.
149 * - A SET UP EVENT LIST proactive command supplies a set of event to monitor.
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)
158 * @par Prospective Clients:
164 * #include <ITapiSat.h>
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);
177 /*================================================================================================*/
178 int tel_download_sat_event(TapiHandle *handle, const TelSatEventDownloadReqInfo_t* pEventData, tapi_response_cb callback, void *user_data);
181 * @brief Send the UI display status of the alpha identifier of a specific proactive command to Telephony Server.
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.
186 * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
189 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
191 * @par Sync (or) Async:
192 * This is a Synchronous API.
195 * - handle from tel_init().
197 * @param [in] commandId
198 * - Specific proactive command id from the Application
201 * - #TelSatUiDisplayStatusType_t contain display status(SUCCESS/FAIL).
203 * @par Async Response Message:
207 * - Display request for the alpha identifier of a Proactive Command should be sent by Telephony Server.
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.
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)
217 * @par Prospective Clients:
223 * #include <ITapiSat.h>
224 * int commandId = 1; //this value should be server given value
226 * ret_status = tel_send_ui_display_status(1, TAPI_SAT_DISPLAY_SUCCESS);
233 /*================================================================================================*/
234 int tel_send_sat_ui_display_status(TapiHandle *handle, int commandId, TelSatUiDisplayStatusType_t status);
237 * @brief This function sends the UI User confirmation data for a specific Proactive Command to the Telephony Server.
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.
243 * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
246 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
248 * @par Sync (or) Async:
249 * This is a synchronous API.
252 * - handle from tel_init().
254 *@param [in] pUserConfirmData
255 * -#TelSatUiUserConfirmInfo_t contains Specific user confirmation data.
257 * @par Async Response Message:
261 * - User Confirmation request for a specific Proactive Command should be sent to application by Telephony Server.
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.
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)
271 * @par Prospective Clients:
277 * #include <ITapiSat.h>
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);
290 /*================================================================================================*/
291 int tel_send_sat_ui_user_confirm(TapiHandle *handle, TelSatUiUserConfirmInfo_t *pUserConfirmData);
294 * @brief This function provides SAT(Sim Application toolkit) Main Menu information for SAT-UI.
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.
300 * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
303 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
305 * @par Sync (or) Async:
306 * This is a Synchronous API.
309 * - handle from tel_init().
311 * @param [out] pMainMenu
312 * - #TelSatSetupMenuInfo_t contain all menu related information which are required like menu title, icon, item count, etc.
314 * @par Async Response Message:
318 * - When SAT SIM is inserted. we can get meaningful data. without SAT SIM, Null is returned
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)
327 * @par Prospective Clients:
330 * @see tel_select_sat_menu
333 * #include <ITapiSat.h>
335 * TelSatSetupMenuInfo_t menu; //this struct will be pull up with SIM menu info
336 * ret_status = tel_get_sat_main_menu_info(&menu);
343 /*================================================================================================*/
344 int tel_get_sat_main_menu_info(TapiHandle *handle, TelSatSetupMenuInfo_t *pMainMenu);
347 * @brief This API provides the Operation result(s) for the Proactive Command execution by the Application(s) to the Telephony Server.
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.
353 * This function makes Dbus method call to Telephony Sever and gets immediate feedback.
356 * Do not use this function. This function is dedicated to the SAT UI embedded application only.
358 * @par Sync (or) Async:
359 * This is a Synchronous API.
362 * - handle from tel_init().
364 * @param [out] pAppRetInfo
365 * - #TelSatAppsRetInfo_t contains execution result of a specific proactive command by application.
367 * @par Async Response Message:
371 * - Proactive Command execution request should be sent by Telephony Server to SAT related applications.
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)
380 * @par Prospective Clients:
381 * Embeded applications which are predefined by 3GPP TS31.111
386 * #include <ITapiSat.h>
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);
399 /*================================================================================================*/
400 int tel_send_sat_app_exec_result(TapiHandle *handle, TelSatAppsRetInfo_t *pAppRetInfo);
407 #endif /* _ITAPI_SAT_H_ */